diff --git a/AGENTS.md b/AGENTS.md
index ca17bc4a0a..3f3cd09350 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -31,7 +31,14 @@ Bun-native TypeScript with no separate server compile step.
 - `go/` — retired Go native-runtime experiment; kept only where the TypeScript
   runtime still references it. New work does not go here.
 - `structure/` — maintainer invariants and architecture notes; read before
-  changing shared subsystems.
+  changing shared subsystems. [`structure/INDEX.md`](./structure/INDEX.md) is the
+  reading order and the source-ownership table, and
+  [`structure/AGENTS.md`](./structure/AGENTS.md) holds the rules for changing
+  anything in there. Ownership is not advisory: changing an owned source area
+  obliges the same change to update its doc, and `bun run structure:check`
+  (wired into the suite by `tests/ci-workflows/structure-ssot.test.ts`) fails on a
+  doc that names a path this tree no longer has, on an invariant whose test is
+  gone, and on a new `src/` area nobody claimed.
 - `scripts/` — release and maintenance tooling; `scripts/release.ts` is the
   release authority.
 - `devlog/` — planning and investigation notes, tracked in this repository. See
@@ -187,6 +194,8 @@ bun run test:changed   # import-graph tests against the resolved `dev` merge bas
 bun run test           # full tests/ suite (PR-ready / explicit ask only)
 bun run lint:gui       # GUI eslint
 bun run privacy:scan   # credential/privacy scan used by CI
+bun run structure:check # structure/ doc-map, ownership, and invariant-binding gate
+bun run structure:index # regenerate structure/INDEX.md from structure/manifest.json
 bun run build:gui      # Vite GUI build
 ```
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 08db5a6bbb..ea36e08eb4 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -5,7 +5,7 @@ Thanks for helping with opencodex.
 - Start with the canonical guide: [Contributing](https://opencodex.me/contributing/)
 - Pull-request quality contract: [Review readiness and author responsibility](https://opencodex.me/contributing/pr-quality/)
 - Public user docs live in [`docs-site/`](./docs-site)
-- Current maintainer invariants live in [`structure/`](./structure)
+- Current maintainer invariants live in [`structure/`](./structure); start at [`structure/INDEX.md`](./structure/INDEX.md)
 - Maintainer roles and merge policy live in [`MAINTAINERS.md`](./MAINTAINERS.md)
 - Attribution for work landed through a maintainer carry lives in [`CREDITS.md`](./CREDITS.md)
 - Historical investigations live in [`docs/`](./docs)
diff --git a/devlog/_fin/260912_devin_cli_account_login/000_plan.md b/devlog/_fin/260912_devin_cli_account_login/000_plan.md
new file mode 100644
index 0000000000..ea736f4942
--- /dev/null
+++ b/devlog/_fin/260912_devin_cli_account_login/000_plan.md
@@ -0,0 +1,88 @@
+# Devin CLI as an account provider
+
+**Unit:** 260912_devin_cli_account_login
+**Class:** C3 (public provider contract + a documented invariant + GUI surface)
+**Goal (host):** register devin-cli as an account provider so it appears in the
+dashboard accounts tab beside devin, by giving it a login entry that drives the
+installed Devin CLI's own auth flow, without opencodex holding a usable Devin
+bearer token.
+
+## Why this unit exists
+
+The dashboard's add-provider dialog has three tabs. Two of them (Free, Paid) are
+rendered from the preset catalog; the Accounts tab is not. In
+`gui/src/components/provider-catalog/ProviderCatalog.tsx` the preset rows are
+drawn only when `tier !== "accounts"`, and the Accounts tab instead renders
+`accountRows`, which is built from providers that have a login flow. The
+`buckets.accounts` bucket that `bucketPresets` computes is never rendered at
+all.
+
+That is why `devin-cli` is reachable only under Free today: `authKind: "local"`
+makes `isFreeProvider` true (`gui/src/provider-workspace/catalog.ts`), the same
+branch that holds Ollama, vLLM and LM Studio. Reclassifying the tier alone would
+remove it from Free and put it in a bucket nothing draws, so it would vanish
+from the dialog entirely. The only way into the Accounts tab is to become a
+provider with a login.
+
+## The constraint this unit has to move
+
+`src/providers/registry.ts` and `tests/providers/devin-cli-adapter.test.ts`
+currently pin the opposite posture:
+
+> The installed CLI carries its own credentials from `devin auth login`, so this
+> provider takes no key and the proxy never sees a token for this provider.
+
+That statement is about the **request path**, and it stays true: the adapter
+spawns `devin acp` and the child authenticates itself. What changes is the
+**dashboard path**, which gains a login entry whose job is to run the CLI's own
+auth flow and read back who is signed in. The distinction the unit must keep
+explicit, in code comments and in the tests, is:
+
+- the adapter still never reads, requests, or forwards a credential at request time;
+- the OAuth entry stores an identity marker, never a usable Devin bearer token.
+
+If those two cannot both hold, the unit stops and reports rather than inventing a
+token to satisfy the framework.
+
+## Constraints
+
+- No repository-wide local suite, typecheck, or build. Focused tests only; hosted
+  CI on the exact PR head is the gate. Push with `--no-verify`.
+- The Devin CLI is **not installed** on the development machine and must not be
+  installed as part of this unit without a separate instruction. Every code path
+  that depends on the binary needs a documented degraded behaviour and a test
+  that exercises it through an injected spawn, the way
+  `tests/providers/devin-cli-adapter.test.ts` already drives the adapter.
+- `src/lab/` must stay off the core path; nothing here touches `src/router.ts`,
+  `src/server/lifecycle.ts`, or `src/server/responses/core.ts`.
+- Target branch is `dev`.
+
+## Work-phase map
+
+Dependency-ordered; each is one full PABCD cycle.
+
+| Phase | Doc | Outcome |
+|---|---|---|
+| wp1 | this unit | Roadmap locked, every later phase written to diff level |
+| wp2 | `010_phase1_cli_login.md` | `src/oauth/devin-cli.ts`: signed-in detection, login that drives the CLI, identity-only credential |
+| wp3 | `020_phase2_reclassify.md` | Registry + OAUTH_PROVIDERS registration, invariant text, tests that pinned `local` |
+| wp4 | `030_phase3_surface_and_land.md` | Accounts-tab proof against the running service, docs/locale, PR, merge |
+
+## Open risks carried into wp2
+
+1. **CLI absent.** Signed-in detection cannot be proven end to end on this
+   machine. wp2 must therefore make the binary lookup injectable and prove both
+   branches (found / not found) with the existing `resolveDevinCliBinary`
+   override seam, and wp4 must state plainly that the live signed-in path is
+   unproven here.
+2. **No documented status subcommand.** If the CLI exposes no non-interactive way
+   to report the signed-in account, the login entry can only report "the CLI
+   reports it is signed in" without an identity. That is still enough for an
+   accounts row, but it changes the credential shape, so wp2 decides this against
+   the subagent finding recorded in `001_cli_auth_survey.md` and amends
+   `010_` before building.
+3. **Refresh.** The OAuth framework expects a refresh path. `src/oauth/devin.ts`
+   throws `invalid_grant` because Cognition mints no refresh token; the CLI entry
+   has the same shape and should reuse that posture rather than extending an
+   expiry it cannot honour.
+
diff --git a/devlog/_fin/260912_devin_cli_account_login/001_cli_auth_survey.md b/devlog/_fin/260912_devin_cli_account_login/001_cli_auth_survey.md
new file mode 100644
index 0000000000..b513a2aeb5
--- /dev/null
+++ b/devlog/_fin/260912_devin_cli_account_login/001_cli_auth_survey.md
@@ -0,0 +1,82 @@
+# 001 — What the surfaces actually require
+
+Findings from three parallel read-only investigations (subagents Carson, Gibbs,
+Rawls), recorded here so each later phase starts from evidence rather than from
+the transcript.
+
+## The Accounts tab is fed by OAUTH_PROVIDERS, not by the preset catalog
+
+`GET /api/oauth/providers` returns `listOAuthProviders()`, which is
+`Object.keys(OAUTH_PROVIDERS)` minus `chatgpt`
+(`src/server/management/oauth-account-routes.ts:137-140`,
+`src/oauth/index.ts:335-371`). The GUI turns that list into the Accounts rows in
+`gui/src/pages/providers-page-utils.ts:8-25`. A provider does **not** need to be
+in `config.json` to appear. So membership in `OAUTH_PROVIDERS` is the whole
+admission rule.
+
+## What an OAuth entry must provide
+
+`OAuthProviderDef` (`src/oauth/index.ts:184-196`) requires `login`, `refresh`,
+`providerConfig`, `defaultModel`. `providerConfig` is not hand-written: `oauthConfig(id)`
+calls `deriveOAuthProviderConfig`, which finds the registry row **only when
+`authKind === "oauth"`** and throws otherwise (`src/providers/derive.ts:350-353`).
+That is why the registry reclassification and the OAuth registration are one
+atomic change, not two independent edits.
+
+`OAuthCredentials` requires `access: string`, `refresh: string`, `expires: number`;
+`normalizeCredential` drops the whole credential if any of the three is missing or
+mistyped (`src/oauth/store.ts:447-502`).
+
+## The durable-key precedent already exists
+
+`devin` faces the same "no refresh endpoint" problem and solves it without
+inventing one: it stores the durable key as both `access` and `refresh`, sets
+`expires: Number.MAX_SAFE_INTEGER`, declares `defaultRefreshPolicy: "disabled"`,
+and its `refresh` throws `invalid_grant` so a forced refresh marks the account
+`needsReauth` instead of pretending success (`src/oauth/devin.ts:50-72, 155-166`,
+`src/oauth/index.ts:310-315`). `orcarouter-oauth` does the same. An empty
+`refresh: ""` is explicitly the wrong shape — it makes `detectOAuthWarning` report
+`stale_credentials` from the moment of login.
+
+This unit reuses that shape, with one difference that has to stay visible: for
+`devin` the stored string is a real API key; for `devin-cli` it is a non-secret
+presence marker, because there is no token for opencodex to hold.
+
+## The fail-closed check that makes this a migration
+
+`src/server/auth-cors.ts:731-737` rejects a saved provider row whose
+`authMode === "local"` when its registry entry is not local:
+
+> `provider ${name} cannot use authMode "local" — its registry entry requires ${entry.authKind} auth`
+
+`derive.ts:217-231` seeds `authMode` from `authKind`, so every config saved while
+`devin-cli` was local carries `authMode: "local"`. Flipping the registry to
+`oauth` without a migration turns those configs into a startup rejection. This is
+the single highest-risk item in the unit and `020` owns it.
+
+## Everything else `"local"` currently controls for this provider
+
+From `gui/src/provider-workspace/`: `catalog.ts:137-143` treats local as
+configuration-ready; `catalog.ts:170-174` puts it in the Free tier;
+`auth.ts:21-22` returns `null` so no auth surface is drawn; `kind.ts:12-21`
+classifies it as kind `local` for the rail filter. Under `oauth` all four change
+behaviour, which is the intent — an OAuth row gets an auth surface and a login
+button — but `030` has to look at the rail, not only the modal.
+
+From `src/providers/`: `fastwire.ts:109` returns `"none"` for local, so no
+Authorization header is attached. This matters: the `devin-cli` adapter never
+travels the fetch path at all (`buildRequest` is a placeholder), so the header
+policy is inert for it either way. `quota.ts:2899` and `key-failover.ts` skip
+local rows; under `oauth` they take the OAuth branches, which is correct because
+there is now an account to reason about.
+
+## What the Devin CLI itself stores
+
+The CLI keeps its own credential on disk as `credentials.toml`. opencodex never
+reads it; the adapter only spawns `devin acp` and the child authenticates itself
+(`src/adapters/devin-cli/adapter.ts:1-8`). The CLI is **not installed** on this
+machine, so the exact path and any non-interactive status subcommand are
+unconfirmed. `010` therefore treats both the path and the status probe as
+injected dependencies with a proven not-found branch, and `030` states plainly
+that the live signed-in path is unproven here.
+
diff --git a/devlog/_fin/260912_devin_cli_account_login/002_audit_resolution.md b/devlog/_fin/260912_devin_cli_account_login/002_audit_resolution.md
new file mode 100644
index 0000000000..dc9e6f4ef5
--- /dev/null
+++ b/devlog/_fin/260912_devin_cli_account_login/002_audit_resolution.md
@@ -0,0 +1,101 @@
+# 002 — Audit resolution: the reclassification is the wrong mechanism
+
+Independent adversarial audit of `000`/`010`/`020`/`030` returned **VERDICT: FAIL**
+with four blockers. Three are fixable in place. The first invalidates the central
+decision, and the roadmap changes rather than arguing with it.
+
+## Blocker 1 (fatal to the original design)
+
+Flipping `authKind` to `oauth` couples the REQUEST path to a credential that
+carries no meaning. `src/router.ts:317-318` forces `authMode` from the registry
+for oauth entries, and `src/server/responses/core.ts:4323` then always calls
+`getValidAccessTokenSnapshot`, which throws `OAuthLoginRequiredError` when no
+account set exists (`src/oauth/index.ts:576-578`) and stamps
+`apiKey: resolved.accessToken` at `:4401`.
+
+Today a configured `devin-cli` row answers with no opencodex credential at all,
+because the child authenticates itself. Under the original plan every turn would
+401 until someone clicked Login, and a dashboard logout would break inference
+while the CLI stayed signed in. `020`'s boundary forbids touching
+`responses/core.ts`, so the plan could not have special-cased its way out.
+
+The audit also killed a claim in `000`: reclassifying does NOT make the row vanish.
+`providerTier` only puts the canonical OpenAI forward provider in `accounts`
+(`gui/src/provider-workspace/catalog.ts:160-181`), so an oauth preset with a
+non-loopback base URL lands in **Paid**, which is rendered. The original
+motivation sentence was wrong about the failure mode while being right that the
+Accounts tab is unreachable from the preset catalog.
+
+## The corrected mechanism
+
+Accounts-tab admission is `OAUTH_PROVIDERS` membership — `listOAuthProviders()`
+is `Object.keys(OAUTH_PROVIDERS)` minus `chatgpt`
+(`src/oauth/index.ts:369-371`, `src/server/management/oauth-account-routes.ts:139-140`).
+Nothing in that path reads `authKind`.
+
+`authKind: "oauth"` was only needed because `oauthConfig(id)` derives
+`providerConfig` through `deriveOAuthProviderConfig`, which filters on it
+(`src/providers/derive.ts:350-353`). But `providerConfig` is an ordinary
+`OcxProviderConfig` field — it can be built from the registry row directly.
+
+**So: register `devin-cli` in `OAUTH_PROVIDERS` and leave `authKind: "local"`
+alone.** The Accounts row appears; the request path keeps seeing a local
+provider, demands no token, and behaves exactly as it does today. The
+`auth-cors` migration in `020` and its whole new migration module become
+unnecessary, because no persisted `authMode` ever mismatches.
+
+This also resolves the honesty problem that made the original design
+uncomfortable: opencodex no longer needs a marker to stand in for a bearer
+token on the request path, because the request path never asks. The stored
+credential exists only so the Accounts row has a state to show.
+
+The residual risk moves to `isOAuthProvider("devin-cli")` becoming true, which
+switches on `ocx login` (`src/oauth/login-cli.ts:86-88`), changes `ocx account`
+(`src/cli/account-api.ts:83-93`), and admits the row to generic 429 failover
+(`src/oauth/generic-account-failover.ts:97-98`). wp2 must prove each of those
+three is either intended or inert for a stdio adapter, and `openUrl("")` in the
+CLI login path must not be reached.
+
+## Blocker 2 — preset duplication
+
+`dashboardPreset: true` keeps the row in `deriveProviderPresets`
+(`src/providers/derive.ts:365`), so it would show on a preset tab as well as
+Accounts. Set `dashboardPreset: false`, matching `devin` and `cursor`, and update
+the assertion at `tests/providers/devin-cli-adapter.test.ts:33` that currently
+pins it true. With `authKind` staying local the preset tab would otherwise be
+Free, not Paid, but the duplication is the same defect either way.
+
+## Blocker 3 — login cannot inherit stdio
+
+`010` said to run `devin auth login` with inherited stdio. Dashboard login is
+`POST /api/oauth/login` inside the proxy, typically a launchd process with no
+TTY. Use kiro's working shape instead: piped spawn with `stdin: "ignore"`
+(`src/oauth/kiro.ts:151-156`), surface the CLI's own output through
+`ctrl.onProgress`, and treat a login that cannot complete without a terminal as
+a reported failure rather than a hang. If the CLI turns out to require a TTY, the
+honest end state is an Accounts row that reports signed-in status and tells the
+operator to run `devin auth login` in their own terminal — wp2 decides this
+against the real binary and records which it was.
+
+## Blocker 4 — wrong label file
+
+Accounts rows use `oauthLabel` → `OAUTH_LABELS[id] ?? id`
+(`gui/src/pages/providers-shared.ts:49-59`), not `formatProviderDisplayName`.
+Without an `OAUTH_LABELS` entry the row reads `devin-cli`. `030`'s write set
+moves from `gui/src/provider-icons.ts` to `gui/src/pages/providers-shared.ts`.
+
+## Structure obligation the plan missed
+
+`structure/AGENTS.md:49` binds changes in `src/oauth/` and `src/providers/` to
+`runtime.md`, `subagents.md`, `transports/inventory.md`, and
+`providers/xai-grok.md`, not only `adapters/registry.md`. wp4 checks each for a
+sentence this change falsifies.
+
+## Effect on the work-phase map
+
+wp2 and wp3 swap emphasis: wp2 still builds `src/oauth/devin-cli.ts` (now with a
+piped spawn and no marker-as-bearer concern), wp3 becomes registration plus the
+`dashboardPreset` flip and the three `isOAuthProvider` consequences, with the
+`authKind` flip and its migration DELETED. wp4 is unchanged apart from the label
+file and the structure docs.
+
diff --git a/devlog/_fin/260912_devin_cli_account_login/003_blocker1_resolution.md b/devlog/_fin/260912_devin_cli_account_login/003_blocker1_resolution.md
new file mode 100644
index 0000000000..e91d181c5c
--- /dev/null
+++ b/devlog/_fin/260912_devin_cli_account_login/003_blocker1_resolution.md
@@ -0,0 +1,81 @@
+# 003 — Blocker 1 resolved: import-first login, oauth classification kept
+
+`002` proposed dodging the request-path coupling by leaving `authKind: "local"`
+and registering in `OAUTH_PROVIDERS` anyway. The operator rejected the premise:
+devin-cli is not a local runtime. It is a CLI that requires a vendor account —
+demonstrated by installing it and signing in, after which
+`devin auth status` reports `Logged in (via Devin)` with its credential at
+`~/.local/share/devin/credentials.toml`. Ollama, vLLM and LM Studio have no
+account at all; grouping devin-cli with them was a taxonomy error.
+
+So the classification is `oauth`, and blocker 1 has to be solved rather than
+avoided.
+
+## The resolution
+
+Blocker 1 said: with `authKind: "oauth"`, `src/router.ts:317-318` forces
+`authMode`, `src/server/responses/core.ts:4323` calls
+`getValidAccessTokenSnapshot`, and that throws `OAuthLoginRequiredError` when no
+account set exists.
+
+That is only a defect while no credential is stored. Once the login entry has
+run, a credential exists, the snapshot resolves, `apiKey` is stamped onto a
+provider config the adapter never reads, and the turn proceeds exactly as it does
+today. Requiring one sign-in before an account provider answers is not a
+regression — it is what an account provider means, and it is what the operator
+asked for.
+
+**No change to `core.ts` or `router.ts` is needed.** The boundary in `000` holds.
+
+> **Superseded in part by `020`.** Audit round 2 disproved the startup-import half
+> of this section: `projectStartupConfigRepairs` is a synchronous projector
+> persisted through `mutatePersistedConfig`, which writes `config.json` only,
+> while `getValidAccessTokenSnapshot` reads the auth store. A boot pass there
+> cannot mint a credential, so existing installs DO need one sign-in after
+> upgrade. `020` carries the corrected, honest version. The login-time
+> import-first design below stands unchanged; only the boot-import claim is dead.
+
+## What does have to be built: import-first, so nobody is broken mid-flight
+
+A user who has `devin-cli` configured today and is signed into the CLI must not
+wake up to 401s. Kiro already solves this shape (`src/oauth/kiro.ts:335-429`):
+login imports an existing CLI session rather than starting a browser flow.
+
+wp2 therefore builds `loginDevinCli` import-first:
+
+1. `devin auth status` — confirmed present and non-interactive on 3000.10.21,
+   printing `Logged in (via Devin).` plus the credential path. This is the probe;
+   the subcommand is no longer a guess (`001` recorded it as unconfirmed).
+2. already signed in -> return the marker credential immediately, no browser.
+3. signed out -> run `devin auth login` with kiro's piped-spawn shape
+   (blocker 3), surfacing the CLI's own `Visit <url> ... paste the code` prompt
+   through `ctrl.onAuth`/`onManualCodeInput` — that flow is confirmed: the CLI
+   prints a PKCE URL and accepts a pasted one-time code, which is exactly the
+   shape `onManualCodeInput` exists for.
+
+And wp3 adds a startup import for existing installs: when `devin-cli` is
+configured, has no stored credential, and `devin auth status` says signed in,
+store the marker so the first turn after upgrade succeeds without a click. Same
+repair pass as the other two migrations
+(`src/providers/model-rename-startup.ts`).
+
+## Blocker 2, 3, 4 — unchanged from `002`
+
+`dashboardPreset: false`; piped spawn; `OAUTH_LABELS` in
+`gui/src/pages/providers-shared.ts` is the Accounts label, not
+`provider-icons.ts`. The `로컬` badge disappears on its own once `auth` stops
+being `"local"` (`ProviderCatalog.tsx` badge ladder), which is the mark the
+operator asked to have removed.
+
+## Corrections to earlier docs from the live install
+
+- credential path is `$XDG_DATA_HOME/devin/credentials.toml`
+  (`~/.local/share/devin/...`), not `~/.config`. `010`'s path resolver changes.
+- `devin auth status` exists and is non-interactive. `010`'s "unconfirmed
+  subcommand" hedge is replaced by a real probe, and its test case 4 becomes a
+  regression guard rather than a guess.
+- A separate live defect was found and already landed on `dev` outside this unit:
+  the adapter passed `DEVIN_PERMISSION_MODE=ask`, which the CLI rejects with exit
+  2, so every default-configuration turn failed (PR #4332, `e7f7487b3d`). This
+  unit assumes that fix is present.
+
diff --git a/devlog/_fin/260912_devin_cli_account_login/004_live_cli_probe.md b/devlog/_fin/260912_devin_cli_account_login/004_live_cli_probe.md
new file mode 100644
index 0000000000..7daa74d82d
--- /dev/null
+++ b/devlog/_fin/260912_devin_cli_account_login/004_live_cli_probe.md
@@ -0,0 +1,63 @@
+# 004 — Live probe of the installed CLI
+
+Devin CLI 3000.10.21 installed to `~/.local/bin/devin` and signed in, so the
+guesses `001` recorded as unconfirmed are now measured. Everything below is
+observed output, not documentation.
+
+## `devin auth status`
+
+Exists, non-interactive, exit 0 when signed in:
+
+```
+$ devin auth status
+Logged in (via Devin).
+
+Credentials:
+  File:              /Users/jun/.local/share/devin/credentials.toml
+  API server:        https://server.codeium.com
+  Devin webapp:      https://app.devin.ai
+  Devin API:         https://api.devin.ai
+$ echo $?
+0
+```
+
+Signed out, before login, it printed `Not logged in.` with the same credentials
+path and a hint to run `devin auth login`.
+
+**No `--json`.** `devin auth status --json` fails with
+`error: unexpected argument '--json' found`. `010`'s probe must therefore parse
+exit status plus the literal prefix `Logged in`, not a JSON field. Parsing prose
+is fragile, so the probe treats exit 0 as authoritative and the prose only as a
+tiebreaker, and the `010` test set gains a case for a future wording change.
+
+## No identity to report
+
+`credentials.toml` holds four keys and none of them is an account identity:
+
+```
+windsurf_api_key = <redacted>
+api_server_url   = <redacted>
+devin_webapp_host = <redacted>
+devin_api_url    = <redacted>
+```
+
+Neither does `auth status`. So the credential this unit stores carries **no**
+`email` and **no** `accountId`. Two consequences `020` must handle:
+
+1. The Accounts row shows a signed-in state without an address. That is honest and
+   matches what the CLI itself can say.
+2. `saveCredential` upserts by `accountId ?? email`, so an identity-less
+   credential replaces the active slot rather than adding one
+   (`src/oauth/store.ts:735-818`). Multi-account is therefore out of scope for
+   this provider, and `020` should say so rather than leave a half-working
+   "Add account" button implying otherwise.
+
+## The file confirms the boundary this unit promised to keep
+
+`windsurf_api_key` is a real credential sitting in the CLI's own file. opencodex
+must not read it — doing so would turn "the CLI owns its credential" into a lie
+and would give the proxy a Cognition key it has no reason to hold. The probe
+checks **presence and exit status only**, never contents. `010`'s
+`readDevinCliSignedInState` is written that way and its test asserts no file
+bytes are read.
+
diff --git a/devlog/_fin/260912_devin_cli_account_login/005_cli_key_is_a_real_credential.md b/devlog/_fin/260912_devin_cli_account_login/005_cli_key_is_a_real_credential.md
new file mode 100644
index 0000000000..79e744b54a
--- /dev/null
+++ b/devlog/_fin/260912_devin_cli_account_login/005_cli_key_is_a_real_credential.md
@@ -0,0 +1,83 @@
+# 005 — The CLI credential is an ordinary Cognition key
+
+This invalidates the mechanism the whole unit was built on, so it is recorded
+before anything else changes.
+
+## What was measured
+
+`~/.local/share/devin/credentials.toml` holds `windsurf_api_key` and
+`api_server_url`. Feeding those two straight into the EXISTING cloud-direct
+client:
+
+```
+host: https://server.codeium.com
+key shape: devin-session-token$ey...(189 chars)
+user_jwt minted: true
+catalog HTTP: 200
+models in catalog: 229 enabled: 229
+```
+
+and then a real turn through `streamChatEvents`:
+
+```
+REPLY: "CLIKEY-OK"
+```
+
+The CLI's key is a `devin-session-token$<JWT>` — byte-for-byte the same shape
+`src/oauth/devin/types.ts` already documents for the Cognition era, and the same
+shape `ocx login devin` obtains through RegisterUser. It mints a `user_jwt`, it
+opens the full 229-model catalog, and it streams chat over
+`exa.api_server_pb.ApiServerService/GetChatMessage`.
+
+## Why that ends the argument the unit was having
+
+Every blocker the three audit rounds produced was downstream of one decision: that
+`devin-cli` has no credential opencodex may hold, so an account row would have to
+be faked with a marker.
+
+That premise is false. There is a real credential, in a file the CLI writes, in
+the format the proxy already parses.
+
+With a real token:
+
+- the marker disappears, and with it the "anything that treats this as a bearer is
+  a bug" caveat the first audit round correctly called already-false;
+- `authKind: "oauth"` is honest rather than a classification trick — the request
+  path resolves a genuine key and uses it;
+- blocker 1 evaporates: `getValidAccessTokenSnapshot` returns a working token, so
+  there is no 401-until-you-click and no upgrade story to apologise for;
+- blocker 3 evaporates: login is a file read, not an interactive paste, so the
+  `stdin` design that three rounds could not get right is not needed at all.
+  `spawnInteractive` and `DevinCliLoginChild` are deleted.
+
+This is exactly kiro's import-first shape, and now with the same substance:
+kiro imports a real token from an installed CLI's own store, and so does this.
+
+## The direction change
+
+**Before:** `devin-cli` drives `devin acp` over stdio; opencodex holds nothing;
+an account row needs a marker.
+
+**After:** `devin-cli` imports the CLI's key and routes through the cloud-direct
+Connect-RPC transport the `devin` adapter already owns.
+
+LOOP-CONTINUITY-01 requires a reason for changing direction. The reason is
+measured, above: the ACP route was chosen when the credential was believed
+unreachable, and it is not.
+
+What is genuinely given up: ACP runs Devin's own agent loop in the child, with its
+own tools and permissions. The cloud route is plain inference. For a proxy whose
+job is to expose a model to Codex and Claude Code, plain inference is the correct
+surface — the local agent loop was never the thing being exposed, and it is what
+produced the `--permission-mode` defect already fixed on `dev` (PR #4332).
+
+## What the unit becomes
+
+wp2 shrinks to a credential importer. wp3 keeps the `authKind` flip and
+`dashboardPreset: false`, and additionally repoints the adapter. wp4 is unchanged
+apart from describing the new transport.
+
+The phase documents are rewritten in `011`, `021`, `031`; `010`/`020`/`030` stay
+in place as the superseded record of the ACP design, because the audit trail that
+killed it is worth keeping.
+
diff --git a/devlog/_fin/260912_devin_cli_account_login/006_prior_art.md b/devlog/_fin/260912_devin_cli_account_login/006_prior_art.md
new file mode 100644
index 0000000000..a85cd46437
--- /dev/null
+++ b/devlog/_fin/260912_devin_cli_account_login/006_prior_art.md
@@ -0,0 +1,84 @@
+# 006 — Prior art: how everyone else uses this credential
+
+Survey of public implementations, to check that `005`'s direction is the one the
+ecosystem converged on rather than a local guess.
+
+## There is no OpenAI-shaped Devin API to point at
+
+No repo, and no Cognition page, exposes `POST /v1/chat/completions` that accepts a
+`devin-session-token`. `api.devin.ai` is a different product: cloud Devin
+**sessions** (`/v1/sessions`, `/v3/organizations/{org}/sessions`) authenticated
+with `cog_` service keys, which creates an agent VM rather than returning a
+completion.
+
+Every client that wanted an OpenAI surface built the translator itself, in front
+of Connect-RPC. That is exactly what opencodex already is, so the question
+"can we use it as an API instead of ACP" resolves to "yes, over the transport the
+`devin` adapter already owns."
+
+## The convergent pattern
+
+1. obtain a `devin-session-token$<JWT>` — by RegisterUser, by CLI OAuth, or by
+   reading it from disk;
+2. send it as Metadata `api_key` to `api_server_url`, default
+   `https://server.codeium.com` — **not** `api.devin.ai`;
+3. chat over `exa.api_server_pb.ApiServerService/GetChatMessage`;
+4. list models over `GetCascadeModelConfigs` (or `GetCliModelConfigs`), optionally
+   minting a `user_jwt` first.
+
+Implementations reviewed at source level: `rsvedant/opencode-windsurf-auth` (the
+70-star original opencodex's cloud-direct client is derived from, MIT notice in
+`index.ts`), its live fork `sudokar/opencode-devin-bridge`, `ktappdev/pi-windsurf`,
+`CaiJingLong/devin-gateway`, `leookun/devin-2api`, `dwgx/WindsurfAPI` (2978 stars,
+its `DEVIN_CONNECT=1` path), and `can1357/oh-my-pi`'s first-class Devin provider.
+
+Two divergences worth knowing, neither blocking:
+
+- `CaiJingLong/devin-gateway` lists models with **`GetCliModelConfigs`** rather
+  than `GetCascadeModelConfigs`. opencodex's existing catalog path works against
+  this account (229 models, measured in `005`), so no change; recorded in case a
+  future account type answers only the CLI variant.
+- `oh-my-pi` calls **`AssignModel`** before chatting. opencodex does not and
+  streams fine, so it is not required for this surface.
+
+## Nobody else reads the CLI file for chat — and that is fine
+
+The repos that parse `credentials.toml` are usage monitors:
+`wakamex/devin-cli-usage` (`windsurf_api_key` + `api_server_url` →
+`SeatManagementService/GetUserStatus`), `robinebers/openusage`, and
+`SammySnake-d/fast-context-mcp`. The chat clients each mint or store their own
+token instead.
+
+So `011` is a new combination rather than a copied one: read the file the usage
+tools read, then use it on the transport the chat clients use. Both halves are
+independently attested, and `005` measured the join end to end. The reason nobody
+published this combination is likely that the other projects are not already
+holding a working cloud-direct client — opencodex is.
+
+## Key names confirmed by independent sources
+
+Cognition documents only that the CLI "stores your API token" in
+`credentials.toml` and never names the keys. Three unrelated projects observe the
+same two that matter:
+
+| key | role |
+|---|---|
+| `windsurf_api_key` | the durable credential, `devin-session-token$<JWT>` |
+| `api_server_url` | Cognition api-server; where GetChatMessage goes |
+
+`devin_webapp_host` and `devin_api_url` are the webapp and the session-REST
+product; `011` reads neither.
+
+Token shapes in circulation: `devin-session-token$…` (current), `sk-ws-01-…`
+(older Windsurf RegisterUser), `cog_…` (official Devin session API — different
+product), `auth1_…` (web auth, not accepted as an api_key). `011`'s parser takes
+the value verbatim and lets the server judge it, which is the right posture given
+that spread.
+
+## Licensing note
+
+opencodex's `cloud-direct/` already carries the MIT attribution to
+`rsvedant/opencode-windsurf-auth` in `index.ts`. `011` adds no new derived code —
+it reads a local file and calls modules already in this tree — so no further
+attribution is owed.
+
diff --git a/devlog/_fin/260912_devin_cli_account_login/007_reference_proxy_corroboration.md b/devlog/_fin/260912_devin_cli_account_login/007_reference_proxy_corroboration.md
new file mode 100644
index 0000000000..0d7d1aac0d
--- /dev/null
+++ b/devlog/_fin/260912_devin_cli_account_login/007_reference_proxy_corroboration.md
@@ -0,0 +1,39 @@
+# 007 — Independent corroboration from a working Devin CLI proxy
+
+A second reference implementation was supplied by the operator
+(`server (1).mjs`, 851 lines, "Devin CLI proxy: OpenAI-compatible /v1 API backed
+by `devin acp`"). It is an ACP proxy, so it is not the transport this unit
+chose — but it independently confirms the credential half of `011`.
+
+## Same path, same key, same parse
+
+```js
+// server (1).mjs:173-176
+? join(process.env.APPDATA ?? join(homedir(), "AppData", "Roaming"), "devin", "credentials.toml")
+: join(process.env.XDG_DATA_HOME ?? join(homedir(), ".local", "share"), "devin", "credentials.toml"));
+...
+return readFileSync(path, "utf8").match(/windsurf_api_key\s*=\s*"([^"]+)"/)?.[1] ?? null;
+```
+
+That is the resolver `011` specifies, arrived at independently: `%APPDATA%` on
+Windows, `$XDG_DATA_HOME ?? ~/.local/share` elsewhere, and a line match for
+`windsurf_api_key` rather than a TOML dependency. Three sources now agree on the
+path and key name — this file, `wakamex/devin-cli-usage`, and the live probe in
+`004` — so `011`'s parser is not a guess.
+
+Its `readFileSync(...).match(...) ?? null` also returns null rather than throwing
+on a missing file, which is the shape `011` uses for
+`readDevinCliCredentialFile`.
+
+## What it does NOT corroborate
+
+It reads the key and then still spawns `devin acp` (`:329`), keeping one live
+child per session and compacting inside it. So it is evidence for where the
+credential lives, not for what to do with it. `005` is the evidence that the same
+key works directly against `server.codeium.com`, which this proxy never tries.
+
+Worth noting for anyone comparing: an ACP proxy inherits the CLI's agent loop and
+its per-session process, which is what makes session lifecycle, compaction and
+`--permission-mode` its own problem — the same class of defect PR #4332 fixed in
+opencodex's ACP adapter. The cloud route has none of that surface.
+
diff --git a/devlog/_fin/260912_devin_cli_account_login/010_phase1_cli_login.md b/devlog/_fin/260912_devin_cli_account_login/010_phase1_cli_login.md
new file mode 100644
index 0000000000..1aef9e65cb
--- /dev/null
+++ b/devlog/_fin/260912_devin_cli_account_login/010_phase1_cli_login.md
@@ -0,0 +1,158 @@
+# 010 — Phase 1: the Devin CLI login entry
+
+**Work-phase:** wp2. **Write set:** `src/oauth/devin-cli.ts` (NEW),
+`tests/providers/devin-cli-login.test.ts` (NEW). Nothing else.
+
+Rewritten after audit rounds 1 and 2. Superseded guidance from the first draft:
+inherited stdio (audit blocker 3) and an `XDG_CONFIG_HOME` credential path
+(wrong, measured in `004`).
+
+## NEW `src/oauth/devin-cli.ts`
+
+```ts
+/**
+ * Devin CLI account login.
+ *
+ * The installed CLI owns its own credential. It writes
+ * \`$XDG_DATA_HOME/devin/credentials.toml\` — measured, not assumed — and that file
+ * holds a real \`windsurf_api_key\`. opencodex deliberately never reads it: the
+ * whole point of this provider is that the child authenticates itself, and
+ * lifting that key would hand the proxy a Cognition credential it has no reason
+ * to hold.
+ *
+ * What this module produces is an ACCOUNT ROW. The dashboard Accounts tab is
+ * built from OAUTH_PROVIDERS, so a provider absent from that map cannot appear
+ * there however it is classified. The stored \`access\` is the marker below — a
+ * non-secret constant, present because normalizeCredential drops any credential
+ * whose \`access\` is not a string. It is never a bearer token: the devin-cli
+ * adapter is runTurn-only, ignores provider.apiKey, and sends empty headers.
+ */
+export const DEVIN_CLI_SESSION_MARKER = "devin-cli-local-session";
+```
+
+### `devinCliCredentialsPath(env, platform)`
+
+Measured layout (`004`), not the config dir:
+
+- override `OPENCODEX_DEVIN_CLI_CREDENTIALS` (absolute only)
+- Windows `%APPDATA%/devin/credentials.toml`
+- otherwise `${XDG_DATA_HOME ?? ~/.local/share}/devin/credentials.toml`
+
+Used for a presence check only; the bytes are never read.
+
+### `readDevinCliSignedInState(deps)`
+
+```ts
+export interface DevinCliLoginDeps {
+  resolveBinary?: () => string | undefined;
+  credentialsPath?: () => string;
+  exists?: (path: string) => boolean;
+  /** Fire-and-wait. Enough for the `auth status` probe, which takes no input. */
+  run?: (bin: string, args: string[]) => Promise<{ code: number; stdout: string; stderr: string }>;
+  /**
+   * Interactive spawn, required for `auth login`.
+   *
+   * `run` cannot express that flow and an earlier draft wrongly reused it: the
+   * login child must receive a one-time code AFTER it has printed a URL, so the
+   * caller needs a live stdin handle and an incremental stdout stream, not a
+   * buffered result. The audit caught the draft specifying both kiro's
+   * `stdin: "ignore"` and a paste into that same child.
+   */
+  spawnInteractive?: (bin: string, args: string[]) => DevinCliLoginChild;
+}
+export interface DevinCliLoginChild {
+  /** Called with each chunk of stdout/stderr as it arrives. */
+  onOutput(listener: (chunk: string) => void): void;
+  /** Writes the pasted code; the implementation appends the newline. */
+  writeLine(text: string): void;
+  /** Resolves with the exit code. */
+  wait(): Promise<number>;
+  /** Terminates the child and its group, for the deadline path. */
+  kill(): void;
+}
+export interface DevinCliSignedInState { signedIn: boolean; reason?: "not-installed" | "signed-out" }
+```
+
+1. binary missing -> `{ signedIn: false, reason: "not-installed" }`
+2. `devin auth status` — confirmed present and non-interactive. **Exit code is
+   authoritative**; there is no `--json` (`devin auth status --json` fails with
+   `unexpected argument`), so the prose is only a tiebreaker when the exit code
+   is ambiguous. Exit 0 -> signed in.
+3. non-zero exit but the credential file exists -> signed in, so a future wording
+   or exit-code change degrades to the file check instead of locking the user out
+4. otherwise `{ signedIn: false, reason: "signed-out" }`
+
+No `identity` field. `004` measured that neither `auth status` nor
+`credentials.toml` exposes an account address, so inventing one would be a lie.
+
+### `loginDevinCli(ctrl, opts, deps)`
+
+1. binary missing -> throw with `DEVIN_CLI_INSTALL_HINT` reused verbatim from
+   `src/adapters/devin-cli/binary.ts`.
+2. signed in and `!opts?.forceLogin` -> return the credential; import-first, no
+   browser, the kiro shape.
+3. signed out -> `spawnInteractive(bin, ["auth", "login"])` with **all three
+   streams piped**: `stdio: ["pipe", "pipe", "pipe"]`.
+
+   Kiro's runner uses `stdin: "ignore"` (`src/oauth/kiro.ts:151-156`) and an
+   earlier draft of this document copied it. That is wrong here, and the audit
+   caught it: kiro's CLI completes on its own and kiro then imports the token,
+   whereas this flow has to hand a one-time code BACK to the child. With stdin
+   ignored the child waits for a paste that can never arrive and the login hangs
+   until the deadline. Inheriting the proxy's stdio is equally wrong for the
+   opposite reason — dashboard login is `POST /api/oauth/login` inside a launchd
+   process with no TTY.
+
+   So: piped stdin to write the code, piped stdout **and stderr** to find the
+   prompt. Measured shape of that prompt (`004`):
+   `Visit https://app.devin.ai/auth/cli/continue?...&cli_pkce_marker=1 to sign in, then copy the code and paste it below.`
+   Scrape the URL, hand it to `ctrl.onAuth({ url, instructions })`, take the code
+   from `ctrl.onManualCodeInput()`, and write it to stdin followed by a newline.
+   The CLI answers `Login successful! Credentials stored.` on success.
+4. If no URL appears within the deadline, abort the child and throw a message
+   naming the manual path: run `devin auth login` in a terminal, then press Login
+   again — the import-first branch will pick it up.
+
+Returns:
+
+```ts
+{
+  access: DEVIN_CLI_SESSION_MARKER,
+  refresh: DEVIN_CLI_SESSION_MARKER,
+  expires: Number.MAX_SAFE_INTEGER,
+  source: "local-cli",
+}
+```
+
+No `email`/`accountId` (see `004`). Marker duplicated and a MAX expiry, matching
+the `devin` durable-key shape; `refresh: ""` would trip `detectOAuthWarning`.
+
+### `refreshDevinCliToken()`
+
+Throws `invalid_grant: the Devin CLI owns its own session. Run devin auth login again.`
+
+## NEW `tests/providers/devin-cli-login.test.ts`
+
+Registered in `scripts/test-layout/layout.json` and
+`tests/fixtures/test-layout-expected.json` under `providers`.
+
+1. binary absent -> login throws, message carries the install hint
+2. `auth status` exit 0 -> signed in; credential is marker/marker/MAX, carries no
+   email or accountId, and `exists` was never called on the credential file
+   contents (presence only)
+3. `auth status` non-zero but file present -> still signed in (wording-change guard)
+4. `auth status` non-zero and no file -> signed out
+5. signed out + login -> `spawnInteractive` receives `["auth","login"]`, the fake
+   child emits the measured `Visit <url> ...` line, that URL reaches `onAuth`, and
+   the code from `onManualCodeInput` arrives at `writeLine`. Asserts the child is
+   never handed the proxy's own streams
+8. a login whose stdin is not writable fails loudly rather than hanging — the
+   regression guard for the `stdin: "ignore"` mistake this phase already made once
+6. login producing no URL before the deadline -> throws naming the terminal fallback
+7. `refreshDevinCliToken` rejects with `invalid_grant`
+
+## Acceptance
+
+- No import from `src/router.ts`, `src/server/lifecycle.ts`, `src/server/responses/core.ts`.
+- `bun test tests/providers/devin-cli-login.test.ts` green.
+- `src/adapters/devin-cli/` untouched in this phase.
diff --git a/devlog/_fin/260912_devin_cli_account_login/011_phase1_credential_import.md b/devlog/_fin/260912_devin_cli_account_login/011_phase1_credential_import.md
new file mode 100644
index 0000000000..26783c266f
--- /dev/null
+++ b/devlog/_fin/260912_devin_cli_account_login/011_phase1_credential_import.md
@@ -0,0 +1,221 @@
+# 011 — Phase 1 (revised): import the CLI's credential
+
+**Supersedes `010`.** `005` measured that the Devin CLI stores a real Cognition
+key, so this phase is a file import, not an interactive login.
+
+**Work-phase:** wp2. **Write set:** `src/oauth/devin-cli.ts` (NEW), `src/oauth/devin.ts` (export
+`identityFromApiKey`, add the `providerId` parameter), `src/adapters/devin.ts`
+(consume it), `src/adapters/registry.ts` + `src/server/adapter-resolve.ts` +
+`src/server/responses/core.ts` (thread `providerId`),
+`tests/providers/devin-cli-login.test.ts` (NEW).
+
+## NEW `src/oauth/devin-cli.ts`
+
+```ts
+/**
+ * Devin CLI credential import.
+ *
+ * The installed CLI writes \`$XDG_DATA_HOME/devin/credentials.toml\` after
+ * \`devin auth login\`, and the \`windsurf_api_key\` in it is an ordinary
+ * \`devin-session-token$<JWT>\` — the same shape RegisterUser returns for
+ * \`ocx login devin\`, and the same one the cloud-direct client already speaks.
+ * Measured: it mints a user_jwt, opens the 229-model catalog, and streams chat.
+ *
+ * So this is kiro's import-first login with the same substance: read a signed-in
+ * local CLI's own store and adopt the token, rather than starting a browser flow
+ * the CLI has already completed.
+ */
+```
+
+### `devinCliCredentialsPath(env, platform)`
+
+- override `OPENCODEX_DEVIN_CLI_CREDENTIALS` (absolute only)
+- Windows `%APPDATA%/devin/credentials.toml`
+- otherwise `${XDG_DATA_HOME ?? ~/.local/share}/devin/credentials.toml`
+
+Measured in `004`. Not the config dir.
+
+### `readDevinCliCredentialFile(deps)`
+
+Parses only the two keys it needs, with a minimal line matcher rather than a TOML
+dependency — the file is flat and adding a parser for four keys is not worth it:
+
+```
+windsurf_api_key = "devin-session-token$..."
+api_server_url   = "https://server.codeium.com"
+```
+
+Returns `{ apiKey, apiServerUrl }` or `undefined` when the file is absent or
+either key is missing. **Never logs either value.**
+
+### `loginDevinCli(ctrl, opts, deps)`
+
+1. file missing or unparseable -> throw, message naming
+   `DEVIN_CLI_INSTALL_HINT` plus "run `devin auth login`, then press Login again".
+   No browser is ever opened: there is nothing for opencodex to authorize.
+2. `resolveDevinApiBaseUrl(apiServerUrl)` — reuse
+   `src/oauth/devin/api-base.ts` verbatim. The host comes off disk and then
+   receives the key, so it passes the same allowlist as the RegisterUser host.
+   An unallowlisted value falls back to the default rather than exfiltrating.
+3. Return the credential, reusing the newly exported `identityFromApiKey` from
+   `src/oauth/devin.ts` so an email or sub in the JWT becomes the account identity:
+
+```ts
+{
+  access: apiKey,
+  refresh: apiKey,          // durable-key pattern; "" trips detectOAuthWarning
+  expires: Number.MAX_SAFE_INTEGER,
+  source: "local-cli",
+  apiBaseUrl: resolvedHost,
+  ...identityFromApiKey(apiKey),
+}
+```
+
+`ctrl.onProgress?.("Imported the signed-in Devin CLI session.")`; `onAuth` is
+never called, which is the shape `startLoginFlow` already handles for local
+imports.
+
+### MODIFY `src/oauth/devin.ts` — make host resolution provider-aware
+
+The import stores `apiBaseUrl`, but nothing reads it. `createDevinAdapter` calls
+`resolveDevinApiServer(provider.baseUrl)` (`src/adapters/devin.ts:219`), and that
+helper is hard-coded to one credential:
+
+```ts
+// src/oauth/devin.ts:26-31 — today
+export function resolveDevinApiServer(configuredBaseUrl?: string): string {
+  return (
+    validateDevinApiBaseUrl(getCredential("devin")?.apiBaseUrl) ??
+    validateDevinApiBaseUrl(configuredBaseUrl) ??
+    DEVIN_DEFAULT_API_SERVER
+  );
+}
+```
+
+Left alone, a `devin-cli`-only user is pinned to the default host regardless of
+what their CLI recorded, and a user signed into both providers would send the CLI
+key to whatever tenant the browser-login `devin` credential named — an EU or
+FedStart account crossed with a US one. Two accounts, one host.
+
+```diff
+-export function resolveDevinApiServer(configuredBaseUrl?: string): string {
++export function resolveDevinApiServer(configuredBaseUrl?: string, providerId = "devin"): string {
+   return (
+-    validateDevinApiBaseUrl(getCredential("devin")?.apiBaseUrl) ??
++    validateDevinApiBaseUrl(getCredential(providerId)?.apiBaseUrl) ??
+     validateDevinApiBaseUrl(configuredBaseUrl) ??
+     DEVIN_DEFAULT_API_SERVER
+   );
+ }
+```
+
+### The adapter has no provider id today — this is the plumbing
+
+An earlier draft said "the adapter passes the provider it was built for" without
+checking that it can. It cannot: `createDevinAdapter` receives only
+`OcxProviderConfig`, which has no id, and after the flip both `devin` and
+`devin-cli` share `adapter: "devin"`, so the factory cannot infer the store key.
+The audit was right that the edit was unimplementable as written.
+
+The name IS available at the call sites — `route.providerName` at
+`src/server/responses/core.ts:1436` and `:4171` — so it only has to be threaded:
+
+```diff
+ // src/adapters/registry.ts
+ export interface AdapterFactoryContext {
+   cacheRetention?: AdapterCacheRetention;
++  /**
++   * The configured provider row this adapter serves. Needed when one adapter
++   * backs two provider ids whose credentials differ — `devin` and `devin-cli`
++   * share a transport and a token format but sign in to different accounts and
++   * can sit on different tenants.
++   */
++  providerId?: string;
+ }
+```
+
+```diff
+ // src/server/adapter-resolve.ts
+-export function resolveAdapter(providerConfig: OcxProviderConfig, cacheRetention?: "none" | "short" | "long") {
+-  return createRegisteredAdapter(providerConfig, { cacheRetention });
++export function resolveAdapter(
++  providerConfig: OcxProviderConfig,
++  cacheRetention?: "none" | "short" | "long",
++  providerId?: string,
++) {
++  return createRegisteredAdapter(providerConfig, { cacheRetention, ...(providerId ? { providerId } : {}) });
+ }
+```
+
+Both `core.ts` call sites pass `route.providerName`. The parameter is optional and
+every other adapter ignores it, so no existing behaviour moves. This touches
+`core.ts` but does not make it reach `src/lab/`, which is the boundary `000` set.
+
+`createDevinAdapter(provider, context)` then resolves with
+`context.providerId ?? "devin"`, preserving today's behaviour for any caller that
+does not supply one.
+
+One easily-missed hop, flagged by the final audit: the registry factory currently
+drops the context on the floor, so the field would arrive nowhere.
+
+```diff
+ // src/adapters/registry.ts
+   devin: {
+     wire: "devin",
+     mutation: "codex-owned",
+-    create: (provider: OcxProviderConfig, _context: AdapterFactoryContext) => createDevinAdapter(provider),
++    create: (provider: OcxProviderConfig, context: AdapterFactoryContext) => createDevinAdapter(provider, context),
+   },
+```
+
+`createRegisteredAdapter` already forwards `context` to `definition.create`, so
+this one line is the whole remaining gap. Test 9 fails without it, which is the
+point of routing that test through the factory.
+
+`identityFromApiKey` is likewise private at `src/oauth/devin.ts:45`; export it
+rather than copying the JWT decode into a second file.
+
+### `refreshDevinCliToken()`
+
+Throws `invalid_grant: the Devin CLI owns this session. Run devin auth login again.`
+Same posture as `refreshDevinToken`.
+
+### What is deleted relative to `010`
+
+`DEVIN_CLI_SESSION_MARKER`, `spawnInteractive`, `DevinCliLoginChild`, the PKCE
+URL scraper, and the deadline path. None of them has a reason to exist once the
+credential is readable.
+
+## NEW `tests/providers/devin-cli-login.test.ts`
+
+Registered in `scripts/test-layout/layout.json` and
+`tests/fixtures/test-layout-expected.json` under `providers`.
+
+1. file absent -> throws, message carries the install hint
+2. file present -> credential is `access === refresh === <key>`,
+   `expires === Number.MAX_SAFE_INTEGER`, `source === "local-cli"`
+3. identity: a key whose JWT carries an email surfaces it; one without does not
+   invent one
+4. `api_server_url` pointing at a non-Cognition host -> falls back to
+   `DEVIN_DEFAULT_API_SERVER`, and the off-allowlist host never reaches the
+   credential
+5. malformed file (missing `windsurf_api_key`) -> throws rather than returning a
+   half credential
+6. neither the key nor the host appears in anything passed to `onProgress`
+7. `refreshDevinCliToken` rejects with `invalid_grant`
+8. `resolveDevinApiServer(undefined, "devin-cli")` returns the host stored on the
+   devin-cli credential and does NOT read the `devin` credential
+9. **through the adapter, not only the helper**: build the adapter with
+   `createRegisteredAdapter(devinRow, { providerId: "devin-cli" })` while a
+   `devin` credential names a different allowlisted tenant, and assert the RPC
+   host is the CLI one. A green helper test alone would not have caught the
+   crossed-tenant bug, which is exactly what the audit said
+
+## Acceptance
+
+- No import from `src/router.ts`, `src/server/lifecycle.ts`, `src/server/responses/core.ts`.
+- `bun test tests/providers/devin-cli-login.test.ts` green.
+- A live import against this machine's signed-in CLI yields a credential that
+  streams a real turn — the `CLIKEY-OK` probe in `005`, repeated through the
+  module rather than through a scratch script.
+
diff --git a/devlog/_fin/260912_devin_cli_account_login/020_phase2_reclassify.md b/devlog/_fin/260912_devin_cli_account_login/020_phase2_reclassify.md
new file mode 100644
index 0000000000..857a6d074a
--- /dev/null
+++ b/devlog/_fin/260912_devin_cli_account_login/020_phase2_reclassify.md
@@ -0,0 +1,127 @@
+# 020 — Phase 2: reclassify local to oauth
+
+**Work-phase:** wp3. **Write set:** `src/providers/registry.ts`,
+`src/oauth/index.ts`, `src/providers/devin-cli-authmode-migration.ts` (NEW),
+`src/providers/model-rename-startup.ts`, `src/adapters/devin-cli/adapter.ts`
+(comment only), `tests/providers/devin-cli-adapter.test.ts`, NEW migration test.
+
+Rewritten after audit rounds 1 and 2. Folded: `dashboardPreset: false` (blocker
+2, missing from the first draft) and the honest upgrade story (blocker 1).
+
+Atomic: `oauthConfig("devin-cli")` throws unless the registry row already says
+`authKind: "oauth"` (`src/providers/derive.ts:350-353`), so the registry edit and
+the OAUTH_PROVIDERS entry land in one commit.
+
+## MODIFY `src/providers/registry.ts`
+
+```diff
+-    // Drives the locally installed Devin CLI. The CLI owns its own credentials
+-    // from `devin auth login`, so this provider takes no key and the proxy never
+-    // holds one. Inference happens in the child process, which is why the
+-    // destination is a stdio scheme rather than a URL.
++    // Drives the locally installed Devin CLI. The CLI owns its own credential and
++    // authenticates itself inside the child, so the proxy still never holds a
++    // Devin token and the adapter never reads one at request time.
++    //
++    // `oauth` classifies the ACCOUNT, not the transport. This is not a local
++    // runtime: unlike Ollama or LM Studio it cannot answer at all until a vendor
++    // account is signed in, and `local` grouped it with things that have no
++    // account. It is also the only classification under which the row reaches the
++    // dashboard Accounts tab, which is built from OAUTH_PROVIDERS.
+     id: "devin-cli",
+-    authKind: "local",
++    authKind: "oauth",
+     featured: false,
+-    dashboardPreset: true,
++    // Off, like `devin`. `deriveProviderPresets` keys the preset
++    // catalog off this flag, so leaving it true would draw the row twice: once as
++    // an Accounts login row and again as a preset tile.
++    dashboardPreset: false,
+```
+
+`note` keeps "no API key is stored by opencodex" — still true — and gains
+"Sign in from the dashboard, or run `devin auth login` yourself; opencodex only
+records that the CLI session exists."
+
+## MODIFY `src/oauth/index.ts`
+
+```ts
+"devin-cli": {
+  login: (ctrl, opts) => loginDevinCli(ctrl, opts),
+  refresh: (rt, signal, credential) => refreshDevinCliToken(rt, signal, credential),
+  providerConfig: oauthConfig("devin-cli"),
+  defaultModel: oauthDefaultModel("devin-cli"),
+  // No endpoint to refresh against: the CLI owns the session. Same posture as
+  // `devin` and `orcarouter-oauth`.
+  defaultRefreshPolicy: "disabled",
+},
+```
+
+Not in `FORCE_REFRESH_PROVIDERS`: a 401 cannot arrive from a provider that never
+sends a token.
+
+## NEW `src/providers/devin-cli-authmode-migration.ts`
+
+`src/server/auth-cors.ts:731-737` rejects a saved row whose `authMode === "local"`
+once the registry entry is not local, and `derive.ts:217-231` seeded exactly that
+value into every config saved while devin-cli was local.
+
+```ts
+export function projectDevinCliAuthMode(config: OcxConfig) {
+  const prov = config.providers?.["devin-cli"];
+  if (!prov || prov.adapter !== "devin-cli" || prov.authMode !== "local") return { config, changed: false, warnings: [] };
+  prov.authMode = "oauth";
+  return { config, changed: true, warnings: ["rewrote devin-cli authMode local -> oauth: the registry no longer classifies it as local, and the management write boundary fails closed on the mismatch."] };
+}
+```
+
+Guarded exactly like `projectStaleContextWindows`: exact old value, adapter still
+`devin-cli`, nothing else touched. Composed into `projectStartupConfigRepairs`.
+
+**What this migration does NOT do.** It cannot mint a credential.
+`projectStartupConfigRepairs` is a synchronous projector persisted through
+`mutatePersistedConfig`, which writes `config.json` and never the auth store, and
+`getValidAccessTokenSnapshot` reads the auth store. An earlier draft claimed a
+boot import would keep existing installs working; the audit disproved it. The
+honest upgrade story is therefore:
+
+> After upgrading, an existing `devin-cli` user's first turn returns
+> `OAuthLoginRequiredError` until they sign in once — one click in the dashboard
+> Accounts tab, or `ocx login devin-cli`. Because login is import-first and the
+> CLI is already signed in, that click completes without a browser.
+
+This ships in the release note and in the provider docs. wp4 verifies both the
+401-before and the success-after on this machine.
+
+## MODIFY `tests/providers/devin-cli-adapter.test.ts`
+
+```diff
+-  test("is a local provider that stores no credential", () => {
++  test("is an account provider whose adapter still holds no credential", () => {
+     const entry = PROVIDER_REGISTRY.find((row) => row.id === "devin-cli");
+     expect(entry?.adapter).toBe("devin-cli");
+-    expect(entry?.authKind).toBe("local");
+-    expect(entry?.dashboardPreset).toBe(true);
++    // `oauth` classifies the account, not the request path.
++    expect(entry?.authKind).toBe("oauth");
++    // Off, or the row is drawn twice — Accounts login row plus preset tile.
++    expect(entry?.dashboardPreset).toBe(false);
++    expect(OAUTH_PROVIDERS["devin-cli"]).toBeDefined();
+```
+
+New assertion that the runtime posture is unchanged: extend the existing
+handshake test so `DEVIN_CLI_SESSION_MARKER` never appears in the child's env or
+in anything written to its stdin.
+
+## MODIFY `src/adapters/devin-cli/adapter.ts` (comment only)
+
+Header gains: the dashboard now carries an account row recording that a CLI
+session exists; it never produces a credential this adapter reads.
+
+## Acceptance
+
+- `bun test tests/providers/devin-cli-adapter.test.ts tests/providers/devin-cli-login.test.ts` green.
+- A config carrying `authMode: "local"` is repaired; proven by a focused test and
+  a dry run against the real saved config.
+- `listOAuthProviders()` includes `devin-cli`; `deriveProviderPresets()` does not.
+
diff --git a/devlog/_fin/260912_devin_cli_account_login/021_phase2_oauth_and_transport.md b/devlog/_fin/260912_devin_cli_account_login/021_phase2_oauth_and_transport.md
new file mode 100644
index 0000000000..2f55642826
--- /dev/null
+++ b/devlog/_fin/260912_devin_cli_account_login/021_phase2_oauth_and_transport.md
@@ -0,0 +1,151 @@
+# 021 — Phase 2 (revised): oauth classification and the cloud transport
+
+**Supersedes `020`.** The marker, the 401-until-you-click upgrade story, and the
+whole reason those existed are gone (`005`).
+
+**Work-phase:** wp3. **Write set:** `src/providers/registry.ts`,
+`src/oauth/index.ts`, `src/providers/devin-cli-authmode-migration.ts` (NEW),
+`src/providers/model-rename-startup.ts`,
+`tests/providers/devin-cli-adapter.test.ts`, NEW migration test.
+
+## MODIFY `src/providers/registry.ts`
+
+```diff
+-    // Drives the locally installed Devin CLI. The CLI owns its own credentials
+-    // from `devin auth login`, so this provider takes no key and the proxy never
+-    // holds one. Inference happens in the child process, which is why the
+-    // destination is a stdio scheme rather than a URL.
++    // The signed-in Devin CLI as an account source. The CLI writes a
++    // `devin-session-token$<JWT>` to its own credentials.toml, which is the same
++    // credential RegisterUser hands `ocx login devin` and which the cloud-direct
++    // client already speaks, so this provider imports that token and streams over
++    // Connect-RPC like its browser-login sibling.
++    //
++    // It is NOT a local runtime. Unlike Ollama or LM Studio it cannot answer
++    // without a vendor account, and `local` grouped it with things that have no
++    // account at all. `oauth` is also the only classification that reaches the
++    // dashboard Accounts tab, which is built from OAUTH_PROVIDERS.
+     id: "devin-cli",
+-    label: "Devin CLI (local)",
+-    adapter: "devin-cli",
+-    baseUrl: "https://cli.devin.ai",
+-    authKind: "local",
++    label: "Devin CLI",
++    adapter: "devin",
++    baseUrl: DEVIN_DEFAULT_API_SERVER,
++    authKind: "oauth",
+     featured: false,
+-    dashboardPreset: true,
++    // Off, like `devin`. `deriveProviderPresets` keys the preset catalog off this
++    // flag, so leaving it true would draw the row twice: an Accounts login row and
++    // a preset tile.
++    dashboardPreset: false,
++    liveModels: true,
++    modelContextWindows: DEVIN_MODEL_CONTEXT_WINDOWS,
+```
+
+`models` / `defaultModel` move from the eleven-entry CLI roster to the cloud
+roster, because discovery is now live against the account's own catalog. The
+context windows come from `ClientModelConfig` field #18 through the same live
+path the `devin` provider uses, so this phase also retires the hand-maintained
+`DEVIN_CLI_MODEL_CONTEXT_WINDOWS` table.
+
+### The ACP adapter stays registered, but `devin-cli` can no longer reach it
+
+An earlier draft called this an escape hatch — "set `"adapter": "devin-cli"` in
+your row and keep ACP". The audit disproved it. `routedProviderConfig` pins the
+adapter from the registry whenever the row's name matches a registry id:
+
+```
+// src/router.ts:373-376
+const resolved: OcxProviderConfig = { ...provider, adapter: registryEntry.adapter, baseUrl, ...
+```
+
+and `providerMatchesRegistryTransport` (`src/providers/registry.ts:3530-3536`)
+returns true for anything that is not a `key` destination with
+`preserveCustomDestination`, so an oauth row is always pinned. Model discovery
+pins the same way (`src/oauth/index.ts:1110-1123`), and `upsertOAuthProvider`
+(`:1463-1490`) copies `adapter` from the preset on the first login, so the saved
+row is rewritten too.
+
+So the honest statement is: **after this phase the `devin-cli` PRESET is the cloud
+transport, and nothing named `devin-cli` runs ACP.** The adapter itself stays
+registered and tested, and is reachable from a differently named custom row:
+
+```json
+"providers": { "devin-acp": { "adapter": "devin-cli", "baseUrl": "https://cli.devin.ai" } }
+```
+
+That is a real capability, not a fig leaf: a custom id is not a registry id, so no
+pin applies.
+
+### The migration therefore has to warn, not just rewrite
+
+An operator who deliberately chose ACP would otherwise switch transports silently
+on upgrade. `projectDevinCliAuthMode` gains a second, non-mutating job: when the
+saved row still carries `adapter: "devin-cli"`, emit a startup warning naming the
+change and the exact `devin-acp` snippet above. It does not attempt to rename the
+row — a rename would move a provider the user's model ids point at.
+
+## MODIFY `src/oauth/index.ts`
+
+```ts
+"devin-cli": {
+  login: (ctrl, opts) => loginDevinCli(ctrl, opts),
+  refresh: (rt, signal, credential) => refreshDevinCliToken(rt, signal, credential),
+  providerConfig: oauthConfig("devin-cli"),
+  defaultModel: oauthDefaultModel("devin-cli"),
+  // The CLI owns the session and Cognition exposes no refresh endpoint. Same
+  // posture as `devin` and `orcarouter-oauth`.
+  defaultRefreshPolicy: "disabled",
+},
+```
+
+Atomic with the registry edit: `oauthConfig("devin-cli")` throws at module load
+when `deriveOAuthProviderConfig` returns undefined (`src/oauth/index.ts:204-207`),
+which it does unless `authKind` is already `"oauth"` — the filter is at
+`src/providers/derive.ts:350-353`, the throw is in `oauthConfig`.
+
+## NEW `src/providers/devin-cli-authmode-migration.ts`
+
+`src/server/auth-cors.ts:731-737` rejects a saved row whose `authMode === "local"`
+once the registry entry is not local, and `derive.ts:217-231` seeded exactly that
+value while devin-cli was local. Rewrite `local` -> `oauth`, guarded on the exact
+old value, composed into `projectStartupConfigRepairs` beside the two migrations
+already there.
+
+Unlike `020`, this pass no longer has to apologise for a credential it cannot
+mint: the token arrives from the import at login.
+
+It must not repeat the hatch claim either. The migration leaves the saved
+`adapter` field in place, but **that field does not choose the transport** for a
+registry-named row — routing pins it (`src/router.ts:373-376`). Leaving the value
+alone preserves nothing except a signal the warning can detect. An existing ACP
+user keeps ACP only by moving to a custom-named row, which is what the warning
+tells them to do.
+
+## MODIFY `tests/providers/devin-cli-adapter.test.ts`
+
+```diff
+-  test("is a local provider that stores no credential", () => {
++  test("is an account provider sourced from the installed CLI", () => {
+     const entry = PROVIDER_REGISTRY.find((row) => row.id === "devin-cli");
+-    expect(entry?.adapter).toBe("devin-cli");
+-    expect(entry?.authKind).toBe("local");
+-    expect(entry?.dashboardPreset).toBe(true);
++    expect(entry?.adapter).toBe("devin");
++    expect(entry?.authKind).toBe("oauth");
++    expect(entry?.dashboardPreset).toBe(false);
++    expect(OAUTH_PROVIDERS["devin-cli"]).toBeDefined();
+```
+
+The ACP `describe` blocks stay exactly as they are: that adapter is still
+registered and still has to work for anyone who selects it explicitly.
+
+## Acceptance
+
+- `bun test tests/providers/devin-cli-adapter.test.ts tests/providers/devin-cli-login.test.ts` green.
+- `listOAuthProviders()` includes `devin-cli`; `deriveProviderPresets()` does not.
+- A saved `authMode: "local"` row is repaired, proven by a focused test and a dry
+  run against the real config.
+
diff --git a/devlog/_fin/260912_devin_cli_account_login/030_phase3_surface_and_land.md b/devlog/_fin/260912_devin_cli_account_login/030_phase3_surface_and_land.md
new file mode 100644
index 0000000000..c5def2e7b8
--- /dev/null
+++ b/devlog/_fin/260912_devin_cli_account_login/030_phase3_surface_and_land.md
@@ -0,0 +1,89 @@
+# 030 — Phase 3: surface, docs, and landing
+
+**Work-phase:** wp4. **Write set:** `gui/src/pages/providers-shared.ts`,
+`docs-site/` English + 7 locales, `structure/` docs, PR.
+
+Rewritten after audit rounds 1 and 2. The first draft targeted
+`gui/src/provider-icons.ts`, which is the wrong surface (blocker 4).
+
+## GUI — the label lives in OAUTH_LABELS
+
+Accounts rows resolve their title through `oauthLabel(id)` →
+`OAUTH_LABELS[id] ?? id` (`gui/src/pages/providers-shared.ts:49-59`, consumed at
+`gui/src/pages/providers-page-utils.ts:21-23`). `formatProviderDisplayName`
+already returns "Devin CLI" but oauth rows never call it, so without a new entry
+the row reads `devin-cli`.
+
+```diff
+ const OAUTH_LABELS: Record<string, string> = {
+   ...
++  "devin-cli": "Devin CLI",
+ };
+```
+
+The icon needs nothing: `devin-cli` already maps to `devin.svg`.
+
+### The `local` badge disappears on its own
+
+`ProviderCatalog.tsx`'s badge ladder draws the amber `modal.badge.local` chip
+from `p.auth === "local"`, and `derive.ts:613` derives that from `authKind`.
+Once the registry says `oauth` the chip is gone and the row is an Accounts login
+row instead — which is the mark the operator asked to have removed. Nothing to
+edit; wp4 verifies it rather than assuming it.
+
+### Rail, not only the modal
+
+`gui/src/provider-workspace/auth.ts:21-22` returned `null` for local, and
+`kind.ts:12-21` classified the row as kind `local`. Under `oauth` both change:
+the row becomes a login kind and an auth surface is drawn. Check that surface
+does not offer an API-key field for a provider that takes no key — that would be
+a regression this unit introduced.
+
+## Docs
+
+English:
+
+- `docs-site/src/content/docs/reference/adapters.md:458-459` — "none held by
+  opencodex ... stores no key and asks for none." Keep the true half, add the
+  account row and the one-time sign-in.
+- `docs-site/src/content/docs/guides/providers.md:196` — same sentence in the
+  table.
+
+Locale copies of that sentence, all of which assert opencodex stores no key (still
+true; the sign-in sentence is added): `ko:117`, `ja:119`, `zh-cn:111`,
+`zh-tw:116`, `fr:130`, `ru:128`, `tr:143`.
+
+Upgrade note, from `020`: an existing user's first turn after upgrade returns
+`OAuthLoginRequiredError` until one sign-in. Import-first makes that click
+complete without a browser.
+
+## structure/
+
+`structure/AGENTS.md:49` binds `src/oauth/` and `src/providers/` changes to
+`runtime.md`, `subagents.md`, `transports/inventory.md` and
+`providers/xai-grok.md` — not only `adapters/registry.md`, which the first draft
+named alone. Read each and update any sentence this change falsifies;
+`structure/adapters/registry.md:16-25` says the two Devin adapters have
+"separate credentials", which stays true and gains the account row.
+
+## Proof against the running service
+
+1. `GET /api/oauth/providers` lists `devin-cli`.
+2. `GET /api/provider-presets` does NOT list it (blocker 2 regression guard).
+3. The Accounts tab renders a **Devin CLI** row beside devin, with no `local`
+   badge — screenshot, which the PR needs anyway because `gui/` changed.
+4. `ocx login devin-cli` completes without a browser against the already
+   signed-in CLI, and a `codex exec -m devin-cli/swe-2` turn answers afterwards.
+5. The 401-before / success-after upgrade behaviour is exercised, not asserted.
+
+## Landing
+
+Branch from a freshly fetched `origin/dev`, push `--no-verify`, PR into `dev`
+with the screenshot, hosted CI green on the exact head, merge, prove ancestry
+from a fetched `origin/dev`.
+
+## Acceptance
+
+Every goalplan criterion met with fresh evidence, including an explicit statement
+of the one-time sign-in required after upgrade.
+
diff --git a/devlog/_fin/260912_devin_cli_account_login/031_phase3_surface_and_land.md b/devlog/_fin/260912_devin_cli_account_login/031_phase3_surface_and_land.md
new file mode 100644
index 0000000000..d6fc0d7bc5
--- /dev/null
+++ b/devlog/_fin/260912_devin_cli_account_login/031_phase3_surface_and_land.md
@@ -0,0 +1,67 @@
+# 031 — Phase 3 (revised): surface, docs, and landing
+
+**Supersedes `030`.** Same surfaces, new transport, and the proof list changes
+because there is now a real credential to prove with.
+
+**Work-phase:** wp4. **Write set:** `gui/src/pages/providers-shared.ts`,
+`docs-site/` English + 7 locales, `structure/` docs, PR.
+
+## GUI
+
+Accounts rows title through `oauthLabel(id)` → `OAUTH_LABELS[id] ?? id`
+(`gui/src/pages/providers-shared.ts:49-59`, consumed at
+`gui/src/pages/providers-page-utils.ts:21-23`). Without an entry the row reads
+`devin-cli`.
+
+```diff
+ const OAUTH_LABELS: Record<string, string> = {
++  "devin-cli": "Devin CLI",
+ };
+```
+
+The icon already maps to `devin.svg`. The amber `local` badge disappears on its
+own once `auth` stops being `"local"`; verify rather than assume. Check the rail
+too: `provider-workspace/auth.ts` and `kind.ts` both change branch under
+`oauth`, and the auth surface must not offer an API-key field for a row whose
+credential is imported.
+
+## Docs
+
+The English sentences at `docs-site/src/content/docs/reference/adapters.md:458-459`
+and `docs-site/src/content/docs/guides/providers.md:196` currently describe a
+stdio ACP provider that holds no key. Both halves change: the preset now imports
+the CLI's token and streams over Connect-RPC. The seven locale copies of the
+table row follow (`ko:117`, `ja:119`, `zh-cn:111`, `zh-tw:116`, `fr:130`,
+`ru:128`, `tr:143`).
+
+Say plainly what is imported and what is not: opencodex adopts the
+`windsurf_api_key` the CLI already wrote, and never reads anything else from that
+file.
+
+Also document the surviving ACP escape hatch: an explicit
+`"adapter": "devin-cli"` still drives `devin acp`.
+
+`structure/AGENTS.md:49` binds `src/oauth/` and `src/providers/` changes to
+`runtime.md`, `subagents.md`, `transports/inventory.md` and
+`providers/xai-grok.md`. `structure/adapters/registry.md:16-25` says the two
+Devin adapters have "separate transports, separate credentials" — the credential
+half is now false for the preset and must be corrected.
+
+## Proof against the running service
+
+1. `GET /api/oauth/providers` lists `devin-cli`; `GET /api/provider-presets` does not.
+2. `ocx login devin-cli` imports without opening a browser, against the already
+   signed-in CLI.
+3. `codex exec -m devin-cli/<model>` answers — the `CLIKEY-OK` shape, now through
+   the shipped provider rather than a scratch script.
+4. The model list is the live catalog, and a spot-checked context window matches
+   `ClientModelConfig` field #18 rather than a static table.
+5. Accounts tab screenshot: a **Devin CLI** row beside Devin, no `local` badge.
+   The PR needs it anyway because `gui/` changed.
+
+## Landing
+
+Branch from a freshly fetched `origin/dev`, push `--no-verify`, PR into `dev`
+with the screenshot, hosted CI green on the exact head, merge, prove ancestry from
+a fetched `origin/dev`.
+
diff --git a/devlog/_fin/260912_devin_cli_account_login/090_outcome.md b/devlog/_fin/260912_devin_cli_account_login/090_outcome.md
new file mode 100644
index 0000000000..f1b6cfa9b5
--- /dev/null
+++ b/devlog/_fin/260912_devin_cli_account_login/090_outcome.md
@@ -0,0 +1,62 @@
+# 090 — Outcome
+
+**Merged to `dev` as `b09ef15c6f` (PR #4335).** PR head `2930a0a3bc` is an
+ancestor of a freshly fetched `origin/dev`.
+
+## What shipped
+
+`devin-cli` is an account provider that imports the credential the installed
+Devin CLI already holds and streams over Cognition's Connect-RPC api-server. It
+appears in the dashboard Accounts tab beside Devin, with no `local` badge, and is
+gone from the preset tabs.
+
+Supporting changes that were not obvious at the start: tenant selection became
+provider-scoped, because `resolveDevinApiServer` read a fixed `devin` credential
+slot and would have crossed two accounts onto one host as soon as a second
+provider shared the adapter. That required threading a provider id through
+`AdapterFactoryContext`, `resolveAdapter` and both `core.ts` call sites.
+
+## Evidence
+
+| Check | Result |
+| --- | --- |
+| `GET /api/oauth/providers` | includes `devin-cli` |
+| `GET /api/provider-presets` | excludes it |
+| `ocx login devin-cli` | `{"loggedIn":true,"source":"local-cli"}`, no browser |
+| `GET /v1/models` | 42 `devin-cli/*` rows from live discovery |
+| `codex exec -m devin-cli/swe-2` | `CLOUD-OK` |
+| context windows | `swe-2` 262,000 · Claude/GPT 1,000,000 · Gemini/GLM/Kimi 1,048,576 · Grok 500,000, from field #18 |
+| dashboard | Accounts tab screenshot, Devin CLI row signed in |
+
+Focused tests 128 pass / 0 fail, 18 of them new. GUI 1963 pass / 0 fail.
+`structure:check` and `privacy:scan` pass. Hosted CI green on `2930a0a3bc`.
+
+## What did not work, and what killed it
+
+LOOP-PESSIMIST-01. The first design was wrong and took three audit rounds to
+die. It kept the ACP transport and invented a marker credential so the provider
+could have an account row without holding a token. Reviewers killed it in stages:
+the request path would have 401'd every turn until someone clicked Login; the
+`stdin` design could not deliver the one-time code it also required; the label
+surface was the wrong file.
+
+What actually ended it was not an argument but a measurement. Reading the CLI's
+`credentials.toml` showed an ordinary `devin-session-token`, and feeding it to
+the client already in this tree returned a real answer. Every blocker downstream
+of "there is no credential we may hold" then evaporated, including the two that
+had already been patched around.
+
+The lesson worth carrying: three rounds were spent refining a design whose
+premise nobody had tested, and the test took one minute. When a plan's central
+constraint is an assumption about someone else's system, measure it before
+designing around it.
+
+## Residual
+
+- The seven `two-lock xAI refresh` failures seen while checking this work
+  reproduce on pristine `origin/dev` and are unrelated; they remain open.
+- `identityFromApiKey` returned nothing for this account's token, so the Accounts
+  row shows "signed in" without an address. That is what the CLI itself can say.
+- Multi-account is out of scope: an identity-less credential replaces the active
+  slot rather than adding one.
+
diff --git a/devlog/_plan/260911_account_pool_unification/000_plan.md b/devlog/_plan/260911_account_pool_unification/000_plan.md
new file mode 100644
index 0000000000..203c540c42
--- /dev/null
+++ b/devlog/_plan/260911_account_pool_unification/000_plan.md
@@ -0,0 +1,158 @@
+# Account pool unification
+
+Unit opened 2026-09-11. Base: `dev` at `dd9a2906b` (2.52.0).
+
+## Objective
+
+Collapse the three independent account-pool implementations into one shared
+selection kernel with per-kind policy, and make an operator's manual account
+selection actually win over the pool cursor.
+
+## Why this unit exists
+
+An audit of `dev` on 2026-09-11 found pooling is not one feature but three,
+plus a fourth path for API keys:
+
+| Kind | Owner | What it actually does |
+|---|---|---|
+| Codex | `src/codex/routing.ts`, `src/codex/pool-rotation.ts` | full: strategy, sticky, priority tiers, auto-switch threshold |
+| Anthropic | `src/oauth/anthropic-routing.ts` | full: strategy, session affinity, manual preference |
+| generic OAuth (10 providers) | `src/oauth/generic-account-failover.ts` | 429 rotation plus a proactive headroom preference when `enabled`; only `strategy` and `autoSwitchThreshold` are persisted-but-inert |
+| API keys | `src/providers/key-failover.ts` | reactive 429/401 index walk; no strategy at all |
+
+The generic kind already has a settings DTO and a capability enum
+(`src/oauth/pool-settings-capability.ts` returns `"codex" | "anthropic" | "generic"`),
+so the seam for a shared layer was designed and then left hollow. This unit fills
+it rather than inventing a new abstraction.
+
+## The defect that motivates work-phase 1
+
+Reported by the maintainer and confirmed in code: the pool moves the active
+account to B, the operator then selects A through the dashboard or
+`ocx account use`, and the runtime keeps serving B.
+
+The shape of the defect, not its patch: the Codex pin is a priority-tier ceiling
+rather than a selection input, so the strategy picker and the preemption path can
+return a different account and record it as the runtime choice. Anthropic solves
+the same problem with a one-shot `manualPreference` that Codex and the generic
+kind do not have. GUI and CLI are not the divergence: both issue the same
+`PUT /api/codex-auth/active`.
+
+This is a pin-semantics change, not a one-expression bug. An earlier draft named
+`applyQuotaAutoSwitch` as the cause; the A-phase audit rejected that, because that
+path only moves at `autoSwitchThreshold`, which the drain handler already treats
+as the end of a pin. Exact call sites, line anchors and the before/after contract
+belong to `010_phase1_manual_selection.md`, not here.
+
+## Settled semantics
+
+Recorded during the 2026-09-11 interview (session tracker rounds 1-5):
+
+- **Manual selection is a one-shot preference that commits on success.** The next
+  dispatch uses the operator's account; if that dispatch succeeds the account is
+  committed as the stored active one. The pool may move again only for a real
+  reason such as 429, cooldown or quota exhaustion. This is the shape Anthropic
+  already implements through `manualPreference`; Codex and the generic kind lack it.
+- **One shared layer, different policy per kind.** Selection order, cooldown and
+  account state are shared. Policy is not: API keys are a rate-limit scheduling
+  problem and rotate cheaply, while subscription accounts lose their prompt cache
+  on every move, so cache affinity must be consulted before quota for them.
+
+## Constraints
+
+- `dev` is the only integration branch. Layers that sit in a chain target the layer
+  below them; layers that are not in a chain target `dev` directly. The Delivery
+  section names which is which.
+- Bun-native TypeScript. No Node-only APIs, no compile step.
+- Touching OAuth account selection and credential resolution puts this unit inside
+  the AGENTS.md security boundary, so each layer needs explicit security review and
+  must not log tokens or account identifiers.
+- `privacy:scan` must stay green.
+- Existing Codex and Anthropic pool behavior must not regress; they migrate onto
+  the shared layer rather than being rewritten in place.
+- **Lane ownership.** `devlog/_plan/260911_lane_dispatch_round/010_lane_partition.md`
+  is the authoritative ownership list for the multi-lane round in flight on `dev`,
+  and lane L3 owns `src/codex/auth-api.ts`, `src/codex/routing.ts` and
+  `src/types/config.ts`. Work-phases 1 and 2 need those files, so no implementation
+  cycle may open against them until that lane releases them or the maintainer
+  reassigns ownership. This roadmap cycle writes documents only and takes no owned path.
+- **Reversibility is a precondition, not a nicety.** Because this unit changes
+  credential selection, every migrating phase ships behind a flag that defaults to
+  the existing pools, dual-reads the already-persisted keys
+  (`accountPoolStrategy`, `accountPoolStickyLimit`, `autoSwitchThreshold`,
+  `anthropicAccountPool`, `providers.<name>.oauthAccountFailover`,
+  `activeCodexAccountPinned`), and proves parity with before/after selection traces
+  for Codex and Anthropic across manual, affinity, quota, round-robin and fill-first.
+  Flag-off is the rollback.
+
+## Work-phase map
+
+Dependency order, not effort order. Each layer stands alone with its own tests.
+
+| Phase | Doc | Thesis | Depends on |
+|---|---|---|---|
+| 0 | this unit | roadmap written to diff level | — |
+| 1 | `010_phase1_manual_selection.md` | an operator pick beats the pool cursor | 0 |
+| 2 | `020_phase2_shared_kernel.md` | one kernel, and the generic kind consumes its persisted strategy and threshold | 1 |
+| 3 | `030_phase3_cache_affinity.md` | cache affinity ranks ahead of quota | 2, plus the three open assumptions closed |
+| 4 | `040_phase4_key_pool_strategy.md` | API keys gain proactive selection | none (parallel off trunk) |
+| 5 | `050_phase5_surface_consolidation.md` | three contracts and two GUIs become one | 2 |
+
+Phase 4 was reparented during the A-phase audit. It does not depend on phase 2:
+`src/providers/key-failover.ts` shares no module with the OAuth kernel, and an API
+key is a different identity from an OAuth account set. It runs parallel off trunk,
+and would gain a dependency only if phase 2 chose to export a credential-kind-agnostic
+kernel that `key-failover` imports, which phase 2 does not promise.
+
+Phase 3 is the speculative layer: all three open assumptions below live in it, so it
+does not ride the first train.
+
+Phase 5 and phase 4 must not both edit the pool management routes and the shared GUI
+controls. Phase 5 owns `src/server/management/oauth-account-routes.ts`, the route
+registry entries and the GUI pool surfaces; phase 4 keeps key-strategy fields out of
+those files and exposes nothing operator-visible until phase 5 gives it a home.
+
+## Delivery
+
+A manual branch chain, each layer a PR based on the layer below
+(`gh pr create --base`). GitHub native stacks are not used: per
+DEV-STACK-OPT-IN-01 a generic request to stack is not native opt-in.
+
+The first chain is two layers, phase 1 then phase 2. Phase 5 opens off the phase-2
+layer once the kernel lands. Phase 3 waits for its assumptions to close. Phase 4 is
+an ordinary PR off `dev` and joins no chain. This replaces an earlier 1-2-3 chain
+that the audit rejected for carrying the speculative layer.
+
+## Open assumptions
+
+Carried out of the interview unresolved. Each is a question the roadmap answers in
+its own phase doc, not a blocker on this plan.
+
+1. **Affinity key composition.** Codex keys on thread id, Anthropic on a session
+   key. A shared key shape is not yet chosen. Phase 3 decides it.
+2. **Shared-cohort handling.** `promptCacheKeyIsSharedCohort` currently discards
+   affinity entirely when a `prompt_cache_key` looks shared. Whether to fall back
+   to another identifier instead of discarding is open.
+3. **Cache minimum threshold.** There is no minimum-token gate before applying
+   `cache_control`, and Anthropic's own 1024/2048 breakpoint minimum is not
+   implemented locally. Whether to add one is open.
+
+## Audit record
+
+Two independent reviewers audited this plan at A and both returned FAIL. Folded
+findings: the phase-1 implementation recipe moved out of this 000 document
+(LEXICO-SPLIT-01); the causal story corrected away from `applyQuotaAutoSwitch`; the
+generic-OAuth description corrected from "reactive only"; phase 4 reparented off
+trunk; rollback, feature flag, persisted-config dual-read and parity proof added as
+constraints; the lane-ownership collision with `260911_l3_account_pool` recorded as
+a hard precondition on phases 1 and 2.
+
+One finding is passed to a phase doc rather than folded here: `key-failover` already
+logs `failedId` and `candidateId`, so `040` must forbid inheriting that logging shape.
+
+## Evidence
+
+Audit conducted 2026-09-11 against `origin/dev`. Interview record:
+`.codexclaw/interviews/01a08fce-634e-7531-b383-26f2251d9dae.jsonl`, tracker
+`.codexclaw/sessions/01a08fce-634e-7531-b383-26f2251d9dae.json` (five scan rounds,
+no unresolved contradictions).
diff --git a/devlog/_plan/260911_account_pool_unification/010_phase1_manual_selection.md b/devlog/_plan/260911_account_pool_unification/010_phase1_manual_selection.md
new file mode 100644
index 0000000000..949ee387b1
--- /dev/null
+++ b/devlog/_plan/260911_account_pool_unification/010_phase1_manual_selection.md
@@ -0,0 +1,353 @@
+# Phase 1 — an operator pick beats the pool cursor (Codex)
+
+Base: `origin/dev` `dd9a2906b`. Branch: `codex/pool-manual-selection` off `dev`.
+Precondition: lane L3 owns `src/codex/routing.ts` and `src/codex/auth-api.ts`
+(000_plan.md constraints). Do not open this layer until that ownership clears.
+
+## Thesis
+
+A manual selection from the dashboard or `ocx account use` wins the next dispatch,
+and commits as the stored active account when that dispatch succeeds.
+
+## Current behaviour (verified on dd9a2906b)
+
+```
+src/codex/routing.ts
+  56   let runtimeActiveCodexAccountId: string | undefined;
+  1625 export function getEffectiveActiveCodexAccountId(config: OcxConfig): string | undefined {
+  1626   return runtimeActiveCodexAccountId ?? config.activeCodexAccountId;
+  1644 function rememberActiveCodexAccount(_config: OcxConfig, accountId: string): void {
+  1645   runtimeActiveCodexAccountId = accountId;
+```
+
+`rememberActiveCodexAccount` is called at `:1470` (round-robin commit), `:1481`
+(fill-first commit), `:1678` (`promoteActiveCodexAccount`) and `:2286`
+(preemption). None of the four consults the pin. The pin itself
+(`config.activeCodexAccountPinned`, written only by `auth-api.ts:2441`) is read as
+a priority-tier ceiling in `getEligiblePoolAccounts` `:1318-1322` and nowhere else
+in the selection path.
+
+The path to copy is Anthropic's:
+
+```
+src/oauth/anthropic-routing.ts
+  94  let manualPreference: OAuthAccountSelection | null | undefined;
+  575 if (manualPreference === undefined) { ...seed from set.activeAccountId + selectionRevision }
+  588 if (manualPreference.accountId !== set.activeAccountId || revision mismatch) manualPreference = null;
+  597 return { accountId: chosen, reason: "manual" };
+  799 // consumed only after the admission commit
+  808 export function resetAnthropicRoutingForManualSelection(accountId: string)
+```
+
+## Change surface
+
+MODIFY `src/codex/routing.ts`
+
+1. NEW `manualPreference`, keyed by pool scope rather than a singleton:
+   `Map<poolKey, { accountId: string } | null>` beside `runtimeActiveCodexAccountId`
+   (`:56`), keyed by `codexPoolKeyForScope` (`:225`). A singleton would let an
+   independent quota scope (spark, reserve) apply or consume the shared one-shot,
+   because `isIndependentCodexQuotaScope` deliberately isolates those from the
+   shared `remember` path. An absent entry means not yet seeded; `null` means
+   consumed.
+
+   Seeding is explicit only. The entry is written by
+   `resetCodexRoutingForManualSelection` and nowhere else. There is no lazy seed
+   from `config.activeCodexAccountId` on first read, because an absent entry plus a
+   lazy seed would let an independent quota scope invent a preference it was never
+   given.
+
+   Invalidation, since Codex has no account-side equivalent of Anthropic's
+   `selectionRevision` (`apiKeySelectionRevision` is for keys and the store
+   `generation` is credential lineage): the preference is dropped only by an
+   OPERATOR-driven change of the active account, meaning another
+   `resetCodexRoutingForManualSelection` naming a different account, or an explicit
+   clear. A POOL-driven move must not drop it.
+
+   That distinction is load-bearing and was missed twice. An earlier draft said
+   "drop it whenever the accountId no longer equals the persisted active account",
+   which contradicts the guarantee below: `promoteActiveCodexAccount` (`:1677`)
+   calls `releaseCodexAccountPinFor` and then `setActiveCodexAccount` (`:1660`,
+   which clears `runtimeActiveCodexAccountId` at `:1661`) BEFORE it would reach the
+   guarded `remember`. Under the old rule a failover promote would move the
+   persisted active, look like a mismatch, and silently spend the operator's
+   one-shot. Keying invalidation to the operator path instead of to value equality
+   is what keeps F1 and F4 from cancelling each other.
+2. `resetCodexRoutingForManualSelection` (`:870`) additionally seeds
+   `manualPreference` from `config.activeCodexAccountId`, mirroring
+   `anthropic-routing.ts:810`. It keeps clearing thread affinity, clearing the
+   runtime cursor and seeding round-robin, and keeps preserving cooldown.
+3. The guard sits on BOTH writers, not only on `remember`.
+   `rememberActiveCodexAccount` (`:1644`) becomes a no-op while a live preference
+   names a different account, which closes its four call sites `:1470`, `:1481`,
+   `:1678` and `:2286` at once. That alone is still insufficient, because
+   `promoteActiveCodexAccount` (`:1677`) releases the pin and calls
+   `setActiveCodexAccount` (`:1660`) before it ever reaches `remember`. So
+   `promoteActiveCodexAccount` and `setActiveCodexAccount` also check for a live
+   preference and leave the operator's account in place for the pool-driven paths
+   (failover `:1878`, model detour `:2213`, exclusion `:1704`, cooldown `:2534`
+   and `:2584`). An operator PUT still moves them, because that path seeds a new
+   preference first.
+4. `getEffectiveActiveCodexAccountId` (`:1625`) returns the preference account
+   while one is live, ahead of the runtime cursor.
+5. `resolveCodexAccountForThreadDetailed` (`:2069`) checks the preference before
+   `pickUnboundStrategyAccount` (`:2194`). If the preference account is selectable
+   and not exhausted, return it with a `manual` reason and do not call
+   `rememberActiveCodexAccount`. Honouring does NOT require the preference to still
+   equal `config.activeCodexAccountId`: a pool-driven promote may legitimately have
+   moved that value, and treating the difference as staleness is the mistake the
+   audit rejected twice.
+6. `previewCodexAccountForRequest` (`:1987`) peeks the preference without
+   consuming it.
+7. NEW consume-on-success, mirroring `anthropic-routing.ts:799-800`. Codex has no
+   equivalent of the Anthropic admission commit, so the hook must be named
+   explicitly: consume at the same point that already records a successful upstream
+   outcome for the resolved account, `recordCodexUpstreamOutcome`, and only for a
+   non-quota success. Consuming must call `setActiveCodexAccount` rather than only
+   nulling the entry, because nulling alone leaves `runtimeActiveCodexAccountId`
+   pointing at the pool's earlier pick and the next dispatch would silently return
+   to it. A failed lookup must not spend the preference.
+
+MODIFY `src/codex/auth-api.ts` PUT `/api/codex-auth/active` (`:2412-2444`):
+no contract change. It keeps `setCodexAccountPin` and
+`resetCodexRoutingForManualSelection`; the pin stays the tier ceiling and the new
+preference carries the one-shot. A null body still clears the pin (`:2440`).
+
+Explicitly NOT changed: `applyQuotaAutoSwitch` (`:1784`). It only moves at
+`autoSwitchThreshold`, and `releaseDrainedCodexAccountPin` (`:1757`) already
+treats that drain as the end of a pin. An earlier draft named it as the cause and
+the audit rejected that. Goalplan criterion c-2 therefore already holds on `dev`;
+what is missing is not behaviour but proof, so this layer adds the test rather
+than the code.
+
+## Tests
+
+Extend, do not add files. `codex-` is not in the `layout.json` domain regex, so a
+new `codex-*.test.ts` would need entries in both `scripts/test-layout/layout.json`
+`explicit` and `tests/fixtures/test-layout-expected.json`.
+
+- `tests/codex-integration/codex-pool-rotation.test.ts` — the operator pick wins the
+  next round-robin and fill-first dispatch (manual seed cases at `:524-541`); the
+  existing pin-holds-RR case at `:791-803` stays green for the ceiling after the
+  preference is consumed.
+- `tests/codex-integration/codex-routing.test.ts` — a second unbound session follows
+  the pool cursor again once the preference is spent; a failed admission leaves the
+  preference unspent (pin cases at `:3139-3242`).
+- `tests/codex-integration/codex-auth-api.test.ts` — PUT then next-dispatch identity
+  (`:3956-3989`).
+
+Semantic oracle: `tests/adapters/anthropic/anthropic-account-pool.test.ts` `:144`,
+`:209`, `:234`.
+
+Added after the A-phase audit, because the three files above prove the ceiling and
+the drain but not these:
+
+- a live preference survives `promoteActiveCodexAccount` reached through failover
+  and through a model detour, and survives a priority preemption
+- an independent quota scope neither applies nor consumes the shared preference
+- an operator selecting a different account replaces the previous preference, while
+  a pool-driven promote that moves the persisted active account does not spend it
+- criterion c-2 directly: with a pinned account that is selectable and under
+  `autoSwitchThreshold`, auto-switch holds, under both the quota strategy and
+  round-robin or fill-first
+
+## Out of scope
+
+## Audit record
+
+The A-phase reviewer returned FAIL with one blocker and four majors, all folded
+above: the overwrite hole at `promoteActiveCodexAccount` and preemption, the
+singleton-versus-scope-keyed state, the missing invalidation rule in the absence
+of an account-side revision, the pin-versus-preference disagreement after a
+released pin, and the test gap against criterion c-2.
+
+## Implementation-entry audit, after the lane freeze lifted
+
+Lane L3 PR #4230 and lane L1 PR #4226 merged, so this work became writable. A
+fresh audit against the post-merge file returned FAIL with three more blockers.
+All anchors survived the merge (`codexPoolKeyForScope` 225,
+`resetCodexRoutingForManualSelection` 870, `pickUnboundStrategyAccount` 1446,
+`getEffectiveActiveCodexAccountId` 1625, `rememberActiveCodexAccount` 1644,
+`setActiveCodexAccount` 1660, `promoteActiveCodexAccount` 1669), but L3 added
+independent-scope cursor isolation and runtime-only preemption, which changes what
+the design may assume.
+
+1. **BLOCKER. The preference is scope-keyed but `getEffectiveActiveCodexAccountId`
+   is not.** It takes only a config and has no `quotaScope`, so it can read the
+   shared `POOL_KEY_CODEX` entry and nothing else. `resolveCodexAccountForThreadDetailed`
+   and `previewCodexAccountForRequest` look up `codexPoolKeyForScope(quotaScope)`
+   themselves. A scope with no entry means NO preference; it must never fall back to
+   the shared key, or an independent scope would consume a one-shot it was not given.
+2. **BLOCKER. Consuming inside `setActiveCodexAccount` is wrong.** That function is
+   also the persist path for pool-driven moves: quota auto-switch (1807), affinity
+   re-evaluation (2166), unbound persist (2231 and 2252) and the quota promote
+   (1671) all call it. Consuming there would let the pool spend the operator's
+   one-shot. Consume only on the path where the preference was actually honoured
+   and the dispatch succeeded, plus on an operator reset.
+3. **BLOCKER. An unconditional honour traps a cooled account.** With
+   `rememberActiveCodexAccount` a no-op, a 429 or failover on the preferred account
+   (2527, 2576, 1878) could not move `getEffectiveActiveCodexAccountId` away from
+   it. Honour the preference only while that account is selectable and not cooling;
+   otherwise treat it as absent for this dispatch without spending it.
+4. **The preview path must mirror resolve.** The check belongs immediately before
+   BOTH `pickUnboundStrategyAccount` calls, at 2020 and 2193, after affinity and
+   model-detour handling, not at function entry.
+5. **Pause and exclusion never route through the reset.** `reconcileCodexActiveAfterExclusion`
+   (1692) and the health-clear path (317-320) bypass it, so a preference would
+   outlive an excluded or paused account. Drop the key when the preferred account is
+   excluded or paused.
+6. **Minor, but decide it deliberately.** `isEffectiveCodexAccountPinned` (1637)
+   would read true while the preference equals the pin, and L3 now documents that
+   `getEffectiveActiveCodexAccountId` is what surfaces automatic picks to the API
+   and dashboard. Either keep the pin check reading persisted and runtime only, or
+   accept and document that `GET /api/codex-auth/active` is manual-sticky until the
+   preference is consumed.
+
+## Measured: the consume call site is the whole design, not a detail
+
+A first implementation pass built the preference map, the seeding inside
+`resetCodexRoutingForManualSelection`, the `rememberActiveCodexAccount` guard, the
+`getEffectiveActiveCodexAccountId` overlay and the exclusion revoke, and left the
+consume call site unwired. It typechecked, and then
+`tests/codex-integration/codex-pool-rotation.test.ts` went from green to **15 failures
+out of 69**, including "fill-first picks the same sequence with no stored order as
+before the feature".
+
+That is the correct result, and it is worth recording rather than repeating. Without a
+consume site the one-shot is permanent: the first operator selection freezes the
+automatic cursor forever, because `rememberActiveCodexAccount` stays a no-op and no
+code path ever clears the entry. Every rotation-strategy test that expects the pool to
+keep moving after a manual selection fails, and they are right to.
+
+So the implementation order matters. Build the consume path FIRST, not last:
+
+1. Find the point that already records a successful upstream outcome for the resolved
+   account and call `consumeCodexManualPreference(poolKey)` there, for a non-quota
+   success only. This is the Codex analogue of `commitAnthropicSelectionRouting`
+   (`anthropic-routing.ts` :799-800), which Codex has no direct equivalent of.
+2. Only then add the `rememberActiveCodexAccount` guard, so the suite never passes
+   through a state where the cursor can freeze.
+3. Gate honouring on the account being selectable, per blocker 3 above, so a cooled
+   preferred account is skipped for that dispatch without being spent.
+
+The pass was reverted rather than pushed. The branch `codex/manual-selection-wins`
+carries this document and no source change.
+
+## Measured again: guarding the writer is right, but the 429 path needs an exemption
+
+A second pass followed the order above. The consume site went in first, at the
+`outcomeClass === "success"` branch of `recordCodexUpstreamOutcome` (:2356), keyed by
+`codexPoolKeyForScope(quotaScope)` which that function already computes. Seeding and the
+exclusion revoke followed. At each of those two steps
+`tests/codex-integration/codex-pool-rotation.test.ts` stayed **69 pass, 0 fail**, which
+confirms the ordering advice above is correct.
+
+Adding the `rememberActiveCodexAccount` guard then produced **6 failures out of 69**, down
+from 15, and every single one is a 429 promotion case:
+
+- fill-first 429 advances to next stable account, not lowest usage
+- RR 429 promotes via ring, not lowest usage
+- 429 retry reuse promoteAccountId avoids a second RR ring advance
+- fill-first transient failover advances stable order, not lowest usage
+- scoped reset 429s retain strategy while excluding only the affected native quota
+- fill-first preserves its pre-feature fallback when every ordered tier is drained
+
+That is exactly the hazard blocker 3 named, and it is sharper than the blocker stated it.
+Gating the guard on `isCodexAccountSelectable(preferred)` is NOT sufficient: at the moment
+`promoteActiveCodexAccount` runs, the preferred account can still read as selectable
+because the 429 cooldown is recorded on a different path, so the guard holds and the
+promotion cannot land.
+
+The conclusion for the next pass: guarding the writer closes all four call sites at once,
+which is still the right shape, but the failover promote needs an explicit exemption. It
+only ever runs because the account in use just failed, so it is never an automatic pick
+competing with the operator. Either pass an explicit "this is a failover promote" flag
+through `rememberActiveCodexAccount`, or leave the writer unguarded and guard the two
+strategy commit sites plus preemption instead, accepting three guards rather than one.
+
+Reverted again rather than pushed. The measurement is the deliverable.
+
+The generic OAuth kind gets no preference in this layer; that arrives with the
+kernel in phase 2. No management or GUI change.
+
+## Staleness re-verification
+
+Re-verified at the wp1 P entry against `origin/dev` `16f18d654`, after lane L3
+landed `de1d88739`, `abec9ee51` and `7f91737c2` on the owned files. Every anchor
+this document depends on is unchanged from the `dd9a2906b` reading:
+
+| Symbol | Line on 16f18d654 |
+|---|---|
+| `getEffectiveActiveCodexAccountId` | 1625 |
+| `rememberActiveCodexAccount` | 1644 |
+| `applyQuotaAutoSwitch` | 1784 |
+| `resetCodexRoutingForManualSelection` | 870 |
+| `pickUnboundStrategyAccount` | 1446 |
+| `releaseDrainedCodexAccountPin` | 1757 |
+
+The design therefore survives the lane's landings. What does not change is the
+coordination risk: L3 still owns these files for the dispatch round, so the B
+phase of this work-phase must not open until that ownership clears. Re-run this
+table at that point, because the guarantee above is a snapshot of `16f18d654`.
+
+## Audit round 4 — the shipped tests proved nothing
+
+The first implementation landed as PR #4284 with three new cases under
+`an operator selection outranks the pool cursor`, and a reviewer was asked one
+question the earlier rounds never asked: does each test fail without the production
+change? It does not. Measured by reverting only `src/codex/routing.ts` to the parent
+branch and keeping the new tests:
+
+```
+bun test tests/codex-integration/codex-pool-rotation.test.ts \
+  -t "an operator selection outranks the pool cursor"
+3 pass, 0 fail          # production change reverted
+```
+
+All three passed against a tree with no guard, no preference map and no consume site.
+They were re-assertions of things that already held: case 1 of
+`resetCodexRoutingForManualSelection` clearing the runtime cursor and seeding the ring,
+cases 2 and 3 of the failover promote, which this design deliberately leaves exempt. A
+test that cannot fail is not weak coverage, it is an empty claim, and criteria c-1 and
+c-2 had been recorded `met` against it.
+
+Three real defects were behind that blind spot.
+
+**Deletion never revoked the preference.** Pause and exclusion both route through
+`reconcileCodexActiveAfterExclusion`, which forgets it. Delete does not: the
+account-lifecycle path reaches routing through `clearCodexUpstreamHealthForAccount`
+(`routing.ts:327`, called from `account-lifecycle.ts:43`), which cleared two health maps
+and left the preference behind. Once the named account is gone nothing can ever succeed
+on it, so the one-shot can never be spent, and every later automatic write is suppressed
+until the process restarts. The generation sweep in `reconcileCodexRoutingHealth` had the
+same hole for an account removed by an edit the runtime never observed.
+
+**The model-detour promote was reported as unguarded — REBUTTED.** `promoteActiveCodexAccount`
+at the model-detour site sits twelve lines above the preemption site this design guards, so
+the symmetry argument is tempting. It is wrong, and the measurement says so: guarding it
+fails 8 cases in `tests/codex-integration/codex-routing.test.ts`, the
+`cannot re-pick a quota-drained shared account that remains model-eligible` family and its
+siblings. Those encode an older contract. A model detour is not the pool exercising
+discretion — it runs because the operator's account cannot serve the requested model at
+all — and under a rotating strategy that promote moves only the process-local cursor to
+whoever is actually serving, then releases the pin. `config.activeCodexAccountId`, the
+operator's persisted selection and the thing this preference exists to protect, is
+untouched either way. The guard was written, measured red, and reverted with the reason
+recorded at the call site.
+
+**The independent-scope entries were dead state.** Every write site the guard protects is
+already skipped for independent scopes, so those keys were seeded and consumed but never
+read. Removed: state nothing reads is what the next reader mistakes for a rule.
+
+The replacement cases are each red against the variant that removes the piece they cover:
+
+| Case | Red against |
+|---|---|
+| an over-threshold operator account is served around, not replaced | parent branch: reads `b`, expected `a` |
+| deleting the preferred account releases the hold | pre-fix head `63217d161`: reads `undefined`, expected `b` |
+| a successful dispatch spends the one-shot so the pool may move again | guard without consume: 15 of 69 rotation tests fail |
+
+The over-threshold case is also the one that states the user-facing rule plainly. An
+account past its switch threshold is temporarily spent, not wrong: the pool serves the
+request from elsewhere, and the operator's selection stays pointed where the operator put
+it, so the window rolling over returns routing to it without a second manual pick.
diff --git a/devlog/_plan/260911_account_pool_unification/020_phase2_shared_kernel.md b/devlog/_plan/260911_account_pool_unification/020_phase2_shared_kernel.md
new file mode 100644
index 0000000000..fd0b21c651
--- /dev/null
+++ b/devlog/_plan/260911_account_pool_unification/020_phase2_shared_kernel.md
@@ -0,0 +1,421 @@
+# Phase 2 — one kernel, and the generic kind consumes its persisted settings
+
+Base: the phase-1 layer. Branch: `codex/pool-shared-kernel`, PR base
+`codex/pool-manual-selection`. Same lane-L3 precondition as phase 1.
+
+## Thesis
+
+Extract the rotation primitives into a credential-neutral kernel, then make the
+generic OAuth kind actually consume the `strategy` and `autoSwitchThreshold` it
+already persists.
+
+## Availability and the slice this cycle can actually take
+
+Re-verified at the wp2 P entry against `origin/dev`. The lane partition for the
+round in flight does not list `src/oauth/generic-account-failover.ts`,
+`src/oauth/pool-settings-capability.ts` or `src/codex/pool-rotation.ts`, so the
+kernel extraction and the generic-kind strategy work are available now. Two things
+are not:
+
+- `src/codex/routing.ts` is owned by lane L3, so the Codex-side import swap waits.
+- `src/server/responses/core.ts` is owned by lane L1 and is the most contended
+  file in the round with four open PRs, which is also why the wp4b call-site
+  wiring could not follow #4277 immediately.
+
+This cycle takes the kernel, the Anthropic import swap and the generic consumer.
+Only the CODEX import swap is deferred, and it is deferred for free: once
+`pool-rotation.ts` re-exports the kernel, `src/codex/` keeps its existing import
+path and needs no edit at all. So the contended files stay out of this PR without
+the kernel being an orphan.
+
+Two kinds of change are moving here and they carry different risk, which is why
+only one of them is behind the flag:
+
+- **Relocation** is behaviour-preserving. Moving the state and primitives into
+  `pool-kernel.ts` and re-exporting them changes no selection outcome, so it is
+  not flagged. `git` history and a green existing suite are its proof.
+- **Behaviour** is flagged. The generic kind consuming `strategy` and
+  `autoSwitchThreshold`, and the DTO reporting `inert: false`, only happen when
+  `pool.kernel` is on. Flag off restores today's outcomes exactly, because the
+  pre-kernel path is the same code reached through the shim.
+
+Anchors confirmed present on `origin/dev`: `selectPriorityTier` :86,
+`pickRoundRobinAccount` :189, `notePoolRotationSuccess` :213,
+`seedPoolRotationAccount` :245, `reconcilePoolRotationState` :260 in
+`pool-rotation.ts`; `preferredInitialAccount` :246 and the
+`rankAccountsByHeadroom` import :19 in `generic-account-failover.ts`.
+
+## Current behaviour (verified on dd9a2906b)
+
+The primitives already take an opaque `poolKey`, so a third key is addable:
+
+```
+src/codex/pool-rotation.ts
+  4-5  POOL_KEY_CODEX = "codex"; POOL_KEY_ANTHROPIC = "anthropic";
+  13   const selectionState = new Map<string, SelectionState>();
+  86   selectPriorityTier(ids, priorityOf, hasHeadroom, pinnedId?)
+  189  pickRoundRobinAccount(poolKey: string, eligibleIds, stickyLimit)
+  201  peekRoundRobinAccount(...)
+  213  notePoolRotationSuccess(poolKey, accountId, stickyLimit)
+  232  notePoolRotationFailure(poolKey, accountId)
+  245  seedPoolRotationAccount(poolKey, accountId)
+  270  reconcilePoolRotationState  // only sweeps "anthropic", "codex", "codex:*"
+```
+
+Fill-first is duplicated rather than shared: `pickFillFirstCodexAccount`
+(`routing.ts:1370`) and `pickFillFirstAnthropicAccount`
+(`anthropic-routing.ts:513`).
+
+`src/oauth/generic-account-failover.ts` imports nothing from `pool-rotation.ts`.
+It keeps its own cooldown `health` map (`:64-70`, keyed `provider\0accountId`),
+rotates on 429 through `rankAccountsByHeadroom` (`:178-218`) and steers the first
+attempt through `preferredInitialAccount` (`:246-292`) when
+`oauthAccountFailover.enabled`. It never reads `failover.strategy` or
+`autoSwitchThreshold`.
+
+`src/oauth/pool-settings-capability.ts` returns `"codex" | "anthropic" | "generic"`
+and stamps `inert: true` on the generic DTO (`:40-54`, `:57-67`).
+`src/server/management/oauth-account-routes.ts:395-396` still rejects
+`stickyLimit` and `quotaWindow` for the generic kind.
+
+## Change surface
+
+NEW `src/oauth/pool-kernel.ts`
+- move the WHOLE private `selectionState` map together with
+  `pickRoundRobinAccount`, `peekRoundRobinAccount`, `seedPoolRotationAccount`,
+  `notePoolRotationSuccess`, `notePoolRotationFailure`, `clearPoolRotationState`,
+  `selectPriorityTier`, the priority parsers, `POOL_KEY_*` and the strategy and
+  sticky normalizers. Moving a function subset while leaving the map behind would
+  split one piece of state across two modules.
+- the move is safe: `pool-rotation.ts` imports only two TYPES,
+  `OcxAccountPoolRotationStrategy` from `../types` and `GenerationContext` from
+  `../lib/state-store-sweeper`. Neither creates a cycle into `src/oauth`.
+- add `genericPoolKey(provider) => \`generic:\${provider}\``
+- add a fill-first helper with the signature
+  `pickFillFirst(ids, afterId, hasHeadroom, stableAll)`. The earlier three-argument
+  shape was rejected by the audit: both existing copies walk a STABLE FULL roster
+  and not the eligible subset, so dropping `stableAll` changes the wrap order
+  whenever an ineligible id sits between two eligible ones.
+- extend the reconcile sweep to `generic:*`. `buildGenerationContext` already fills
+  `oauthAccountKeys` from `listLiveOAuthAccountKeys` as `provider\0id` for every
+  live OAuth provider, so the sweep needs no new field and no Codex dependency;
+  today those keys are simply skipped as `valid === null`.
+
+NOT moved, deliberately: the Codex fill-first copy in `src/codex/routing.ts` stays
+where it is. Deleting it is the only thing that would force an edit to a file lane
+L3 owns, and the audit flagged that as a blocker against this unit's own freeze.
+Only `anthropic-routing.ts` and the generic kind switch to the kernel helper, and
+the Anthropic caller keeps its weekly `exhausted5h` pre-filter rather than pushing
+that rule into the shared helper.
+
+MODIFY `src/codex/pool-rotation.ts` — re-export the kernel so existing importers
+and `tests/codex-integration/codex-pool-rotation.test.ts` keep working unchanged.
+
+MODIFY `src/oauth/generic-account-failover.ts` — branch BOTH paths on strategy, not
+just the proactive one. `preferredInitialAccount` currently no-ops when the active
+account is healthy and requires `hasHeadroomEvidence`, and the 429 path always ends
+in `rankAccountsByHeadroom`; leaving either unbranched keeps the strategy inert in
+practice even after the DTO says otherwise. `quota` keeps
+`rankAccountsByHeadroom`, `round-robin` calls
+`pickRoundRobinAccount(genericPoolKey(name), ...)`, and `fill-first` uses the
+kernel helper with `autoSwitchThreshold` as its headroom test. Keep the presence
+quorum, the `EXCLUDED_PROVIDERS` guard and the per-provider `health` cooldown.
+
+MODIFY `src/server/management/oauth-account-routes.ts` — a manual account selection
+must seed the cursor, or the operator's pick immediately loses to sticky
+round-robin. Today that PUT calls only `forgetGenericFailoverRoster`, which clears
+the presence cache and not the rotation state. Add
+`seedPoolRotationAccount(genericPoolKey(provider), accountId)` beside it, mirroring
+what `resetAnthropicRoutingForManualSelection` already does for Anthropic.
+`clearGenericFailoverHealth` is the wrong map and `clearPoolRotationState` wipes
+where seeding is wanted.
+
+MODIFY `src/oauth/pool-settings-capability.ts` — report `inert` from the flag rather
+than as a type literal. While `pool.kernel` is off the generic DTO must keep saying
+`inert: true`, because nothing consumes the strategy yet and the reversibility rule
+below requires the old behaviour to be exactly restorable. The literal becomes a
+computed field and only turns false once the kernel is on.
+
+Known readers of that field, all of which move in the same PR:
+`src/cli/account-extended.ts` (forces generic auto-switch inactive),
+`tests/server/account-pool-management-api.test.ts` and
+`tests/cli/cli-account-pool-verbs.test.ts`. The GUI does not read it.
+Also lift the `stickyLimit` rejection at `oauth-account-routes.ts:395` and update
+`src/types/provider.ts:512-518` comments.
+
+MODIFY `src/oauth/anthropic-routing.ts` — import from the kernel. `src/codex/`
+keeps importing `./pool-rotation`, which is now a re-export, so this layer needs
+no edit inside lane L3's files at all. The audit confirmed the shim is sufficient:
+`routing.ts`, `auth-api.ts`, `account-priority.ts` and
+`state-store-registrations.ts` all keep their existing import path.
+
+## Reversibility (audit blocker, mandatory)
+
+1. **Flag.** `pool.kernel` defaults to `false`. With it off, Codex and Anthropic
+   take the pre-kernel code path and the generic kind keeps reporting `inert`.
+2. **Dual-read.** The kernel reads the already-persisted keys without rewriting
+   them: `accountPoolStrategy`, `accountPoolStickyLimit`, `autoSwitchThreshold`,
+   `anthropicAccountPool.*`, `providers.<name>.oauthAccountFailover`,
+   `activeCodexAccountPinned`. No migration writes on upgrade.
+3. **Rollback.** Flag off. No config is rewritten, so downgrade is a restart.
+4. **Parity proof.** Golden selection traces recorded before and after for Codex
+   and Anthropic across manual, affinity, quota, round-robin and fill-first, plus
+   the `__main__` and independent-quota-scope callers. Identical picks are the
+   gate; a differing pick is a blocker, not a note.
+
+## Tests
+
+Audit record: the A-phase reviewer returned PASS-WITH-FINDINGS with two blockers,
+both folded above. The first was that lifting fill-first out of its Codex copy
+would have forced an edit inside lane L3's freeze. The second was that dropping
+`inert: true` unconditionally contradicts this document's own reversibility rule,
+which requires `pool.kernel` to default off and the old behaviour to be exactly
+restorable.
+
+## Second-half audit (the flagged behaviour change)
+
+The extraction shipped as PR #4279. A separate audit of the remaining half returned
+FAIL, and its findings change that half materially. Recorded here so the next cycle
+starts from them rather than rediscovering them.
+
+1. **BLOCKER. Branching the final ranking expression is not enough.**
+   `preferredInitialAccount` encodes the quota strategy BEFORE its tail: the
+   healthy-active early return tests `isAccountQuotaExhausted` (:262) and the
+   roster-wide `hasHeadroomEvidence` check (:272) returns null when a provider has
+   no quota data at all. Leave those untouched and round-robin can never run for a
+   provider without quota evidence, and fill-first never reaches
+   `autoSwitchThreshold` because the healthy active account already returned. Both
+   guards have to be strategy-gated: skip the evidence requirement for round-robin,
+   and use the threshold rather than exhaustion for fill-first.
+2. **BLOCKER. The preference must peek, not pick.**
+   `pickRoundRobinAccount` mutates live ring state, but
+   `preferredInitialAccount` is explicitly a discardable proposal that the caller
+   drops on a resolver throw or a missing project. Mutating there desyncs the
+   cursor against requests that never happened. Use `peekRoundRobinAccount` and
+   mutate with `pickRoundRobinAccount` plus `notePoolRotationSuccess` only after
+   the selection is admitted, which is what Anthropic already does.
+3. **The 429 path is safe to branch but fill-first must still move.** That tail has
+   no evidence guard, so a strategy branch is structurally fine. Fill-first there
+   cannot mean keep-active: the account that just returned 429 is already cooled,
+   so staying put would skip rotation entirely.
+4. **`stickyLimit` does not exist for the generic kind yet.** The
+   `oauthAccountFailover` type carries only `enabled`, `strategy` and
+   `autoSwitchThreshold`. Lifting the 400 at `oauth-account-routes.ts:395` before
+   adding the field to the type, the DTO, GET and the PUT writer would accept a
+   value and then drop it. The kernel default is 1.
+5. **The flag lands in a lane-owned file.** `OcxConfig` has no `pool` key today,
+   so `pool.kernel` belongs in `src/types/config.ts` (around :363) - which lane L3
+   owns. This half therefore inherits the same freeze as work-phases 1 and 2 until
+   that ownership clears, or the flag needs a different home.
+
+- `tests/codex-integration/codex-pool-rotation.test.ts` — unchanged behaviour
+  through the re-export (`pickRoundRobinAccount` `:270`, `selectPriorityTier` `:111`)
+- `tests/oauth/generic-oauth-failover.test.ts` — a configured strategy changes the
+  selected account, which is the criterion that closes "no longer inert"
+- `tests/server/account-pool-management-api.test.ts` `:435`, `:449` and
+  `tests/cli/cli-account-pool-verbs.test.ts` `:315` — update the inert assertions
+- `tests/adapters/anthropic/anthropic-account-pool.test.ts` — parity
+- `tests/providers/kiro/kiro-pool-rank.test.ts` — the kiro exhaustion special case
+  in `account-quota-rank.ts:84-108` survives
+
+## wp2b implementation plan (re-verified against `dev` 29d632ff2)
+
+Every anchor below was re-read on the post-merge tree, after #4275/#4277/#4279/#4284 landed.
+
+| Symbol | File | Line |
+|---|---|---|
+| `isProactivePreferenceEnabled` | `src/oauth/generic-account-failover.ts` | 150 |
+| `rotateGenericOAuthAccountOn429` | `src/oauth/generic-account-failover.ts` | 178 |
+| `preferredInitialAccount` | `src/oauth/generic-account-failover.ts` | 246 |
+| `forgetGenericFailoverRoster` | `src/oauth/generic-account-failover.ts` | 308 |
+| `GenericPoolSettingsDto` / `inert: true` | `src/oauth/pool-settings-capability.ts` | 40 / 54, 65 |
+| `PUT /api/oauth/accounts/active` | `src/server/management/oauth-account-routes.ts` | 325 |
+| generic GET / PUT DTO | `src/server/management/oauth-account-routes.ts` | 360 / 422 |
+| `stickyLimit` 400 | `src/server/management/oauth-account-routes.ts` | 396 |
+| `genericPoolKey` / `pickRoundRobinAccount` / `peekRoundRobinAccount` / `notePoolRotationSuccess` | `src/oauth/pool-kernel.ts` | 12 / 198 / 210 / 222 |
+| `genericFailoverAccountId = resolved.accountId` | `src/server/responses/core.ts` | 4407 |
+| per-provider `oauthAccountFailover` | `src/types/provider.ts` | 520 |
+
+### The question 020 left open: where does a round-robin proposal commit?
+
+`peekRoundRobinAccount` exists and does not advance the ring, which is correct for
+`preferredInitialAccount` — that answer is discardable, and the resolver drops it when the
+account turns out to be removed, reauth-flagged, or missing a Cloud Code Assist project. But
+a peek that never commits is a ring that never turns: every request would propose the same
+account forever, and "round-robin" would be a label on a constant.
+
+So a commit site is mandatory, and it has to be the admission point, not the proposal. That
+point already exists and already has a generic-only branch:
+
+```
+src/server/responses/core.ts:4405-4408
+  if (isGenericFailoverProvider(route.providerName, route.provider)) {
+    genericFailoverAccountId = resolved.accountId;
+  }
+```
+
+One line joins it: `noteGenericPoolSelection(config, route.providerName, resolved.accountId)`.
+The function lives in `generic-account-failover.ts` and does the flag read, the strategy read
+and the `notePoolRotationSuccess(genericPoolKey(name), id, stickyLimit)` call itself. No policy
+moves into `core.ts`, the import comes from a module `core.ts` already imports from, and the
+core-path Lab boundary is untouched — `pool-kernel.ts` pulls only two types.
+
+This is the one file in the unit that sits on every user's request path, so it takes exactly
+one statement and no branching of its own.
+
+### Change surface
+
+**`src/types/config.ts`** — add `pool?: { kernel?: boolean }` beside the existing optional flag
+objects (`resetCreditAutoRedeem` at :833 is the nearest shape). **`src/config.ts`** — add
+`pool: z.object({ kernel: z.boolean().optional() }).optional().catch(undefined)` next to
+`resetCreditAutoRedeem` at :1304. `.catch(undefined)` matches the house rule: a malformed hand
+edit turns the feature off rather than costing the operator their providers.
+
+**`src/types/provider.ts`** — add `stickyLimit?: number` to the per-provider
+`oauthAccountFailover` block at :520, with the same 1..100 range the Anthropic pool documents.
+
+**`src/oauth/generic-account-failover.ts`** — branch BOTH paths on strategy, because branching
+one leaves the setting inert in practice:
+
+| Strategy | `preferredInitialAccount` | `rotateGenericOAuthAccountOn429` |
+|---|---|---|
+| flag off, or absent/`quota` | unchanged: healthy-active return :262, `hasHeadroomEvidence` :267, `rankAccountsByHeadroom` | unchanged: ring after the failed id, then `rankAccountsByHeadroom` |
+| `round-robin` | skip BOTH guards, `peekRoundRobinAccount(genericPoolKey(name), eligible, stickyLimit)` | `pickRoundRobinAccount` over the eligible ring |
+| `fill-first` | skip the healthy-active return; keep active while its usage is under `autoSwitchThreshold`, else advance to the next eligible account | must NOT keep the failed account: advance to the next eligible one |
+
+The two guards are skipped deliberately and for different reasons, both measured in 020's audit:
+`hasHeadroomEvidence` returns false for any provider with no quota data, so leaving it in front
+of round-robin makes round-robin unreachable exactly where it is most useful; and the
+healthy-active early return fires before `autoSwitchThreshold` can ever be read, so fill-first
+would never reach its own threshold test. Keep the presence quorum, the `EXCLUDED_PROVIDERS`
+guard and the per-provider `health` cooldown on every branch.
+
+**`src/oauth/pool-settings-capability.ts`** — `inert` becomes `boolean` computed from the flag
+instead of the literal `true`. `genericPoolSettingsDto` takes the flag as a third argument
+rather than reading config itself, so the DTO stays a pure projection.
+
+**`src/server/management/oauth-account-routes.ts`** — three edits. The active PUT at :325 gains
+`seedPoolRotationAccount(genericPoolKey(provider), accountId)` beside `forgetGenericFailoverRoster`,
+or the operator's pick immediately loses to sticky rotation — the same defect wp1b just fixed on
+the Codex side, and `forgetGenericFailoverRoster` only drops the presence count, never the
+cursor. The 400 at :396 narrows to `quotaWindow` alone. The pool PUT accepts and persists
+`stickyLimit` with the 1..100 validation.
+
+**`src/cli/account-extended.ts`** — the generic branch at :395 currently hardcodes
+`const enabled = false`. With the kernel on it reports the real state.
+
+### Acceptance
+
+Criterion c-3: a test asserts a configured strategy actually changes the selected account, and
+the DTO stops reporting `inert` once the flag is on.
+
+- `tests/oauth/generic-oauth-failover.test.ts` — round-robin rotates across dispatches for a
+  provider with NO quota data (the case the evidence guard blocks today); fill-first holds the
+  active account under threshold and advances over it; quota is byte-identical to today; every
+  one of them is a no-op with `pool.kernel` off.
+- `tests/server/account-pool-management-api.test.ts` — `inert` follows the flag, `stickyLimit`
+  round-trips, `quotaWindow` still 400s. The existing marker test at :435 reads the source for
+  the literal `inert: true;` and moves with the type.
+- `tests/cli/cli-account-pool-verbs.test.ts` — the CLI reports the live threshold when on.
+- Red control for each new case, as in wp1b: the assertion must fail with its production branch
+  removed. A test that passes either way is not coverage.
+
+### Reversibility
+
+`pool.kernel` defaults off, and off means the pre-kernel code path byte for byte: the guards
+stay, the DTO still says `inert: true`, and `noteGenericPoolSelection` returns before touching
+the ring. No migration writes on upgrade; the kernel reads keys that are already persisted.
+
+### A-phase findings folded into this plan
+
+Verified while auditing the plan above, before any code was written.
+
+**The `inert` contract is published, in seven languages.** Turning `inert` into a computed
+field makes live documentation false, and AGENTS.md requires docs-site to stay in sync and
+translated locales not to contradict the English source. The statements that change:
+`docs-site/src/content/docs/reference/configuration/providers.md` :568 ("the generic selector
+does not act on it yet, so omitted and set behave the same today"), :569 ("inert until the
+selector consumes it") and :590 ("`inert: true` for those two fields only"); and
+`reference/cli/providers-accounts.md` :351 ("Generic pool thresholds are currently inert") and
+:355, whose signature literally reads `inert: true | null`. The same page exists under
+`ko`, `ja`, `fr`, `ru`, `tr`, `zh-cn` and `zh-tw`. All of it moves in this PR: a flag-gated
+feature still has to describe both states, not the old one.
+
+**The DTO marker test fails OPEN, which is worse than failing.**
+`tests/server/account-pool-management-api.test.ts:435` locates its slice with
+`source.indexOf("inert: true;", start)`. Once the type reads `inert: boolean;` that returns
+`-1`, and `source.slice(start, -1)` happily returns almost the whole file — which still
+contains "strategy", "autoSwitchThreshold" and "enabled", so all three assertions pass while
+the test has stopped checking anything. It must be rewritten against the new literal, not
+merely allowed to keep passing. This is the same failure mode wp1b was built on, so it gets
+named rather than discovered later.
+
+**`src/server/management/provider-routes.ts`:1023-1024 is a reader the plan did not name.**
+It carries `oauthAccountFailover` forward when a provider is overwritten, to stop an edit
+silently enabling rotation. It copies the whole object, so a new `stickyLimit` rides along
+with no change — verified, listed here so the next reader does not have to re-derive it.
+
+**The core-path import edge is already there.** `src/server/responses/core.ts` imports from
+`../../oauth/generic-account-failover` at :150, so adding `noteGenericPoolSelection` to that
+existing import creates no new module edge at all, and `pool-kernel.ts` imports only two
+types. `bun test tests/lab/core-lab-boundary.test.ts` is green at 17 pass / 0 fail on this
+branch and is re-run at Check.
+
+**Fill-first's stable order is `eligibleFailoverAccounts`:164**, which preserves
+`set.accounts` order from the store and filters out reauth-flagged and cooled accounts. That
+is the order the 429 ring already walks, so fill-first advances through the same sequence
+rather than inventing a second one.
+
+### Plan audit round 2 — FAIL, three blockers folded
+
+A dispatched reviewer returned FAIL on the plan above. All three blockers are real and two of
+them contradict what this document said one revision earlier. Recorded rather than quietly
+edited, because the corrections are the useful part.
+
+**Blocker 1 — fill-first must walk the SORTED FULL roster, not the eligible subset.**
+The "A-phase findings" note above claimed `eligibleFailoverAccounts`:164 is the order
+fill-first advances through. That is wrong, and it is the exact bug 020's own earlier audit
+already rejected when it added the `stableAll` argument to `pickFillFirst`. Both shipped
+copies walk a stable roster sorted with `localeCompare` — `src/codex/routing.ts`:1443 and
+`src/oauth/anthropic-routing.ts`:427 — and dropping to the eligible subset changes the wrap
+order whenever an ineligible id sits between two eligible ones. The generic roster is worse
+than unsorted-by-accident: `getAccountSet().accounts` is in LOGIN order, so two operators who
+added the same accounts in a different sequence would get different rotation. The generic
+fill-first sorts the full roster the same way, then skips ineligible ids while walking it.
+Supersedes the paragraph above.
+
+**Blocker 2 — the commit site fires on every generic dispatch, so it must gate on
+round-robin specifically.** `core.ts`:4407 is reached on every generic first dispatch,
+including the preferred-null quota path and the fallback after a preferred account is dropped
+at :4368-4388. The plan said `noteGenericPoolSelection` "does the flag read and the strategy
+read" without saying what it does with them, which is not precise enough to implement: an
+ungated call would advance round-robin sticky state for quota and fill-first pools too.
+It returns immediately unless `pool.kernel` is on AND the resolved strategy is
+`round-robin`. Anthropic already draws exactly this line — `anthropic-routing.ts`:791 notes
+rotation only on its round-robin branch — so this is matching an existing contract, not
+inventing one.
+
+**Blocker 3 — the CLI has three states, not two.** `src/cli/account-extended.ts`:402-409
+prints "unavailable" and "threshold support is unknown" whenever `inert !== true`, so a
+kernel-on `inert: false` would render the live feature as an unknown capability — the
+opposite of the truth. `tests/cli/cli-account-pool-verbs.test.ts`:393-403 also feeds
+`inert: false` through a malformed-capability loop that expects `enabled: false`. The CLI
+needs `true` (stored, not applied), `false` (applied) and `null`/absent (unknown) as three
+distinct renderings, and that test's fixture must stop conflating the middle one with
+malformed input.
+
+**Major folded — an exact-equality DTO assertion.**
+`tests/server/account-pool-management-api.test.ts`:477 asserts the generic GET body with
+`toEqual`, so adding `stickyLimit` breaks it. :484 uses `toMatchObject` and is safe. The PUT
+round-trip at :486 breaks only once PUT actually persists the field. All three move with the
+change.
+
+**Major folded — `src/cli/capabilities.ts`:331** also publishes the inert contract, alongside
+the docs-site pages already listed.
+
+**Correction — anchor.** This document cited `hasHeadroomEvidence` at :267; that is where its
+comment begins. The call is at :272. The anchor table itself was verified correct.
+
+**Confirmed, no action —** the reviewer independently reached the same conclusion on the Lab
+boundary: `core.ts` already imports `generic-account-failover`, and `pool-kernel.ts` is
+`import type` only, which the boundary walker skips. No new edge.
diff --git a/devlog/_plan/260911_account_pool_unification/030_phase3_cache_affinity.md b/devlog/_plan/260911_account_pool_unification/030_phase3_cache_affinity.md
new file mode 100644
index 0000000000..dcf7ac9924
--- /dev/null
+++ b/devlog/_plan/260911_account_pool_unification/030_phase3_cache_affinity.md
@@ -0,0 +1,239 @@
+# Phase 3 — cache affinity ranks ahead of quota
+
+Base: the phase-2 layer, and all three open assumptions in 000_plan.md closed
+first. This is the speculative layer and does not ride the first train.
+
+## Thesis
+
+For subscription accounts, moving account destroys the prompt cache, so affinity
+is consulted before quota. For API keys it is not, which is why phase 4 keeps a
+different policy.
+
+## Current behaviour (verified on dd9a2906b)
+
+Stickiness exists but is not cache-driven.
+
+Codex binds on thread identity: codexPoolAffinityKey (src/codex/auth-context.ts)
+from x-codex-parent-thread-id or an HMAC of session and thread id, bound by
+bindThreadAffinity (routing.ts:1262), read at :1090. LRU cap
+CODEX_THREAD_AFFINITY_MAX_ENTRIES = 2048 (:135), pruned oldest-first at
+:1211-1234, idle TTL 24h (:134).
+
+Anthropic binds on a session key: anthropicSessionKeyFromParts
+(anthropic-routing.ts:877) prefers client, session and thread id and treats
+promptCacheKey as a last resort, discarding it entirely when
+promptCacheKeyIsSharedCohort (:894). Cap MAX_AFFINITY_ENTRIES = 2000 (:48),
+evict oldest by lastUsedAt (:468-471).
+
+Generic OAuth has no affinity at all (module comment :1-15).
+
+reevaluateAffinityQuota (routing.ts:1942) may rebind a live thread when the quota
+strategy is active and usage passes autoSwitchThreshold (:2164-2170); round-robin
+and fill-first stay sticky (:2157-2160).
+
+accountPoolStickyLimit is not a binding-count cap. It is the number of successful
+binds retained on one round-robin selection, default 1 (src/types/config.ts:841,
+pool-rotation.ts:167-171 and :204-216), so at the default it never even sets
+activeKey. The real caps are the two LRU limits above.
+
+No minimum-token cache gate exists anywhere: there is no cacheThreshold or
+minCacheTokens, and applyPromptCaching (src/adapters/anthropic.ts:100) places
+cache_control without a size check. MAX_CACHE_BREAKPOINTS = 4 (:60) is the only
+real cache numeric.
+
+## Open assumptions this phase must close first
+
+1. Affinity key shape. Codex keys on thread, Anthropic on session. Proposed
+   shared shape, to confirm before implementation: a composite of tenant,
+   conversation, provider and model, which is what cache-affine proxy practice
+   recommends over hashing the request body.
+2. Shared cohort. Today a shared-looking prompt_cache_key discards affinity
+   entirely. Decide whether to fall back to another identifier instead.
+3. Minimum cache size. Decide whether to implement a minimum-token gate and the
+   Anthropic 1024 and 2048 breakpoint minimum locally.
+
+## Change surface (provisional, re-verify at P)
+
+NEW src/oauth/affinity-key.ts - one composite key builder used by Codex,
+Anthropic and the generic kind through the phase-2 kernel.
+
+MODIFY the kernel selection order so that, for pools marked cache-sensitive, a
+live affinity binding outranks a higher-headroom candidate unless the affine
+account is exhausted. Key pools are not marked cache-sensitive.
+
+MODIFY reevaluateAffinityQuota so a rebind requires exhaustion rather than merely
+passing the threshold, because a threshold rebind throws away a warm cache.
+
+## Tests
+
+A cache-affine account is chosen over a higher-headroom one; an exhausted affine
+account still yields; concurrent distinct sessions keep distinct accounts; a
+shared-cohort cache key does not collapse every session onto one account.
+
+## Staleness re-verification and why this phase is not open yet
+
+Re-verified at the wp3 P entry against `origin/dev` `1da8dae96`. Every anchor this
+document relies on is unchanged from the original reading:
+
+| Symbol | File | Line |
+|---|---|---|
+| `CODEX_THREAD_AFFINITY_MAX_ENTRIES` | `src/codex/routing.ts` | 135 |
+| `pruneLruThreadAffinities` | `src/codex/routing.ts` | 1212 |
+| `reevaluateAffinityQuota` | `src/codex/routing.ts` | 1942 |
+| `MAX_AFFINITY_ENTRIES` | `src/oauth/anthropic-routing.ts` | 48 |
+| `anthropicSessionKeyFromParts` | `src/oauth/anthropic-routing.ts` | 877 |
+| `promptCacheKeyIsSharedCohort` | `src/oauth/anthropic-routing.ts` | 883 |
+| `MAX_CACHE_BREAKPOINTS` | `src/adapters/anthropic.ts` | 60 |
+
+The design is therefore current. Two things still stop this phase from opening,
+and neither is a documentation gap:
+
+1. **Its three open assumptions are genuine product decisions, not research gaps.**
+   The affinity key shape, what to do when a `prompt_cache_key` looks like a shared
+   cohort, and whether to add a minimum-token cache gate all change observable
+   behaviour and none is settled by reading the code. They need a human answer.
+   Under an active goal the Interview is suppressed, so this phase cannot resolve
+   them from inside the loop.
+2. **The Codex half is frozen.** `src/codex/routing.ts` carries three of the seven
+   anchors above and is owned by lane L3 for the dispatch round in flight.
+
+The Anthropic and generic halves are not frozen, so a narrower first slice exists:
+unify the affinity key for those two kinds only, leaving the Codex thread-affinity
+map on its current key until the freeze lifts. That slice still needs assumption 1
+answered, which is why this phase stays closed rather than being re-scoped now.
+
+## wp3 plan — what criterion c-4 actually requires
+
+This phase was recorded as blocked on three product decisions: the shared affinity key shape,
+the shared-cohort `prompt_cache_key` fallback, and a minimum-token cache gate. Re-reading the
+criterion against the code shows none of the three is on the path to it.
+
+> c-4: Account selection consults cache affinity before quota for subscription pools, proven by
+> a test where the cache-affine account is chosen over a higher-headroom one.
+
+That is a statement about **ordering**, not about key shape. The phase title pairs ordering with
+"a unified affinity key", but only the ordering half is an acceptance criterion, and the two are
+separable: reordering uses each kind's EXISTING affinity binding and introduces no new key.
+Assumption 1 gates the unified key, not this. Assumption 2 is a property of the Anthropic
+session-key derivation, which the ordering change does not touch. Assumption 3 is explicitly
+optional in the original text ("decide whether to implement") and is not required by c-4.
+
+So the unified key stays open and stays out of this cycle. The ordering ships now.
+
+## Only one kind actually breaks cache affinity
+
+Verified on the branch head rather than assumed:
+
+- **Anthropic already honours affinity unconditionally.** `src/oauth/anthropic-routing.ts`:604-610
+  returns `{ reason: "affinity" }` whenever the affined account is present, not reauth-flagged,
+  not cooled and credential-usable. `autoSwitchThreshold` governs NEW-session picks
+  (`anthropicAutoSwitchThreshold`, :111) and never rebinds a live session.
+- **Codex does not.** `reevaluateAffinityQuota` (`src/codex/routing.ts`:2031) rebinds a live
+  thread whenever the quota strategy is active and usage crosses `autoSwitchThreshold` (:2047),
+  which throws away a warm prompt cache on a hint rather than on evidence.
+- The generic OAuth kind has no affinity at all, so it has nothing to reorder.
+
+That makes this a one-function change, and it makes the criterion's "pools" plural satisfiable:
+after it, both subscription pools keep a bound conversation on its account until that account
+genuinely cannot serve.
+
+## Change surface
+
+`src/codex/routing.ts`, `reevaluateAffinityQuota` only. Under `pool.kernel`, the rebind bar
+stops being "crossed the threshold" and becomes the same **drained** test the pin-release path
+already uses (`releaseDrainedCodexAccountPin`, :1866):
+
+```
+!isCodexAccountUsable(config, entry.accountId, selectionOptions)
+  || !hasCodexQuotaHeadroom(config, entry.accountId, selectionOptions, now)
+```
+
+Reusing that predicate rather than inventing a second notion of "spent" is deliberate: two
+definitions of exhausted in one file is how they drift. The reeval-interval short circuit keeps
+its current shape so a bound thread is still not re-scored more than once a minute.
+
+Flag off restores today's behaviour exactly, which is what makes shipping this without the three
+open decisions safe rather than presumptuous.
+
+## Acceptance
+
+- A bound thread on an account at 90% usage with `autoSwitchThreshold: 80` and a sibling at 10%
+  KEEPS its account while the flag is on — the cache-affine account chosen over the
+  higher-headroom one, which is c-4 verbatim.
+- The same fixture with the flag off still moves, so the old behaviour is provably intact.
+- A bound thread whose account is genuinely drained still moves with the flag on, so the change
+  is a reordering and not a pin.
+- Red control: with the flag branch removed, the first case must fail.
+
+### wp3 plan audit — FAIL, folded
+
+**Blocker 1 — the "drained" bar I proposed IS the threshold.** `releaseDrainedCodexAccountPin`
+reads `!isCodexAccountUsable || !hasCodexQuotaHeadroom`, and `hasCodexQuotaHeadroom`
+(`src/codex/routing.ts`:1387-1395) is `usage < (autoSwitchThreshold ?? 80)`. Reusing it inside
+`reevaluateAffinityQuota` would have preserved today's 80% rebind exactly, so the plan's own
+acceptance case — a bound thread at 90% with threshold 80 KEEPING its account — could not have
+passed. The argument for reuse ("don't invent a second notion of spent") was right in spirit and
+wrong in fact: the pin path deliberately releases at the auto-switch crossing, which is a
+different question from whether the account can still serve.
+
+The bar this phase needs is genuine exhaustion, and it is not expressible as the existing
+predicate. Definition used instead, local to the reeval and stated once:
+
+```
+spent = !isCodexAccountUsable(config, id, selectionOptions)   // reauth, excluded, cooled
+     || (!isUnknownUsage(usage) && usage >= 100)              // allowance actually gone
+```
+
+Per minor 7 the usable half is already guaranteed by the caller, which requires
+`isCodexAccountSelectable`, so in practice the test reduces to the usage half — kept explicit
+anyway so the predicate reads correctly on its own.
+
+**Major 3 — `previewReusableAffinityAccount` duplicates the same threshold move.**
+`src/codex/routing.ts`:1984 carries its own copy for the preview path. Changing only the
+mutating site would make `previewCodexAccountForRequest` disagree with
+`resolveCodexAccountForThreadDetailed` — and the suite already contains cases asserting those
+two agree. Both move together.
+
+**Major 4 — the reeval interval must stop keying off the old bar.** The short circuit stamps
+`lastReevalAt` only when `overThreshold`, so leaving it as-is while the rebind bar changes
+re-scores a thread on every request through the whole 80-99% band. The short circuit follows the
+new bar, keeping the once-a-minute ceiling intact.
+
+**Minor 6, taken — the flag is wrong.** `pool.kernel` is the generic-OAuth strategy-consume
+flag introduced in wp2b; reusing it for a Codex affinity rule would overload one switch with two
+unrelated meanings and make either one impossible to turn on alone. This uses its own
+`pool.cacheAffinity`, defaulting off.
+
+**Minor 5 recorded.** `tests/codex-integration/codex-routing.test.ts` contains cases that require
+the immediate over-threshold switch. They stay green because the flag defaults off, and that is
+the check that proves flag-off is byte-identical rather than merely claimed.
+
+### Major 2 — rebutted, with its limit stated
+
+The audit is right that today's stickiness is keyed on thread and session identity rather than
+on a cache key, and that a thread-keep test therefore proves "identity stickiness outranks
+quota", not "a measured cache is consulted". That distinction is real and is exactly what the
+deferred unified key would close.
+
+It does not block c-4. In this codebase the thread/session binding IS the mechanism by which a
+warm prompt cache stays reachable: the cache lives on the account that served the conversation,
+so keeping the conversation there is what preserves it. c-4 asks that the affine account win
+over a higher-headroom one, and after this change it does. What remains open — and is recorded
+as open rather than quietly satisfied — is making the binding explicitly cache-derived instead
+of identity-derived. The criterion's plural "pools" is likewise honest only because Anthropic
+already holds its live sessions; this change brings Codex to the behaviour Anthropic has, rather
+than adding a second implementation.
+
+### The "## Change surface" block above is SUPERSEDED
+
+It still names `pool.kernel`, `hasCodexQuotaHeadroom` and `reevaluateAffinityQuota` alone.
+Implementing it as written fails three of the folded findings and cannot pass the 90% keep case.
+The fold is the spec. Concretely, the build is:
+
+- `src/types/config.ts` and `src/config.ts` — `pool.cacheAffinity?: boolean`, default off.
+- `src/codex/routing.ts` `reevaluateAffinityQuota` AND `previewReusableAffinityAccount` — both
+  copies swap the rebind bar to `!isCodexAccountUsable || (!isUnknownUsage(usage) && usage >= 100)`
+  when the flag is on, and the `lastReevalAt` short circuit keys off that same bar.
+
+The pre-audit block stays as the record of what was planned before the audit rather than being
+rewritten to look correct.
diff --git a/devlog/_plan/260911_account_pool_unification/040_phase4_key_pool_strategy.md b/devlog/_plan/260911_account_pool_unification/040_phase4_key_pool_strategy.md
new file mode 100644
index 0000000000..810e5256db
--- /dev/null
+++ b/devlog/_plan/260911_account_pool_unification/040_phase4_key_pool_strategy.md
@@ -0,0 +1,395 @@
+# Phase 4 — API keys gain proactive selection
+
+Base: dev directly. This layer is NOT in the chain: key-failover shares no module
+with the OAuth kernel, and an API key is a different identity from an OAuth
+account set. The A-phase audit reparented it here.
+
+## Thesis
+
+API-key pools get a proactive strategy before the first attempt, while keeping
+the existing reactive 429 and 401 rotation as the fallback.
+
+## Current behaviour (verified on dd9a2906b)
+
+src/providers/key-failover.ts is reactive only. hasKeyPoolFailover (:98-101)
+requires authMode not oauth or forward and apiKeyPool length at least 2.
+Selection is a circular index walk in rotateKeyAfterFailure (:220-233) starting
+from the failed entry, skipping cooled keys. Cooldown state is a local map
+(:19-53) keyed by provider and key id. Wrappers: rotateKeyOn429 (:269-278),
+rotateKeyOn401 (:288-296), rotateProviderTransportOn429 (:322-338).
+
+src/providers/api-keys.ts listProviderApiKeys (:62-80) returns the pool and an
+activeId with no strategy. src/types/provider.ts:384-389 defines apiKeyPool as
+id, key, label and addedAt only.
+
+The pre-dispatch hook points are in src/server/responses/core.ts: :4188-4190
+(refreshDispatchAdapter calling resolveCurrentProviderApiKeyTransport) and
+:4437-4444 (resolveProviderTransport after OAuth resolution). The OAuth side has
+preferredInitialAccount at :4335-4340 with the comment that it prefers a known
+headroom account before the first attempt; API keys have no analogue.
+
+## Change surface
+
+MODIFY src/types/provider.ts - add an optional per-provider key-pool strategy
+field. Do not reuse the OAuth account-pool field names; these are different
+identities and phase 5 owns the operator surface.
+
+MODIFY src/providers/key-failover.ts - add a proactive selector invoked from the
+pre-dispatch sites, supporting round-robin and a rate-limit-aware order. Keep
+:220-233 exactly as the 429 and 401 fallback.
+
+MODIFY src/server/responses/core.ts at :4188 and :4437 to consult the selector
+before the first attempt. The mid-retry resolveProviderTransport calls at :4119,
+:5399, :5503 and :7346 stay recovery paths and are not touched.
+
+## Policy difference from OAuth pools, stated deliberately
+
+Key rotation is a rate-limit scheduling problem: keys usually share an account or
+organization, so moving key costs little cache. Subscription accounts lose their
+prompt cache on every move. That is why phase 3 puts affinity ahead of quota for
+accounts and this phase does not for keys.
+
+## Security
+
+key-failover already logs failedId and candidateId. The new selector must not
+inherit that shape, and must log no key identity. privacy:scan stays green.
+
+## Tests
+
+A configured round-robin strategy changes the first-attempt key; the reactive 429
+and 401 walk still works when the strategy is unset; a cooled key is skipped by
+both paths; a single-key pool is a no-op.
+
+## Out of scope
+
+No operator-visible surface. Phase 5 owns the management route and GUI; adding
+fields there from this layer would collide with it.
+
+## wp4b wiring plan (re-verified against `codex/generic-pool-kernel`)
+
+#4277 shipped `selectProactiveApiKey` (`src/providers/key-failover.ts`:128) and deliberately
+stopped there: the picker exists, is unit-tested, and is called from nowhere in production. So
+does `forgetApiKeyRotationCursor` (:112). This unit connects both, and nothing else.
+
+| Symbol | File | Line |
+|---|---|---|
+| `selectProactiveApiKey` | `src/providers/key-failover.ts` | 128 |
+| `forgetApiKeyRotationCursor` | `src/providers/key-failover.ts` | 112 |
+| OAuth-only branch, skipped by key-auth | `src/server/responses/core.ts` | 4322 |
+| transport pin, last `route.provider` write before the first send | `src/server/responses/core.ts` | 4450 |
+| `activeProvider` bind | `src/server/chat-native.ts` | 238 |
+| `PUT /api/providers/keys/active` | `src/server/management/oauth-account-routes.ts` | 674 |
+
+### Where the call goes, and why there
+
+`route.provider` is final for a key-auth request at the transport pin on `core.ts`:4450, and all
+four first-send consumers read that same object — the image/video bridge (:6570), web search
+(:6653), `runTurn` (:6739) and the generic HTTP path (:7174). One call placed after the OAuth
+block and before the pin therefore serves every one of them, with no per-path duplication. That
+is the exact position the OAuth side already occupies: "prefer the account with known headroom
+BEFORE the first attempt" at :4344.
+
+`chat-native.ts` is a separate entry path and needs its own call, immediately before
+`activeProvider` is bound at :238.
+
+Nothing competes with it. `resolveProviderTransport` never swaps keys, and
+`applyCodexAuthContextToProvider` is a no-op outside `authMode: "forward"`. The one pre-send
+`apiKey` rewrite that does exist (`core.ts`:4196) re-reads an already committed selection and
+does not run on a current first attempt.
+
+**No new import edge on the core path.** `core.ts` already imports `hasKeyPoolFailover` from
+`../../providers/key-failover` at :269, so the picker joins an existing import — which matters
+because `core.ts` is one of the three files that must never reach `src/lab`.
+
+### Cursor invalidation
+
+`forgetApiKeyRotationCursor` has no production caller, so the round-robin cursor currently
+outlives the pool it describes. It joins `clearKeyCooldowns(name)` at the three management
+routes that already reset key state: the manual active-key PUT at :674, and the add/remove key
+routes at :641 and :714. An operator who just chose a key should not be second-guessed by a
+cursor that predates the choice — the same rule wp1b and wp2b applied to the account pools.
+
+### Scope boundary
+
+No change to `selectProactiveApiKey` itself, to the reactive 429/401 rotation, or to the
+strategy semantics. The picker already refuses to override a healthy committed key and already
+returns null when no strategy is configured, so an install that never set `apiKeyPoolStrategy`
+executes one predicate and nothing else.
+
+### Acceptance
+
+Criterion c-5 is already met by #4277 for the selection logic; this unit adds the evidence that
+it reaches a real dispatch.
+
+- `tests/server/server-key-failover-e2e.test.ts` is the only suite that drives a real
+  first-attempt key-auth dispatch with an `apiKeyPool`, so it takes the new case: a two-key pool
+  whose committed key is cooled, with `apiKeyPoolStrategy` set, must send the FIRST request on
+  the other key. Red control: without the wiring the first attempt goes out on the cooled key and
+  earns the 429 the runtime could already predict.
+- A second case pins the no-op: with no `apiKeyPoolStrategy`, the committed key is used
+  unchanged even when cooled, because rotation stays reactive-only for that install.
+- A cursor case: a manual key selection through `PUT /api/providers/keys/active` clears the
+  rotation cursor.
+
+### Plan audit — FAIL, folded
+
+**Blocker 1 — the picker does not mutate the route.** `selectProactiveApiKey` writes
+`config.providers[name]` and RETURNS a clone; it never touches `route.provider`. The plan said
+"wire the call" without saying what to do with the return, which is not implementable: a literal
+reading leaves the live route on the cooled key and the whole unit is a no-op that still writes
+config. The call site is:
+
+```
+const picked = selectProactiveApiKey(config, route.providerName, now);
+if (picked) route.provider = picked;
+```
+
+**Blocker 2 — the assignment must land before the copies, not merely before the send.**
+"One call serves all four consumers" is true only because nothing reassigns `route.provider`
+between the pin and each consumer — but they do not all read it late. `adapterProvider` is
+copied at `core.ts`:4458 and the adapter is bound at :4477, and the HTTP path captures
+`builtInitialRequest` at :7139. So the assignment goes BEFORE :4450, ahead of every copy. The
+audit also showed why this cannot be left to self-healing: the HTTP and `runTurn` paths can
+re-read a stale selection through `refreshDispatchAdapter` (:4197), but the image bridge
+(:6570) and web search (:6655) call `providerFetch(route.provider)` directly and have no such
+second chance. Ordering is the entire correctness argument here.
+
+**Major 1 accepted, with the reason recorded.** Putting the picker on the first-attempt path
+means an ordinary request can now perform a persisted config write. It is bounded: the picker
+returns null unless a strategy is configured AND the committed key is already cooled, so a
+healthy install does one predicate and stops. The write goes through the same
+`commitProviderApiKeySelection` / `mutatePersistedConfig` lock the reactive rotation uses, and a
+later same-request 429 rotation serializes behind that lock rather than racing it. The cost is
+paid exactly once per cooldown, replacing a request that was otherwise spent earning a 429 the
+runtime could already predict.
+
+**Major 2 — two first-send paths this unit does NOT cover, named rather than silently dropped.**
+Native compact for `openai-apikey` (`src/server/responses/compact.ts`:669, dispatch at :745-883)
+never enters `core.ts`, and the keyed `/v1/images` path (`src/server/images.ts`:701) reads
+`candidates.keyed.apiKey` directly rather than a provider object. Each has a different
+provider-resolution shape and needs its own dispatch harness, so they become their own
+work-phase instead of riding along untested here. `collaboration.ts` and
+`encrypted-payload.ts` are NOT affected: they import `rotateProviderTransportOn429` and
+dispatch no first attempt.
+
+**Minors folded.** The web-search fetch is `core.ts`:6655, not :6653 (that line is a comment).
+The stale-selection re-read is :4197, not :4196. `src/server/management/provider-routes.ts`:832
+and :931 also `clearKeyCooldowns` on key replace and delete, so the cursor reset belongs there
+too — five routes, not three.
+
+## wp4 plan — quota-aware API key selection
+
+wp4b wired the picker in; this gives it the third strategy. Today
+`apiKeyPoolStrategy` accepts only `round-robin` and `fill-first`
+(`src/config.ts`:586, `src/types/provider.ts`:399), so an API key pool cannot do what every
+other pool in this codebase already does: prefer the credential with the most room left.
+
+| Symbol | File | Line |
+|---|---|---|
+| `apiKeyPoolStrategy` schema | `src/config.ts` | 586 |
+| `apiKeyPoolStrategy` type | `src/types/provider.ts` | 399 |
+| `selectProactiveApiKey` strategy read | `src/providers/key-failover.ts` | 135 |
+| per-key quota cache (private) | `src/providers/quota-key-accounts.ts` | 22 |
+| `identity()` cache key | `src/providers/quota-key-accounts.ts` | 50 |
+| `readProviderApiKeyQuotas` | `src/providers/quota-key-accounts.ts` | 101 |
+| `keyQuotaReaderForProvider` | `src/providers/quota.ts` | 2897 |
+| editor field list | `src/server/auth-cors.ts` | 821 |
+
+### The one real obstacle: the selector is synchronous, the quota reader is not
+
+Per-key quota already exists — `keyQuotaReaderForProvider` serves seventeen providers — but it
+is reached only through `readProviderApiKeyQuotas`, which is `async` and probes the network on a
+miss. `selectProactiveApiKey` is synchronous and sits on the first-attempt path, where it must
+not await anything.
+
+So `quota-key-accounts.ts` grows one cache-only, synchronous reader:
+
+```
+export function cachedApiKeyQuota(name, provider, keyId, key): ProviderQuota | null
+```
+
+It recomputes the same `identity()` the async path stores under, reads `cache`, and returns
+null on a miss. It never probes, never awaits and never schedules one — a selector that could
+trigger a network read on the request path would be a worse defect than the one this unit
+fixes. A miss is simply "no evidence", which is the same word the OAuth side uses.
+
+Env-placeholder keys resolve through `resolveProviderApiKey` exactly as the async path does,
+inside a try/catch: an unresolvable key is a miss, not a throw on the dispatch path.
+
+### Ranking, and what happens without evidence
+
+`quota` ranks the eligible keys by remaining headroom and takes the roomiest. When NO eligible
+key has a cached row, it falls back to the first eligible key — which is what `fill-first`
+already does, and therefore exactly today's behaviour for a provider whose quota reader does not
+exist or has never run.
+
+That is deliberately NOT the OAuth rule. `preferredInitialAccount` returns null without
+evidence because its active account is still perfectly usable. Here the function has already
+established that the committed key is cooling, so returning null would mean deliberately
+dispatching on a spent key. There is no no-op available; the only question is which replacement.
+
+### Change surface
+
+`src/providers/quota-key-accounts.ts` — add `cachedApiKeyQuota` and a
+`setCachedProviderApiKeyQuotaForTests` seam mirroring the account-side
+`setCachedProviderAccountQuotaForTests`, because a synchronous reader of a private cache is
+otherwise untestable without a live probe.
+
+`src/types/provider.ts`:399 and `src/config.ts`:586 — widen the union to include `quota`.
+`src/server/auth-cors.ts`:821 already lists the field as editor-visible and needs no change.
+
+`src/providers/key-failover.ts` — a third branch in `selectProactiveApiKey`. `round-robin` and
+`fill-first` keep their current code paths byte for byte.
+
+### Acceptance
+
+- `tests/adapters/key-failover.test.ts`: the roomiest eligible key wins; a cooled roomier key is
+  skipped; with no cached rows the first eligible key is taken; an unknown strategy value still
+  degrades to no-op. Red control for each: with the `quota` branch removed the ranking cases must
+  fail.
+- `apiKeyPoolStrategy` is currently undocumented in `docs-site` — no row exists anywhere. It
+  gains one in `reference/configuration/providers.md` describing all three values, since shipping
+  a third undocumented value is how the generic pool ended up inert and unexplained.
+
+### wp4 plan audit — FAIL, folded
+
+**Blocker 1 — a cache hit is not evidence.** `readEntry` stores `{ unavailable: true, quota:
+lastGood }` for up to `LAST_GOOD_MS` (30 minutes) when a probe fails, so the row survives with a
+stale measurement attached. A reader that returns `entry.quota` on any hit would rank on a
+number taken up to half an hour ago from a probe that has since been failing — and rank it
+ABOVE a key with no row at all. `cachedApiKeyQuota` returns null whenever `entry.unavailable`
+is set or `entry.quota` is null. Last-good is a display value; it is not a selection input.
+
+**Blocker 2 — the ranking was not specified, and the obvious formula does not work.**
+"Remaining headroom" is undefined for `ProviderQuota`, which carries `fiveHourPercent`,
+`weeklyPercent`, `monthlyPercent`, `customWindows[].percent` and `creditsUsd`. The definition
+this unit uses, matching `headroomOf` on the OAuth side so the two pools cannot disagree:
+
+`headroom = 100 - max(fiveHourPercent, weeklyPercent, monthlyPercent, ...customWindows.percent)`,
+and null when none of those is a number. `creditsUsd` is deliberately excluded: it is a
+currency amount, not a percentage, and mixing the two scales produces an ordering that means
+nothing.
+
+**Mixed evidence needs a rule and now has one**, borrowed from
+`rankAccountsByHeadroom`'s three buckets rather than invented: measured-with-headroom first
+(most headroom wins), then unmeasured, then measured-and-exhausted, with the stable roster order
+breaking ties. An unmeasured key is not assumed spent, and it is not assumed fresh either.
+
+**Recorded, not fixed — providers whose rows cannot discriminate.** DeepSeek reports every key
+at `customWindows.percent: 0`, so all headrooms tie at 100 and the pick falls through to the
+stable order, which is exactly today's behaviour. That is the correct outcome for a provider
+that publishes no per-key differentiation, and it is why the fallback has to be a real ordering
+rather than an error.
+
+**Major 1 — "unknown strategy is a no-op" was wrong.** Today any truthy value that is not
+`round-robin` takes the `eligible[0]` default, which IS fill-first; zod is the only thing
+rejecting junk. So the new branch is `else if (strategy === "quota")` placed after the
+round-robin block and BEFORE that default. Replacing the default would silently retarget
+fill-first. The acceptance bullet claiming a no-op is struck.
+
+**Major 2 — the test seam cannot mirror the account-side signature.** The key cache is keyed on
+`identity(name, provider, id, resolvedKey)`, so the seam takes the provider name, the provider
+config, the key id and the raw key, not `(provider, accountId, quota)`.
+
+**Minors folded.** `keyQuotaReaderForProvider` is at `quota.ts`:2898, not :2897. The e2e helper
+added in wp4b types its strategy parameter as `"round-robin" | "fill-first"` and widens with the
+union. The provider count is approximate and the claim is dropped. `resolveProviderApiKey` is
+synchronous and swallows its own failures, so the try/catch is belt-and-braces rather than
+required — kept, and labelled as such.
+
+**Deliberate:** a `quota` pick still records `keyRotationCursor`. The cursor is where the pool
+last was, not a round-robin private; leaving it accurate means switching an operator to
+`round-robin` later resumes from the key actually in use instead of the start of the ring.
+
+## wp4c plan — the two first-send paths that never enter core.ts
+
+wp4b wired `selectProactiveApiKey` into the Responses core and native chat. The audit that
+produced it named two dispatch paths those two call sites do not cover, and they became this
+unit rather than riding along untested.
+
+| Seam | File | Line | Shape |
+|---|---|---|---|
+| native compact | `src/server/responses/compact.ts` | 745-746 | `compactProvider` object; key applied as a header |
+| keyed images | `src/server/images.ts` | 701-703 | `candidates.keyed` destructured to `{ provider, apiKey, providerName }` |
+
+Both are genuinely independent: native compact runs only when
+`supportsNativeResponsesCompactEndpoint` accepts the destination and never reaches
+`handleResponses`, and the keyed image path builds its own URL and Authorization header
+without a route object at all.
+
+### One seam per file, and only first sends
+
+`compact.ts`:745 is the native-compact branch:
+
+```
+if (compactProvider.authMode !== "forward" && compactProvider.apiKey) {
+  headers.set("authorization", `Bearer ${resolveProviderApiKey(compactProvider.apiKey)}`);
+```
+
+The pick goes immediately above it, reassigning `compactProvider` from the returned clone —
+the same assign-then-use shape wp4b established, and for the same reason: the picker returns a
+clone and never mutates its argument.
+
+`images.ts`:701 destructures `{ provider, apiKey, providerName }`. The pick runs before the
+destructure so the header below is built from the chosen key.
+
+**Explicitly NOT a seam:** `compact.ts`:446 sits inside `resolveAlternateCompactContext`, which
+runs after a failure. It is the compact analogue of the 429 rotation loops and must stay
+reactive; putting a proactive pick there would move a retry off the account the retry exists to
+replace.
+
+### What stays out
+
+No change to `selectProactiveApiKey`, to the reactive rotation, or to the strategies. The picker
+already returns null unless a strategy is configured AND the committed key is cooling, so an
+install that never set `apiKeyPoolStrategy` evaluates one predicate on each of these paths and
+stops — including the persisted-write path, which is never reached.
+
+### Acceptance
+
+- A cooled committed key with a configured strategy is replaced on the FIRST native-compact send
+  and on the FIRST keyed image send, proven end to end rather than by unit-calling the picker.
+- Without a configured strategy both paths still use the committed key, so rotation stays
+  reactive-only for an install that never asked otherwise.
+- Red control: with each call site removed, its case must fail with the cooled key on the wire.
+- The Lab boundary suite runs, because `compact.ts` imports from the same module family the core
+  path does.
+
+### wp4c plan audit — PASS-WITH-FINDINGS, folded
+
+**Major 1 — the images seam carries a resolved SNAPSHOT, not a live field.**
+`candidates.keyed.apiKey` is built once by `selectImagesProvider` (`src/server/openai-sidecar.ts`:237-238,
+:282), so the literal "pick, then destructure" would set the Authorization header from the OLD
+key while the picker had already persisted the new one — a request on a cooled key plus a config
+write, which is strictly worse than doing nothing. The header is rebuilt from the returned clone
+through `resolveProviderApiKey` instead.
+
+This is the same class of mistake wp4b's blocker caught: the picker returns a clone and mutates
+nothing, so every seam has to be asked "what does the send actually read?" rather than "did I
+call it".
+
+The call also stays INSIDE the `candidates.keyed` branch rather than moving up next to
+`selectImagesProvider`. Higher up it would run — and write config — even on requests that
+ChatGPT forward goes on to serve, spending a rotation on a path that never used the key.
+
+**Minor 2 — gate the compact reassignment.** `compactProvider` starts as `route.provider` and is
+overlaid only for `codexAccountMode` or custom reserve-forward. The picker returns null for
+forward providers, so an ungated assign would be harmless today, but it stays inside the
+existing `authMode !== "forward" && apiKey` branch so a future overlay cannot be clobbered by
+accident. The provider name to pass is `route.providerName`.
+
+**Minor 3 — my lease concern was overstated, corrected.** Key-auth native compact does not hold
+host-circuit admission at all: `preAuthUpstreamHostCircuitKey` requires
+`codexAccountMode === "pool"` with `authMode === "forward"`. Turn admission is a counter and the
+config write is SQLite, so there is no shared mutex to deadlock on and the lease stays valid —
+the same situation wp4b already ships at the core seam. The plan's caution was unfounded and is
+struck rather than left standing as a vague worry.
+
+**Minor 4 — confirmed there are no other first-send key applications in either file.**
+`compact.ts`:289 and :380 are 401 refresh paths, and :446 is the 429/402 pool alternate.
+
+**Both paths are e2e-testable**, which is what lets the acceptance claim an end-to-end proof
+rather than a unit call: native compact through the openai-apikey harness in
+`tests/adapters/openai/openai-api-virtual-models.test.ts`, and the keyed image path through
+`tests/server/server-images.test.ts`, whose keyed fallback already asserts a specific Bearer.
+The cooled-committed-key setup is the one wp4b built in `server-key-failover-e2e.test.ts`.
diff --git a/devlog/_plan/260911_account_pool_unification/050_phase5_surface_consolidation.md b/devlog/_plan/260911_account_pool_unification/050_phase5_surface_consolidation.md
new file mode 100644
index 0000000000..08953085b7
--- /dev/null
+++ b/devlog/_plan/260911_account_pool_unification/050_phase5_surface_consolidation.md
@@ -0,0 +1,491 @@
+# Phase 5 — three contracts and two GUIs become one
+
+Base: the phase-2 layer. Opens once the kernel lands.
+
+## Thesis
+
+One pool-settings contract and one operator surface, so a new pooled provider
+needs configuration rather than another name branch.
+
+## Current behaviour (verified on dd9a2906b)
+
+Three management contracts:
+
+1. Codex only. src/codex/auth-api.ts handleCodexAuthAPI :2477-2515 handles PUT
+   and PATCH /api/codex-auth/pool-strategy, writing accountPoolStrategy and
+   accountPoolStickyLimit. There is no GET on this path.
+2. Anthropic versus generic. src/server/management/oauth-account-routes.ts
+   handleOauthAccountRoutes branches on provider !== "anthropic": GET :348-361,
+   PUT and PATCH :373-423 with stickyLimit and quotaWindow rejected at :395-396,
+   and the anthropic write at :424-483.
+3. Registry. src/server/management/route-registry.ts :95 and :110 for the Codex
+   path, :263, :270 and :283 for the oauth pool path.
+
+Two GUI surfaces, one shared control:
+
+- shared gui/src/components/AccountPoolStrategyControls.tsx :42 and
+  gui/src/account-pool-strategy.ts, whose putCodexPoolStrategy :58-65 posts to the
+  Codex-only route
+- Codex gui/src/components/CodexPoolStrategySetting.tsx :33 and :174
+- Anthropic gui/src/components/provider-workspace/AnthropicAccountPoolSettings.tsx
+  :63 GET and :117 PUT, hardcoded to provider=anthropic
+- mounted by a name branch in
+  gui/src/components/provider-workspace/ProviderAuthPanel.tsx :387-389,
+  item.name === "anthropic" only, so the generic kind has an API and no UI
+
+i18n: 36 accountPool.* keys in gui/src/i18n/en.ts :1981-2023, and every catalog in
+gui/src/i18n/catalogs.ts :24-33 already carries 36. All nine stay in sync.
+
+## Change surface
+
+NEW one pool-settings DTO covering every kind, served from a single route pair
+under the oauth-account-routes module, with the Codex path kept as a deprecated
+alias that forwards rather than duplicating the write.
+
+MODIFY ProviderAuthPanel to mount the pool panel from the capability returned by
+poolSettingsCapability instead of item.name === "anthropic".
+
+MODIFY AnthropicAccountPoolSettings into a kind-driven component; keep
+AccountPoolStrategyControls as the shared control it already is.
+
+MODIFY the i18n catalogs together. Any new key lands in all nine files in the same
+commit, per the docs-sync rule in AGENTS.md.
+
+## Boundary with phase 4
+
+This layer owns oauth-account-routes.ts, the route registry entries and the GUI
+pool surfaces. Phase 4 keeps key-strategy fields out of those files. If the key
+pool needs an operator surface, it arrives here after both have landed, not in
+parallel.
+
+## Tests
+
+tests/server/account-pool-management-api.test.ts for the unified DTO and the
+deprecated alias; tests/cli/cli-account-pool-verbs.test.ts for CLI parity; a GUI
+test that the panel mounts for a generic OAuth provider. A gui-labelled PR needs a
+screenshot in its description per AGENTS.md.
+
+## wp5 plan — one pool-settings contract
+
+## What "three contracts" actually means
+
+Not three routes with one shape. Three shapes, three storage locations and three
+re-implementations of the same validation.
+
+| Kind | Route | Storage | DTO fields |
+|---|---|---|---|
+| Codex | `PUT /api/codex-auth/auto-switch`, `PUT\|PATCH /api/codex-auth/pool-strategy` | `runtimeConfig.autoSwitchThreshold`, `.accountPoolStrategy`, `.accountPoolStickyLimit` | threshold; strategy + stickyLimit, split across two routes |
+| Anthropic | `GET\|PUT\|PATCH /api/oauth/accounts/pool?provider=anthropic` | `config.anthropicAccountPool` | enabled, autoSwitchThreshold, strategy, stickyLimit, quotaWindow, `experimental: true` |
+| generic | same route, other branch | `providers.<name>.oauthAccountFailover` | enabled, strategy, autoSwitchThreshold, stickyLimit, `inert` |
+
+Anchors: `src/codex/auth-api.ts`:2465 and :2478; `src/server/management/oauth-account-routes.ts`:354
+and :379; `src/oauth/pool-settings-capability.ts`:57.
+
+Three consequences, all observable today. The Codex kind is the only one that cannot be READ
+through a pool route at all — the CLI reads `/api/codex-auth/active` instead
+(`src/cli/account-extended.ts`:854-887 already documents the asymmetry as a table, which is the
+tell). Every kind re-parses `strategy` and `stickyLimit` with its own copy of the same bounds.
+And a field that exists for one kind is absent rather than declared-unsupported for the others,
+so a dashboard cannot tell "this pool has no quotaWindow" from "this pool forgot to send it".
+
+## The unit
+
+**One DTO, one validator, one route. The three existing paths stay as aliases.**
+
+NEW `src/server/management/pool-settings-contract.ts` — a single `PoolSettingsDto` with every
+field the union needs and an explicit `supported` set per kind, plus one validator that owns the
+strategy names, the 1..100 sticky bound and the 0..100 threshold bound. The three kinds keep
+their own STORAGE; only the shape and the validation are shared.
+
+NEW route `GET\|PUT /api/pool/settings?provider=<name>` in
+`src/server/management/oauth-account-routes.ts`, registered in `route-registry.ts`, serving all
+three kinds through `poolSettingsCapability`.
+
+The three existing paths keep working, unchanged, delegating to the same module. This is
+additive on purpose: the management API is a public contract with CLI and GUI clients, and a
+breaking change is not what "consolidate" has to mean. The registry marks the old paths
+superseded so the next reader knows which one is canonical.
+
+MODIFY `src/cli/account-extended.ts` — the transport table at :854-887 exists precisely because
+the two contracts disagree. It collapses to one path, and the comment explaining the asymmetry
+goes with it.
+
+## Out of scope, and why
+
+**The GUI half is its own work-phase (wp5b).** `gui/src/codex-auto-switch.ts` and
+`gui/src/components/provider-workspace/AnthropicAccountPoolSettings.tsx` are two separate pool
+surfaces, and merging them is a visual change. This repository's `enforce-target` gate requires
+a screenshot in the description of any PR whose title or description mentions `gui`, which means
+building and running the dashboard to capture one. That is a real deliverable, not a formality,
+and bolting it onto a server-side PR would either skip the evidence or stall the server work
+behind it.
+
+## Acceptance
+
+- One module owns strategy/sticky/threshold validation; a bad value is rejected identically on
+  every kind, proven by a table-driven test across all three.
+- `GET /api/pool/settings?provider=` answers for Codex, Anthropic and a generic provider, and
+  each response declares which fields that kind supports rather than omitting them.
+- The three legacy paths return byte-identical bodies to today, proven by tests that predate this
+  change and must not be edited.
+- Red control: each new shared-validator case must fail if the shared bound is loosened.
+
+### wp5 plan audit — FAIL, folded
+
+**Blocker 1 — the compatibility guard this plan leans on does not exist.** "Byte-identical,
+proven by tests that predate this change and must not be edited" is false. The Codex and
+Anthropic assertions use `toMatchObject`, which passes when extra keys appear, and the Codex
+`PUT /api/codex-auth/auto-switch` test checks only status 200, never the body
+(`tests/server/account-pool-management-api.test.ts`:42, :187, :266;
+`tests/codex-integration/codex-auth-api.test.ts`:3645). Only the generic GET uses a full
+`toEqual` (:483). So the refactor would have been guarded by tests that cannot detect the
+regression they were cited for.
+
+The unit therefore starts by WRITING that guard: exact-body assertions for all three legacy
+responses, committed and green BEFORE any shared module exists. A characterization test written
+after the change proves nothing about what the change did.
+
+**Blocker 2 — "delegating to the same module" skipped the adapter.** The three routes do not
+merely differ in shape, they disagree on every axis: Codex auto-switch takes `{threshold}` and
+answers `{ok:true}`; Codex pool-strategy takes `{strategy, stickyLimit}` and answers
+`{ok, accountPoolStrategy, accountPoolStickyLimit}`; the OAuth route takes `{provider, ...}`
+and answers with different key names again. A shared handler would 400 live CLI and GUI writes.
+
+What is actually shared is narrower and still worth it: the shared module owns VALUE validation —
+the strategy names, the 1..100 sticky bound, the 0..100 threshold bound — while each route keeps
+its own request parsing and response shaping as an explicit adapter. "One validator, three
+adapters", not "one handler".
+
+**Major — a new management route is not a one-line registration.** It must appear in
+`route-registry.ts` (`tests/server/management-route-registry.test.ts` compares source and
+registry as exact pairs), AND in `src/cli/capabilities.ts` or one of the two exemption lists in
+`tests/cli/cli-capabilities.test.ts`:174/:344, AND — if capabilities change — the generated
+`skills/ocx/references/01_management_surface.md` must be regenerated, which is the gate that
+went red on #4289 this session. Also `PATCH` exists on both legacy writes while the proposed
+route was `GET|PUT` only.
+
+**Major — a fourth storage location the plan missed.** Top-level
+`config.oauthAccountFailover.enabled` (`src/types/config.ts`:917) participates in generic
+activation through `isProactivePreferenceEnabled`, but the generic DTO reads only
+`providers.<name>.oauthAccountFailover`. So `enabled: null` currently means "nothing stored
+here" while the effective answer may be `true` from the global. That is a reporting defect in
+its own right and belongs in this unit, since honest per-kind field reporting is the point.
+
+**Major — more clients than the plan named:** `gui/src/account-pool-strategy.ts`,
+`gui/src/components/.../CodexPoolStrategySetting.tsx` and `gui/src/hooks/useCodexAccountPool.ts`
+join `codex-auto-switch.ts`, and `cmdAutoSwitch` sends `threshold` where the OAuth route expects
+`autoSwitchThreshold`.
+
+**Recorded:** `docs-site/src/content/docs/reference/management-api.md`:332 already claims the
+pool route 400s for non-Anthropic providers, which stopped being true when the generic contract
+shipped. Stale before this unit; fixed by it.
+
+**Minors.** The anchor `pool-settings-capability.ts`:57 points at a comment; the kinds are
+:23-28 and `inert` is :63. The kind table omits `provider`/`kind` from the DTO rows. Codex and
+Anthropic already share `parseAccountPoolStrategy` from `pool-kernel.ts` while the generic kind
+keeps a private copy — that duplication is the smallest true instance of the problem this unit
+exists to fix, and is the natural first thing to collapse.
+
+### Status
+
+Planned and audited, NOT implemented. The audit turned a one-route consolidation into a
+four-part unit: write the missing exact-body guard first, collapse the duplicate validators,
+add the route with all four registrations, then fix the `enabled` reporting defect. That is a
+larger cycle than it looked, and the sequencing above is the deliverable of this A phase.
+
+### wp5 cycle scope, after the audit resized it
+
+The audit turned one route change into four parts. This cycle takes the two that stand alone
+and are verifiable on their own; the route and the reporting fix become wp5c, because adding a
+management route touches four registration surfaces and is a different kind of risk from
+deduplicating a validator.
+
+**In this cycle**
+
+1. Write the missing compatibility guard: exact-body assertions for all three legacy pool
+   responses, green BEFORE anything is shared. This is the test the plan wrongly assumed existed.
+2. Collapse the duplicate validators onto one module. Codex and Anthropic already share
+   `parseAccountPoolStrategy` from `pool-kernel.ts`; the generic kind keeps a private copy in
+   `pool-settings-capability.ts`. That is the smallest true instance of the problem this phase
+   exists to fix, and closing it is what makes a bad value behave identically on every kind.
+
+**Deferred to wp5c**
+
+3. `GET|PUT|PATCH /api/pool/settings` with its four registrations.
+4. The `enabled: null` reporting defect, where the generic DTO ignores the top-level
+   `oauthAccountFailover.enabled` that actually participates in activation.
+
+Splitting here is not scope avoidance: part 1 is the precondition for parts 3 and 4 being
+checkable at all, and shipping it separately means the guard exists in `dev` before the risky
+change is written rather than alongside it.
+
+### Residuals from the re-audit, folded
+
+**The three guard targets, named exactly.** Not all four responses are unguarded. Codex
+`GET /api/codex-auth/active` already pins its pool fields with a full `toEqual`
+(`tests/codex-integration/codex-auth-api.test.ts`:1575). The live holes are precisely:
+`PUT /api/codex-auth/auto-switch` (status-only, :3645), `PUT /api/codex-auth/pool-strategy` and
+the Anthropic `PUT /api/oauth/accounts/pool` (both `toMatchObject`), and the Anthropic
+`GET /api/oauth/accounts/pool` (`toMatchObject`). Those four assertions are the deliverable;
+the Codex GET needs nothing.
+
+**The section above is superseded where it disagrees.** "## The unit" and its Acceptance list
+still describe the pre-audit shape — one new route, the CLI transport collapse, and
+"pre-existing tests must not be edited". The cycle scope below overrides all three: the route
+and the CLI collapse move to wp5c, and writing the guard IS editing the test files, which is the
+point rather than a violation. The original text stays as the record of what was planned before
+the audit rather than being rewritten to look prescient.
+
+**Part 1 does not make part 4 checkable by itself.** The generic GET golden already pins
+`enabled: null` (`tests/server/account-pool-management-api.test.ts`:483), so wp5c's reporting
+fix has to change that assertion deliberately. The guard is an alias-safety net for the route
+change in part 3 and only a tripwire for part 4 — it tells wp5c that it is changing a published
+answer, which is exactly what a golden should do, but it does not prove the new answer correct.
+
+## wp5c plan — the unified route and the enabled reporting defect
+
+Part 3 and part 4 of the unit the wp5 audit resized. Parts 1 and 2 shipped: the exact-body
+goldens for the three legacy responses, and one validator for strategy and sticky.
+
+### The route
+
+NEW `GET | PUT | PATCH /api/pool/settings?provider=<name>` in
+`src/server/management/oauth-account-routes.ts`, serving all three kinds through
+`poolSettingsCapability`. The three legacy paths keep working unchanged — the goldens from
+part 1 are what proves that, and they were written before any of this precisely so they could.
+
+**Four registration surfaces, each of which fails CI on its own.** This is the part that went
+red on #4289 and is worth stating as a list rather than a sentence:
+
+1. `src/server/management/route-registry.ts` — `tests/server/management-route-registry.test.ts`
+   compares source and registry as exact pairs.
+2. `src/cli/capabilities.ts` — `tests/cli/cli-capabilities.test.ts` fails on any registry route
+   that is neither declared, `exempt`, nor in the dated ratchet. The ratchet is NOT an option:
+   a sibling test asserts it only ever shrinks.
+3. `skills/ocx/references/01_management_surface.md` — generated; `bun run skill:surface` must
+   run and the result must be committed, or `tests/ci-workflows/skill-ocx.test.ts` fails.
+4. `docs-site` — `reference/management-api.md`:332 still claims the pool route 400s for
+   non-Anthropic providers, which stopped being true when the generic contract shipped. Stale
+   before this unit and fixed by it.
+
+Declaring the route in `capabilities.ts` rather than exempting it is the honest option only if
+the CLI actually uses it, so `src/cli/account-extended.ts` switches its transport table to the
+single path. That table exists today only because the two contracts disagreed.
+
+`PATCH` is included because both legacy writes accept it; a unified route that dropped it would
+be a narrower contract wearing a wider name.
+
+### The enabled reporting defect
+
+`isProactivePreferenceEnabled` reads the per-provider `enabled` when it is a boolean and falls
+back to the global `config.oauthAccountFailover.enabled`. The generic DTO reports only the
+per-provider value, so `enabled: null` means "nothing stored here" while the effective answer
+may be `true` from the global — a dashboard cannot tell a disabled pool from an inherited one.
+
+The fix ADDS `enabledEffective: boolean` rather than changing `enabled`. `enabled` is published
+as "the stored provider override, `null` means unspecified, not inherited effective state" in
+`docs-site/reference/cli/providers-accounts.md` and the CLI surfaces it as `poolEnabled`;
+redefining it would break a documented field to fix a missing one. The generic GET golden at
+`tests/server/account-pool-management-api.test.ts`:483 pins `enabled: null` and must be
+extended deliberately — that is the tripwire firing exactly as intended, not a test to silence.
+
+### Acceptance
+
+- `GET /api/pool/settings?provider=` answers for Codex, Anthropic and a generic provider, each
+  declaring which fields its kind supports.
+- The three legacy paths still return byte-identical bodies, proven by the part-1 goldens, which
+  are not edited.
+- `enabledEffective` is true for a provider with no stored override under a global `true`, and
+  false under a global `false` or absence.
+- Registry, capabilities, regenerated surface map and docs all move in the same commit.
+- Red control: each new assertion must fail with its production branch removed.
+
+### wp5c plan audit — PASS-WITH-FINDINGS, folded
+
+**Major 1 — the acceptance contradicted itself, and the resolution is the safer one.**
+Adding `enabledEffective` to `genericPoolSettingsDto` would change the LEGACY
+`GET /api/oauth/accounts/pool` too, so the part-1 golden at :483 would have to move — while the
+same section promised the goldens stay unedited. Resolution: the new field appears ONLY on
+`/api/pool/settings`. The legacy DTO is not touched, every part-1 golden stays byte-identical
+and unedited, and the reporting defect is fixed on the surface that is meant to be canonical.
+Choosing the other branch would have spent the tripwire on the first cycle that met it.
+
+**Major 2 — the CLI switch orphans a route's coverage.** Once `account strategy` and
+`account sticky` stop driving `PUT /api/codex-auth/pool-strategy`, that route has no capability
+declaring it and cannot enter the ratchet, which only shrinks. It gets a registry
+`exempt: { reason: "compatibility-alias" }` naming the unified route as its replacement — an
+honest description of what it becomes, rather than a capability entry claiming a CLI path that
+no longer exists. `GET`/`PUT /api/oauth/accounts/pool` keep their declarations because
+`cmdAutoSwitch` still uses them; the transport table this cycle collapses is strategy and sticky
+only.
+
+**Major 3 — `PATCH /api/pool/settings` needs its own answer.** The CLI only PUTs, so the PATCH
+verb is declared through the same capability entry as the PUT rather than left to a ratchet that
+cannot take it.
+
+**Major 4 — do not reuse `isProactivePreferenceEnabled` for `enabledEffective`.** It is
+unexported, and it additionally requires `hasFailoverAccountQuorum` — two or more eligible
+accounts. Folding a roster condition into a settings field would make the DTO answer a different
+question than the one it asks: the defect is stored-versus-global CONFIG, so the field resolves
+exactly that and nothing else. Confirmed by the audit that no GUI or CLI consumer already
+derives effective enablement: the CLI's `poolEnabled` is stored-only and the Anthropic GUI reads
+`enabled === true`.
+
+**Minor 6 — two more locales.** `ko` and `ru` carry the same stale "400 for non-Anthropic" pool
+row as the English `reference/management-api.md`. They move with it.
+
+**Confirmed by the audit, no action:** `poolSettingsCapability("openai") === "codex"` is the
+right discriminator; the unified GET must NOT copy the mixed pin+failover+pool DTO that
+`GET /api/codex-auth/active` returns; and CORS, the Vite `/api` proxy, OpenAPI and the
+management-auth enumeration are not gates for a new path.
+
+## wp5b plan — one GUI pool client
+
+The last phase. wp5c gave the server one contract; this points the dashboard at it.
+
+### What "two surfaces" means in the GUI
+
+Not two screens. Two independent client implementations of the same idea:
+
+| Surface | File | Talks to | Reads |
+|---|---|---|---|
+| Codex threshold | `gui/src/codex-auto-switch.ts` | `PUT /api/codex-auth/auto-switch` | bare `{ threshold }` |
+| Codex strategy/sticky | `gui/src/account-pool-strategy.ts` | `PUT /api/codex-auth/pool-strategy` | `accountPoolStrategy`, `accountPoolStickyLimit` |
+| Anthropic pool | `gui/src/components/provider-workspace/AnthropicAccountPoolSettings.tsx` | `GET`/`PUT /api/oauth/accounts/pool` | `strategy`, `stickyLimit`, `quotaWindow` |
+
+Three fetchers, three response shapes, two prefix conventions for the same two fields. The
+components on top are legitimately different — a Codex pool card is not an Anthropic pool card —
+so this phase merges the CLIENT, not the presentation. Merging the rendering would be a visual
+redesign nobody asked for; merging the transport is the duplication the objective names.
+
+### Change surface
+
+NEW `gui/src/pool-settings.ts` — one client for `/api/pool/settings`:
+`getPoolSettings(apiBase, provider)` and `putPoolSettings(apiBase, provider, fields)`, both
+returning the unified DTO with its `supported` list. The existing normalizers in
+`account-pool-strategy.ts` stay where they are and are reused; this adds a transport, not a
+second copy of the value rules.
+
+MODIFY `codex-auto-switch.ts` `putAutoSwitchThreshold` and `account-pool-strategy.ts`
+`putCodexPoolStrategy` to delegate, keeping their exported signatures so no component changes
+shape. The `accountPoolStrategy`/`accountPoolStickyLimit` response handling disappears with the
+prefixed keys — the unified DTO is neutral for every kind.
+
+MODIFY `AnthropicAccountPoolSettings.tsx` to read and write through the same client.
+
+### The screenshot
+
+`enforce-target` requires a screenshot embed in the description of any PR whose title or
+description mentions `gui`, waivable only by a maintainer label. So: `bun run build:gui`, start
+the proxy, open the dashboard, capture the pool settings, and commit the PNG under the plan unit
+so the description can embed it from the branch. A committed asset is the only route that does
+not depend on a browser drag-and-drop.
+
+### Acceptance
+
+- No GUI file references `/api/codex-auth/auto-switch`, `/api/codex-auth/pool-strategy` or
+  `/api/oauth/accounts/pool` any more; one grep proves the consolidation rather than an
+  argument about it.
+- `bun run lint:gui` passes and the GUI suites covering these modules pass.
+- The three server routes still work — they have their own goldens and are not touched.
+- The PR description embeds a real screenshot of the rendered pool settings.
+
+### wp5b plan audit — FAIL, folded
+
+**Blocker 1 — the request adapter, again.** This is the third time this exact shape has been
+caught in this unit, and it is the most dangerous instance. `putAutoSwitchThreshold` sends
+`{ threshold }`; the unified route reads `{ provider, autoSwitchThreshold }`. A URL swap alone
+either 400s, or — with `provider` added and `threshold` left alone — returns **200 while writing
+nothing**, because the route ignores an unknown field. And the function only inspects
+`response.ok`, so the dashboard would report success on every save and change no setting.
+
+Silent success is worse than a visible failure, so the client owns an explicit request mapping:
+`threshold` becomes `autoSwitchThreshold`, `provider` is always sent, and Codex is addressed as
+`provider: "openai"`. The strategy body keys already match and need no mapping; only the
+response did, which is what the original plan named and why the request side slipped past it.
+
+**Major 2 — the read path is a different route, and the plan mislabeled it.** The table called
+the write bodies "Reads". The GUI actually reads the Codex threshold and strategy from
+`GET /api/codex-auth/active` via `extractAutoSwitchThresholdPayload`. That read STAYS: `/active`
+is a mixed pin + failover + pool payload the dashboard needs in one request, and wp5c
+deliberately did not have the unified GET copy it. Stated rather than left implicit, because a
+future reader would otherwise see a half-migrated client and assume it was unfinished.
+
+This narrows the acceptance grep: no GUI file may reference the three legacy pool WRITE
+contracts. `/api/codex-auth/active` legitimately remains, and the grep says so.
+
+**Major 3 — four GUI test files pin the old URLs and payloads:**
+`gui/tests/account-pool-strategy.test.tsx`, `anthropic-pool-quota-window.test.tsx`,
+`codex-account-auto-switch.test.tsx` and `codex-auto-switch-controller.test.tsx`. They move with
+the client. `CodexPoolStrategySetting` reads `result.strategy`/`stickyLimit` from the wrapper,
+so it survives untouched as long as the wrapper maps the DTO; `putAutoSwitchThreshold` callers
+never read the body.
+
+**Minor 4 recorded, not fixed:** `ProviderAuthPanel` still gates the pool card on
+`item.name === "anthropic"`, so a generic OAuth provider has a contract and no UI, and the new
+`supported`/`enabledEffective` fields are not yet rendered. That is a feature the objective does
+not ask for; naming it is better than silently leaving a reader to wonder whether it was missed.
+
+**Screenshot — the gate is stricter than the plan assumed.** It fires on `gui/` PATH CHANGES,
+not on a title cue, so it applies here regardless of wording. A committed PNG alone does not
+satisfy it: the description must contain a rendered embed. A relative path passes the regex but
+renders nothing on GitHub, so the description uses an absolute `raw.githubusercontent.com` URL
+pointing at the committed file on this branch. The waiver is a maintainer COMMENT, not a label.
+
+### wp5b SPEC — supersedes "Change surface", "The screenshot" and "Acceptance" above
+
+Those three sections predate the audit and disagree with it. This is the spec.
+
+**Change surface.**
+
+NEW `gui/src/pool-settings.ts`, one client for `/api/pool/settings`:
+
+- `getPoolSettings(apiBase, provider)` — `GET ?provider=<name>`, returns the unified DTO.
+- `putPoolSettings(apiBase, provider, fields)` — `PUT`, and it owns an explicit REQUEST
+  mapping rather than forwarding whatever it is handed:
+  - `provider` is ALWAYS sent, and Codex is addressed as `provider: "openai"`.
+  - the Codex threshold field `threshold` becomes `autoSwitchThreshold`.
+  - `strategy` and `stickyLimit` already match and pass through unmapped.
+
+  Without that mapping a URL swap returns 200 and writes nothing, because the route ignores an
+  unknown field — and the caller only inspects `response.ok`, so the dashboard would report
+  success on every save. That is the specific failure this mapping exists to prevent.
+
+MODIFY `gui/src/codex-auto-switch.ts` `putAutoSwitchThreshold` and
+`gui/src/account-pool-strategy.ts` `putCodexPoolStrategy`: same exported signatures, bodies
+delegating through the client, and the `accountPoolStrategy`/`accountPoolStickyLimit` response
+parsing replaced by the DTO's neutral keys.
+
+MODIFY `gui/src/components/provider-workspace/AnthropicAccountPoolSettings.tsx`: read and write
+through the client.
+
+MOVE WITH IT — four test files pin the old URLs and payloads and are part of this change, not
+collateral: `gui/tests/account-pool-strategy.test.tsx`,
+`gui/tests/anthropic-pool-quota-window.test.tsx`, `gui/tests/codex-account-auto-switch.test.tsx`,
+`gui/tests/codex-auto-switch-controller.test.tsx`.
+
+UNCHANGED ON PURPOSE — `GET /api/codex-auth/active`. The dashboard reads the Codex threshold and
+strategy from that mixed pin + failover + pool payload in one request, and wp5c deliberately did
+not have the unified GET copy it. This phase migrates the three pool WRITE contracts, not that
+read.
+
+**Acceptance.**
+
+- `rg` over `gui/` returns no hit for `/api/codex-auth/auto-switch`,
+  `/api/codex-auth/pool-strategy` or `/api/oauth/accounts/pool` — the three legacy WRITE
+  contracts. `/api/codex-auth/active` is expected to remain and is not part of this grep.
+- The four test files above assert the unified path and the mapped request body, including
+  `autoSwitchThreshold` rather than `threshold`.
+- `bun run lint:gui` passes and the GUI suites pass.
+- Red control: with the request mapping removed, the auto-switch save test must fail — the point
+  is that it would otherwise pass silently.
+
+**The screenshot.**
+
+The gate fires on `gui/` PATH CHANGES, not on a title cue, so it applies. A committed PNG alone
+does NOT satisfy it. The description must carry a rendered embed — `![alt](url)`,
+`<img src="...">`, or a reference form — outside comments and fences. A relative path passes the
+regex but renders nothing, so the PNG is committed under the plan unit and the description
+embeds its absolute `raw.githubusercontent.com` URL on this branch. The only waiver is a
+maintainer COMMENT, which is not something this cycle can issue for itself.
+
diff --git a/devlog/_plan/260911_account_pool_unification/assets/wp5b-pool-settings.png b/devlog/_plan/260911_account_pool_unification/assets/wp5b-pool-settings.png
new file mode 100644
index 0000000000..f6c6be4743
Binary files /dev/null and b/devlog/_plan/260911_account_pool_unification/assets/wp5b-pool-settings.png differ
diff --git a/devlog/_plan/260911_cursor_checkpoint_capture/000_plan.md b/devlog/_plan/260911_cursor_checkpoint_capture/000_plan.md
new file mode 100644
index 0000000000..5804297c4d
--- /dev/null
+++ b/devlog/_plan/260911_cursor_checkpoint_capture/000_plan.md
@@ -0,0 +1,144 @@
+# Cursor checkpoint capture — why #4245 full-replays
+
+Unit opened 2026-09-11. Tracks issue #4245 (Cursor adapter always full-replays,
+`cached_tokens=0`, while direct `cursor-agent` cache-hits on the same account).
+
+## Why this unit exists
+
+A first triage pass concluded the cause was `isCursorExternalWireModel` excluding
+native router models from the tool-suspended checkpoint commit, and proposed
+relaxing that gate. A live probe disproved it. The gate is not reached: every
+model class dies one condition later, on `capturedBytes === 0`.
+
+That matters beyond this issue. The proposed patch would have shipped a behaviour
+change to a replay path, passed review on plausibility, and fixed nothing — the
+refusal it removed is not the refusal that fires.
+
+## Evidence already captured
+
+macOS, opencodex 2.50.0, real Cursor OAuth account, `ocx debug provider on`,
+requests to the local proxy. Nothing patched.
+
+Same forced-tool-call request, three model classes:
+
+```
+cursor/auto-intelligence  (native router)
+[ocx:cursor:checkpoint-commit-refused] {"replayUnsafe":false,"emittedClientTool":true,"capturedAfterClientTool":false,"externalModel":false,"storeCheckpoints":true,"capturedBytes":0}
+
+cursor/claude-4.5-sonnet  (external)
+[ocx:cursor:checkpoint-commit-refused] {"replayUnsafe":false,"emittedClientTool":true,"capturedAfterClientTool":false,"externalModel":true,"storeCheckpoints":true,"capturedBytes":0}
+
+cursor/composer-2.5-fast  (native composer)
+[ocx:cursor:checkpoint-commit-refused] {"replayUnsafe":false,"emittedClientTool":true,"capturedAfterClientTool":false,"externalModel":false,"storeCheckpoints":true,"capturedBytes":0}
+```
+
+A turn with no client tool commits normally:
+
+```
+[ocx:cursor:checkpoint-continuation] {"mode":"full-replay","checkpointRefHash":"c5609327a9ac1ec4","checkpointBytes":492,"wireModel":"default"}
+[ocx:cursor:checkpoint-continuation] {"mode":"full-replay","checkpointRefHash":"bdd0d48f85f7ebee","checkpointBytes":553,"wireModel":"default"}
+```
+
+Two sequential chat-completions turns, same content:
+
+```
+[ocx:cursor:run-request] {"conversationId":"cursor_f3e3e375188f41b9af0669d7090eb962","continuationMode":"full-replay","checkpointPresent":false,"checkpointInvalidationReason":"missing_ref"}
+[ocx:cursor:run-request] {"conversationId":"cursor_24bbb91416874b53b9a87f97530cfa14","continuationMode":"full-replay","checkpointPresent":false,"checkpointInvalidationReason":"missing_ref"}
+```
+
+And the suspend/cancel sequence on a tool turn, with no
+`conversationCheckpointUpdate` among the 33 frames:
+
+```
+[ocx:cursor:client-tool-suspend] {"reason":"Responses bridge owns client tools; ending turn without fake mcpResult","framesReceived":33,"elapsedMs":2886}
+[ocx:cursor:stream-cancel-expected] {"code":"ERR_HTTP2_STREAM_ERROR","message":"Cursor stream suspended: Stream closed with error code NGHTTP2_CANCEL"}
+```
+
+## Cause map
+
+**C1 — no capture on a client-tool turn.** `capturedCheckpointBytes` is set only by
+the `conversationCheckpointUpdate` frame in `CursorLiveTransport.handleServerMessage`
+(`src/adapters/cursor/live-transport.ts`). On a client-tool turn the finalize-grace
+timer fires, logs `client-tool-suspend`, and calls `cancelCursorRun()`. The frame has
+not arrived by then. Affects every model class equally.
+
+**C2 — unstable conversation identity.** Each chat-completions turn derives a new
+`conversationId`, so a checkpoint committed on turn N is unreachable on turn N+1
+(`checkpointInvalidationReason: missing_ref`). Observed only on the stateless path so
+far; the `/v1/responses` path is untested and is what Codex users actually take.
+
+**Not a cause:** the native/external model split. Recorded so the next reader does
+not retry it.
+
+## Status of each cause
+
+| Cause | Verdict | Evidence |
+|---|---|---|
+| C1 tool-turn capture | **LATE — real, fixable** | `010` Result, `011`, `012`: 50 ms captures nothing, 1500 ms captures 3036 bytes after `toolCallStarted`, wire held constant |
+| C2 conversation identity | **Closed, no patch** | `020` Result: two threaded `/v1/responses` turns share `conversationHash cursor_cdbed7dcc` and turn 2 resumes with `mode: checkpoint`. Scoped to threaded conversations; an unthreaded one-shot legitimately starts fresh |
+| native/external gate | **Not a cause; gated behind wp5** | every model class refused identically at `capturedBytes: 0` before C1 was fixed |
+
+So the whole of `#4245` reduces to C1, and `030` branch A is the only patch this unit
+will produce. Branch B is dropped.
+
+## Constraints
+
+- No change to `src/router.ts`, `src/server/lifecycle.ts`, `src/server/responses/core.ts`.
+- No change to the checkpoint design or its safety contract: a checkpoint that claims
+  coverage it does not have would send wrong context upstream. Slower and correct
+  beats faster and wrong.
+- Every behavioural claim needs a diagnostic captured in the same session it is
+  claimed in.
+
+## Work-phase map (dependency ordered)
+
+| Phase | Doc | Decides |
+|---|---|---|
+| wp1 | this file + 010/020/030 | roadmap locked, docs only |
+| wp2 | `010_phase1_grace_experiment.md` | C1: does the frame arrive late, or never |
+| wp3 | `020_phase2_responses_identity.md` | C2: is it chat-completions-specific |
+| wp4 | `030_phase3_landing.md` | land the proven fix, or record the verdict |
+| wp2b | `010` closing section | only if wp2 is INCONCLUSIVE: instrumented rerun that can reach NEVER |
+| wp5 | `030` closing section | only if branch A lands: does a captured snapshot actually cover the tool call |
+
+wp2 and wp3 are independent of each other and both depend only on wp1. wp4 depends on
+wp2; if wp3 finishes first its outcome folds into wp4 as an additional branch.
+
+wp2b and wp5 were appended during wp1's audit (LOOP-UNIT-CHAIN-01). Both are
+conditional: neither runs unless its predecessor returns the outcome that needs it.
+
+Outcomes: **wp2b closed as delivered-elsewhere** — the experiment returned a self-proving
+positive so a NEVER verdict was never needed, and the `graceMs` field it existed to add
+shipped in #4281 (`live-transport.ts:1064-1069`). **wp5 is live**, because branch A landed
+and the native gate now depends on a coverage question rather than a capture one.
+
+## What the wp1 audit changed
+
+The first draft of this roadmap was audited and failed on two high findings, both
+folded before the roadmap was locked:
+
+1. `030` branch A paired the capture fix with dropping the native/external gate,
+   arguing that arrival order became a sound proof. It does not:
+   `conversationCheckpointUpdate` is classified liveness-only, so a snapshot can arrive
+   after the tool call with contents that predate it. The gate edit was removed and
+   became wp5, gated on decoding the snapshot.
+2. `010` used `client-tool-suspend.elapsedMs` to prove which grace branch ran. That
+   field is turn-relative, and this unit's own evidence already shows `elapsedMs: 2886`
+   on the 50 ms path. The experiment was downgraded to positive-only; a NEVER verdict
+   now requires wp2b.
+
+Recording this because both mistakes have the same shape as the one that opened the
+unit: a plausible mechanism asserted without checking what the field actually measures.
+
+## Decision tree
+
+- **wp2 = LATE** (frame arrives when the grace is extended): C1 is a grace-computation
+  bug. Land branch A in `030`.
+- **wp2 = NEVER**: upstream does not serialize state for a suspended turn. C1 is not
+  fixable inside this adapter; record the verdict and the evidence.
+- **wp3 = STABLE on /v1/responses**: C2 is an artifact of the stateless path and is not
+  a user-facing defect for Codex. Record and close that half.
+- **wp3 = UNSTABLE on /v1/responses**: C2 is real and general. Land branch B in `030`.
+
+Either NEVER or STABLE is a legitimate terminal outcome for its half. A recorded
+negative with captured evidence is the deliverable when no safe change exists.
diff --git a/devlog/_plan/260911_cursor_checkpoint_capture/001_frame_evidence.md b/devlog/_plan/260911_cursor_checkpoint_capture/001_frame_evidence.md
new file mode 100644
index 0000000000..2a4f4c26e5
--- /dev/null
+++ b/devlog/_plan/260911_cursor_checkpoint_capture/001_frame_evidence.md
@@ -0,0 +1,60 @@
+# Frame-level record of one suspended tool turn
+
+Research material for `000_plan.md`. No diffs here.
+
+`000_plan.md` asserts that no `conversationCheckpointUpdate` appears among the frames
+of a client-tool turn. That claim carries the whole unit — branch A exists only if the
+frame is absent at 50 ms — so the sequence it rests on is recorded here rather than
+left in a chat transcript.
+
+## Capture conditions
+
+macbookpro-2, macOS, opencodex 2.50.0, proxy PID 70500 on 127.0.0.1:10100, real Cursor
+OAuth account. `ocx debug provider on` (runtime override, no restart). Request:
+`POST /v1/chat/completions`, `model: cursor/auto-intelligence`, one `get_weather` tool,
+`tool_choice: required`, no `parallel_tool_calls` — so the 50 ms base grace applied.
+Response was HTTP 200 with `finish_reason: tool_calls` and
+`prompt_tokens_details.cached_tokens: 0`.
+
+## Sequence
+
+```
+[ocx:cursor:connected]   {"transport":"http2","connectMs":403}
+[ocx:cursor:first-frame] {"latencyMs":630}
+[ocx:cursor:frame] {"case":"interactionUpdate","update":"heartbeat"}
+[ocx:cursor:frame] {"case":"kvServerMessage","kv":"getBlobArgs"}       x2
+[ocx:cursor:frame] {"case":"kvServerMessage","kv":"setBlobArgs"}       x4
+[ocx:cursor:frame] {"case":"interactionUpdate","update":"thinkingDelta"}
+[ocx:cursor:frame] {"case":"interactionUpdate","update":"tokenDelta"}
+[ocx:cursor:frame] {"case":"interactionUpdate","update":"thinkingDelta"}
+[ocx:cursor:frame] {"case":"interactionUpdate","update":"tokenDelta"}
+[ocx:cursor:frame] {"case":"interactionUpdate","update":"thinkingCompleted"}
+[ocx:cursor:frame] {"case":"interactionUpdate","update":"textDelta"}   interleaved with
+[ocx:cursor:frame] {"case":"interactionUpdate","update":"tokenDelta"}  x7 pairs
+[ocx:cursor:frame] {"case":"interactionUpdate","update":"partialToolCall","toolCase":"mcpToolCall","callId":"call-d4f5fcfc-...-0"}
+[ocx:cursor:frame] {"case":"interactionUpdate","update":"tokenDelta"}
+[ocx:cursor:frame] {"case":"interactionUpdate","update":"toolCallStarted","toolCase":"mcpToolCall","callId":"call-d4f5fcfc-...-0"}
+[ocx:cursor:frame] {"case":"execServerMessage","exec":"mcpArgs"}
+[ocx:cursor:frame] {"case":"kvServerMessage","kv":"setBlobArgs"}       x4
+[ocx:cursor:client-tool-suspend]      {"reason":"Responses bridge owns client tools; ending turn without fake mcpResult","framesReceived":33,"elapsedMs":2886}
+[ocx:cursor:stream-end]               {"committed":true,"framesReceived":33,"expectedClose":true,"elapsedMs":2886}
+[ocx:cursor:checkpoint-commit-refused] {"replayUnsafe":false,"emittedClientTool":true,"capturedAfterClientTool":false,"externalModel":false,"storeCheckpoints":true,"capturedBytes":0}
+[ocx:cursor:stream-cancel-expected]   {"message":"Cursor upstream error: Cursor request was aborted","framesReceived":33,"elapsedMs":2887}
+[ocx:cursor:stream-cancel-expected]   {"code":"ERR_HTTP2_STREAM_ERROR","message":"Cursor stream suspended: Stream closed with error code NGHTTP2_CANCEL","framesReceived":33,"elapsedMs":2893}
+```
+
+## What the sequence establishes, and what it does not
+
+Establishes: across all 33 decoded frames there is no `conversationCheckpointUpdate`,
+and the refusal that follows is over-determined — `capturedBytes: 0` fires regardless
+of the model gate one line above it.
+
+Does **not** establish that upstream never sends one. The stream was cancelled 7 ms
+after the suspend (2886 to 2893), so the observation window closes immediately. This is
+precisely why `010` can only return a positive; an absence here is an absence of
+opportunity, not evidence of absence.
+
+The last four `setBlobArgs` frames arriving after `toolCallStarted` are worth noting:
+upstream was still writing blob state when the cancel landed. That is consistent with
+the late-arrival hypothesis, and consistent with the frame simply not existing for a
+suspended turn. It does not discriminate between them.
diff --git a/devlog/_plan/260911_cursor_checkpoint_capture/010_phase1_grace_experiment.md b/devlog/_plan/260911_cursor_checkpoint_capture/010_phase1_grace_experiment.md
new file mode 100644
index 0000000000..e765707cee
--- /dev/null
+++ b/devlog/_plan/260911_cursor_checkpoint_capture/010_phase1_grace_experiment.md
@@ -0,0 +1,132 @@
+# wp2 — does `conversationCheckpointUpdate` arrive late, or never
+
+Decides C1. Written at wp1; re-verify against the tree before executing.
+
+## The lever, and why no build is needed
+
+`src/adapters/cursor/live-transport.ts:114`:
+
+```ts
+const CLIENT_TOOL_FINALIZE_GRACE_MS = 50;
+```
+
+Fifty milliseconds. The probe that produced `capturedBytes: 0` sent one tool and no
+`parallel_tool_calls`, so it took the base path and the stream was cancelled 50 ms
+after the turn drained.
+
+`clientToolFinalizeGraceMsForRequest` (same file, line 416) already raises that window
+from the request alone:
+
+```ts
+if (request.parallelToolCalls === true && (request.tools?.length ?? 0) > 1) {
+  const advertised = request.tools?.length ?? 0;
+  return Math.max(baseGraceMs, Math.min(1_800, Math.max(750, advertised * 125)));
+}
+```
+
+A request with `parallel_tool_calls: true` and 12 advertised tools therefore gets
+`min(1800, max(750, 1500)) = 1500 ms` instead of 50 ms — on the shipped binary, with
+no patch, no second proxy and no credential copy. That is the experiment.
+
+This deliberately replaces the instrumented build the roadmap first imagined. It is
+strictly better: it exercises production code rather than a local mutant, and it
+touches nothing on the operator machine.
+
+## Procedure
+
+1. `ocx debug provider on` on macbookpro-2; record the log line count as a baseline.
+2. Request A (control): 1 tool, no `parallel_tool_calls`, `tool_choice: required`,
+   model `cursor/auto-intelligence`. Expect the 50 ms path.
+3. Request B (treatment): 12 tools, `parallel_tool_calls: true`, `tool_choice: required`,
+   same model. Expect the 1500 ms path.
+4. Capture per request: `client-tool-suspend.elapsedMs`, whether any
+   `conversationCheckpointUpdate` frame appears, and
+   `checkpoint-commit-refused.capturedBytes`.
+5. `ocx debug provider off`.
+
+## Decision rule
+
+**This experiment can only return a positive.** Folded from the wp1 audit (high):
+`client-tool-suspend.elapsedMs` is `Date.now() - this.turnStartedAt`
+(`live-transport.ts:1015`, `turnStartedAt` set in `open()` at :1033), so it measures
+the whole turn, not the grace delay. `000_plan.md` already records `elapsedMs: 2886`
+on the 50 ms path. Model generation time swamps a 50-vs-1500 ms difference, so
+`elapsedMs` cannot witness which branch of
+`clientToolFinalizeGraceMsForRequest` ran. The original rule below was wrong and is
+replaced.
+
+- **LATE** — B shows `capturedBytes > 0`, or a `conversationCheckpointUpdate` frame
+  that A lacked. Self-proving: bytes can only appear if the window outlasted their
+  arrival. The 50 ms base grace is the defect. Go to `030` branch A.
+- **INCONCLUSIVE** — anything else. A `capturedBytes: 0` result here does **not**
+  establish NEVER, because nothing in the emitted diagnostics witnesses the grace that
+  was actually used.
+
+**Reaching a sound NEVER requires instrumentation**, and only if the cheap arm comes
+back INCONCLUSIVE: add `graceMs: this.activeClientToolFinalizeGraceMs` to the
+`client-tool-suspend` diagnostic payload, build on macbookpro-2 in a throwaway
+checkout, and rerun arm B. NEVER is then `capturedBytes: 0` with a logged
+`graceMs` of 1500. That instrumented arm is wp2b, appended only if needed.
+
+### wp2b closed — its deliverable shipped inside wp4
+
+wp2b was never needed for its original purpose: the experiment returned a positive, and a
+positive is self-proving. But the mechanism it specified — putting the real
+`graceMs` into the `client-tool-suspend` payload so a negative could ever be trusted —
+landed anyway, as part of #4281:
+
+```ts
+debugProviderDiagnostic("cursor", "client-tool-suspend", {
+  ...
+  graceMs: graceMsOverride ?? this.activeClientToolFinalizeGraceMs,
+  checkpointGraceExtended: this.checkpointGraceExtended,
+});
+```
+
+So the instrumented throwaway build this phase was reserved for is now unnecessary in
+both directions: nobody needs to reach NEVER here, and if a future reader does, the field
+is in the shipped binary. Closed as **delivered elsewhere**, not as skipped.
+
+That is worth separating from "not needed". A phase that is genuinely obsolete and a
+phase whose deliverable moved are different states, and recording the wrong one would
+leave the next reader thinking the diagnostic gap is still open.
+
+## Result — LATE
+
+Run 2026-09-11 on macbookpro-2, opencodex 2.50.0, same account and toggle as `001`.
+Both arms used `cursor/auto-intelligence` and `tool_choice: required`.
+
+Arm A, 1 tool, no `parallel_tool_calls` (50 ms path):
+
+```
+[ocx:cursor:client-tool-suspend]       {"framesReceived":33,"elapsedMs":3299}
+[ocx:cursor:checkpoint-commit-refused] {"replayUnsafe":false,"emittedClientTool":true,"capturedAfterClientTool":false,"externalModel":false,"storeCheckpoints":true,"capturedBytes":0}
+conversationCheckpointUpdate frames in window: 0
+```
+
+Arm B, 12 tools, `parallel_tool_calls: true` (1500 ms path):
+
+```
+[ocx:cursor:frame]                     {"case":"conversationCheckpointUpdate","usedTokens":0}
+[ocx:cursor:client-tool-suspend]       {"framesReceived":34,"elapsedMs":4553}
+[ocx:cursor:checkpoint-commit-refused] {"replayUnsafe":false,"emittedClientTool":true,"capturedAfterClientTool":true,"externalModel":false,"storeCheckpoints":true,"capturedBytes":2977}
+conversationCheckpointUpdate frames in window: 1
+```
+
+**LATE.** Upstream does send `conversationCheckpointUpdate` on a suspended client-tool
+turn. At 50 ms the stream is cancelled before it lands; given a longer window the frame
+arrives and 2977 bytes are captured. The positive is self-proving, so the `elapsedMs`
+problem that made a NEVER unreachable never had to be solved. **wp2b is not needed.**
+
+### The second barrier, now visible for the first time
+
+Arm B also shows `capturedAfterClientTool: true` with `externalModel: false` — and it
+*still* refused. With bytes finally present, `toolSuspendedCommit` fails on the wire-model
+test alone. So the two barriers are now separated by evidence rather than by argument:
+
+1. capture never happened (all models) — fixed by `030` branch A1;
+2. the native wire-model gate — reachable only after A1, and still gated on wp5
+   proving the snapshot covers the tool call.
+
+The original triage proposed removing barrier 2 while barrier 1 made it unreachable.
+That is exactly what the probe was built to distinguish, and it did.
diff --git a/devlog/_plan/260911_cursor_checkpoint_capture/011_wp2_deconfound.md b/devlog/_plan/260911_cursor_checkpoint_capture/011_wp2_deconfound.md
new file mode 100644
index 0000000000..de7e8bcd09
--- /dev/null
+++ b/devlog/_plan/260911_cursor_checkpoint_capture/011_wp2_deconfound.md
@@ -0,0 +1,44 @@
+# wp2 — de-confounding the LATE result
+
+The first LATE run varied two things at once and a reviewer caught it. This records the
+correction, because the correction is the part worth keeping.
+
+## The confound
+
+Arm B raised the finalize grace by sending `parallel_tool_calls: true` with 12 tools.
+But 12 tools is not only a local signal: `buildCursorToolDefinitions` puts them in
+`AgentRunRequest.mcpTools` (`protobuf-request.ts:1607`, `:1711-1712`) and the catalog is
+named in the system note (`:197-201`). A larger catalog could plausibly change Cursor's
+own context accounting and make it emit a `conversationCheckpointUpdate` for reasons
+that have nothing to do with how long we waited.
+
+So the original pair could not tell "we waited longer" from "we asked for more tools".
+
+## The correction
+
+Hold the wire constant, vary only the local knob. `parallelToolCalls` is read at
+`live-transport.ts:423` and `:689` and is never protobuf-encoded
+(`protobuf-request.ts:1736`), so `parallel_tool_calls` changes the grace and nothing
+upstream. Three arms, 12 tools in every one:
+
+| Arm | `parallel_tool_calls` | Grace | `conversationCheckpointUpdate` | `capturedBytes` |
+|---|---|---|---|---|
+| C | false | 50 ms | 0 | 0 |
+| B | true | 1500 ms | 1 | 2742 |
+| C repeat | false | 50 ms | 0 | 0 |
+
+```
+C  [ocx:cursor:checkpoint-commit-refused] {"emittedClientTool":true,"capturedAfterClientTool":false,"externalModel":false,"storeCheckpoints":true,"capturedBytes":0}
+B  [ocx:cursor:checkpoint-commit-refused] {"emittedClientTool":true,"capturedAfterClientTool":true,"externalModel":false,"storeCheckpoints":true,"capturedBytes":2742}
+C' [ocx:cursor:checkpoint-commit-refused] {"emittedClientTool":true,"capturedAfterClientTool":false,"externalModel":false,"storeCheckpoints":true,"capturedBytes":0}
+```
+
+Identical request bytes, opposite outcomes, reproduced in both directions within one
+session. **LATE is isolated: the 50 ms finalize grace is the cause.**
+
+## Why this is recorded rather than folded silently
+
+Three times in this unit a plausible mechanism was asserted before the field it rested
+on was checked — the native/external gate, `elapsedMs`, and now the tool catalog. Each
+was caught by looking at what the value actually is rather than what it was assumed to
+mean. The pattern is the finding.
diff --git a/devlog/_plan/260911_cursor_checkpoint_capture/012_wp4_measurement_artifact.md b/devlog/_plan/260911_cursor_checkpoint_capture/012_wp4_measurement_artifact.md
new file mode 100644
index 0000000000..46617d7c55
--- /dev/null
+++ b/devlog/_plan/260911_cursor_checkpoint_capture/012_wp4_measurement_artifact.md
@@ -0,0 +1,69 @@
+# wp4 — a measurement artifact that nearly reversed the verdict
+
+While sizing `CHECKPOINT_CAPTURE_GRACE_MS`, a batch of runs returned 0 checkpoint
+frames for **every** arm, including the 12-tool 1500 ms condition that had just
+produced a frame twice. Taken at face value that reverses wp2.
+
+It was an instrumentation bug in the probe, not a behaviour change.
+
+## The artifact
+
+The probes windowed the log by line count: record `L = ocx debug provider logs | wc -l`
+before a request, then read `tail -n +$((L+1))` after. `ocx debug provider logs` is a
+**bounded ring buffer** — measured at exactly 500 lines on this machine. Once the buffer
+is full, `L` equals the cap and every later `tail -n +501` returns nothing. Every arm
+then reports zero, uniformly and convincingly.
+
+Reading `tail -50` after each request instead of a computed offset restores the signal
+immediately.
+
+This is the fourth time in this unit a conclusion rested on a field that did not mean
+what it appeared to mean. The others were the native/external gate, `elapsedMs`, and
+the tool catalog. It is worth saying plainly: **the failure mode of this investigation
+is not bad reasoning about the adapter, it is trusting an observable without checking
+what produces it.**
+
+## Corrected measurement
+
+Tool turn, `parallel_tool_calls: true`, 12 tools (1500 ms):
+
+```
+[ocx:cursor:frame] {"case":"interactionUpdate","update":"toolCallStarted",...}
+[ocx:cursor:frame] {"case":"conversationCheckpointUpdate","usedTokens":0}
+[ocx:cursor:client-tool-suspend] {"framesReceived":33,"elapsedMs":4488}
+[ocx:cursor:checkpoint-commit-refused] {"emittedClientTool":true,"capturedAfterClientTool":true,"externalModel":false,"storeCheckpoints":true,"capturedBytes":3036}
+```
+
+Tool turn, same 12 tools, `parallel_tool_calls` absent (50 ms):
+
+```
+[ocx:cursor:frame] {"case":"interactionUpdate","update":"toolCallStarted",...}
+[ocx:cursor:client-tool-suspend] {"framesReceived":32,"elapsedMs":2827}
+[ocx:cursor:checkpoint-commit-refused] {"emittedClientTool":true,"capturedAfterClientTool":false,"externalModel":false,"storeCheckpoints":true,"capturedBytes":0}
+```
+
+Plain turn, for shape comparison:
+
+```
+[ocx:cursor:frame] {"case":"conversationCheckpointUpdate","usedTokens":0}
+[ocx:cursor:frame] {"case":"conversationCheckpointUpdate","usedTokens":12037}
+[ocx:cursor:frame] {"case":"interactionUpdate","update":"stepCompleted"}
+[ocx:cursor:frame] {"case":"conversationCheckpointUpdate","usedTokens":12037}
+[ocx:cursor:frame] {"case":"interactionUpdate","update":"turnEnded"}
+[ocx:cursor:checkpoint-continuation] {"checkpointBytes":492,"wireModel":"default"}
+```
+
+**wp2's LATE verdict stands.** The frame arrives strictly after `toolCallStarted` and is
+cancelled away at 50 ms.
+
+## One hypothesis raised and discarded here
+
+Mid-investigation the `usedTokens: 0` on the tool-turn checkpoint was read as evidence
+that it is an early, pre-tool snapshot, which would have made branch A actively unsafe.
+The ordering above refutes that: the frame arrives **after** `toolCallStarted` within the
+same turn, and carries 3036 bytes against the 492 a plain turn commits.
+
+`usedTokens: 0` therefore looks like an unpopulated field on this update, not an empty
+snapshot. That is a reading, not a proof — and it is exactly the kind of reading this
+unit keeps getting wrong. **wp5 still owns the question of whether those 3036 bytes
+cover the tool call, and branch A2 stays gated behind it.**
diff --git a/devlog/_plan/260911_cursor_checkpoint_capture/020_phase2_responses_identity.md b/devlog/_plan/260911_cursor_checkpoint_capture/020_phase2_responses_identity.md
new file mode 100644
index 0000000000..023d9182d8
--- /dev/null
+++ b/devlog/_plan/260911_cursor_checkpoint_capture/020_phase2_responses_identity.md
@@ -0,0 +1,85 @@
+# wp3 — is the fresh `conversationId` chat-completions-specific
+
+Decides C2. Independent of wp2.
+
+## What was seen, and what it does not yet prove
+
+Two sequential `/v1/chat/completions` turns produced two different `conversationId`
+values and `checkpointInvalidationReason: missing_ref` on both. That endpoint carries
+no Responses state, so a fresh identity per turn may be correct there rather than a
+defect.
+
+`src/adapters/cursor.ts` reads the prior identity from
+`_parsed._providerContinuation?.cursor?.checkpointRef` and `_parsed._cursorConversationId`,
+and the builder comment says it "may derive a stable provider id from the client thread
+when Responses state is unavailable". Whether that derivation actually holds across
+turns is the open question.
+
+Codex uses `/v1/responses`. If identity is stable there, C2 is not user-facing and the
+honest outcome is to record that and close the half.
+
+## Procedure
+
+1. `ocx debug provider on`; record the baseline line count.
+2. Turn 1: `POST /v1/responses`, `store: true`, model `cursor/auto-intelligence`,
+   trivial prompt. Capture the response `id`.
+3. Turn 2: `POST /v1/responses` with `previous_response_id` set to that `id`.
+4. Compare the two `[ocx:cursor:run-request]` lines on `conversationId`,
+   `checkpointPresent`, `checkpointInvalidationReason`, `continuationMode`.
+5. `ocx debug provider off`.
+
+## Decision rule
+
+- **STABLE** — same `conversationId` on both turns and `checkpointPresent: true` on
+  turn 2. C2 is an artifact of the stateless endpoint. Record and close.
+- **UNSTABLE-IDENTITY** — `conversationId` differs between the two turns. That is C2
+  on the path users take. Go to `030` branch B.
+- **STABLE-IDENTITY-STORE-MISS** — `conversationId` matches but `checkpointPresent`
+  is false with `missing_ref`. Folded from the wp1 audit (medium): the original rule
+  ORed these two, but `request-builder.ts:454` returns `missing_ref` whenever no
+  thread or ref is resolved, which is reachable with a perfectly stable id. This is a
+  different defect — the checkpoint store, not identity — and needs its own doc before
+  any patch. Do not route it to branch B.
+- **BLOCKED** — the proxy rejects the Responses shape for this provider. Record what it
+  rejected; do not infer the answer from the chat-completions result.
+
+## Result — STABLE
+
+Run 2026-09-11 on macbookpro-2, same account and toggle. Two `/v1/responses` turns,
+`store: true`, second carrying `previous_response_id` from the first. Log read with a
+fixed tail, not the line-count windowing that `012` shows is void.
+
+```
+turn 1  resp_dccfe5a37e224d1e908567403c53db10
+[ocx:cursor:checkpoint-continuation] {"mode":"full-replay","conversationHash":"cursor_cdbed7dcc","checkpointRefHash":"717a262274c68762","checkpointBytes":492,"wireModel":"default"}
+
+turn 2  resp_e023130d5f684c159951cd8458e72914  (previous_response_id set)
+[ocx:cursor:checkpoint-continuation] {"mode":"checkpoint","conversationHash":"cursor_cdbed7dcc","checkpointRefHash":"e28ce47f916e7213","checkpointBytes":595,"wireModel":"default"}
+```
+
+**STABLE.** `conversationHash` is identical across both turns, and turn 2 reports
+`mode: checkpoint` rather than `full-replay` — the continuation resumed from the
+checkpoint turn 1 committed, which is exactly the behaviour `#4245` says is missing.
+
+### What this removes from the issue
+
+C2 does not affect a `/v1/responses` conversation that threads
+`previous_response_id`, which is what a Codex session does. That is the shape the
+reporter was running.
+
+**Scoped precisely, folded from the wp3 audit (near-pass residual):** the earlier
+wording claimed C2 closes for all `/v1/responses` users. It does not. A Responses
+request with **no** `previous_response_id` drops `_cursorConversationId`
+(`src/server/responses/core.ts:533`) and mints a fresh one
+(`src/adapters/cursor/request-builder.ts:361`) unless a thread owner exists, so that
+call is in the same position as chat-completions. `store: false` *with*
+`previous_response_id` is not a hole (`core.ts:461`, `core.ts:6619`).
+
+So: **closed without a patch for threaded conversations**, which is the reported
+scenario; an unthreaded one-shot Responses call still starts fresh, and that is
+expected rather than defective — there is no prior conversation to resume.
+
+That also sharpens what is left. The reporter sees `cached_tokens: 0` and full replay;
+plain multi-turn conversation on `/v1/responses` demonstrably does not do that. So the
+surviving defect is C1 — turns that emit a client tool, where the checkpoint is
+cancelled away before it can be captured. Branch B in `030` is not needed.
diff --git a/devlog/_plan/260911_cursor_checkpoint_capture/030_phase3_landing.md b/devlog/_plan/260911_cursor_checkpoint_capture/030_phase3_landing.md
new file mode 100644
index 0000000000..6ff3c4a1f0
--- /dev/null
+++ b/devlog/_plan/260911_cursor_checkpoint_capture/030_phase3_landing.md
@@ -0,0 +1,239 @@
+# wp4 — land what the probes proved, or record the verdict
+
+One branch per wp2/wp3 outcome. Only the branch the evidence selects gets built.
+
+## Branch A — wp2 = LATE
+
+The 50 ms base grace cancels the stream before upstream serializes conversation state.
+**Branch A is one edit.** The wp1 audit removed a second one; see "What branch A is
+deliberately not doing" below.
+
+**A1. MODIFY `src/adapters/cursor/live-transport.ts`.** Give a drained client-tool
+turn one bounded extension when a checkpoint is wanted and none has arrived. The
+extension must happen *before* the terminal events are pushed — once `done` reaches
+the client the turn is over.
+
+```diff
+   private scheduleClientToolFinalize(
+     state: ReturnType<typeof createCursorProtobufEventState>,
+     push: (message: CursorServerMessage) => void,
++    graceMsOverride?: number,
+   ): void {
+     this.clearPendingFinalize();
+     this.pendingFinalize = setTimeout(() => {
+       this.pendingFinalize = undefined;
+      if (this.expectedClose) return;
+-      const terminal = finalizeAfterDrain(state);
+-      if (terminal.length === 0) return;
++      // A suspended tool turn is the turn whose state we most want to resume from,
++      // and the one turn we cancelled before upstream could send it (#4245). Extend
++      // once, bounded, rather than raising the blanket grace: the common case stays
++      // at 50 ms and a stream that never sends a checkpoint still dies at a known
++      // deadline.
++      // This MUST run before finalizeAfterDrain(): that call reaches
++      // finalizeTurnEvents(), which sets state.terminated = true, and
++      // finalizeAfterDrain() returns [] for a terminated state. Draining first and
++      // then re-arming would make the retry return [] at the length check and leave
++      // the stream uncancelled. So mirror its two guards here instead of calling it.
++      if (!state.terminated
++        && state.openToolCalls.size === 0
++        && this.wantsCheckpointCapture
++        && !this.capturedCheckpointBytes
++        && !this.checkpointGraceExtended) {
++        this.checkpointGraceExtended = true;
++        this.scheduleClientToolFinalize(state, push, CHECKPOINT_CAPTURE_GRACE_MS);
++        return;
++      }
++      const terminal = finalizeAfterDrain(state);
++      if (terminal.length === 0) return;
+       for (const event of terminal) push(event);
+       debugProviderDiagnostic("cursor", "client-tool-suspend", {
+         reason: "Responses bridge owns client tools; ending turn without fake mcpResult",
+         framesReceived: this.framesReceived,
+         elapsedMs: Date.now() - this.turnStartedAt,
++        graceMs: graceMsOverride ?? this.activeClientToolFinalizeGraceMs,
++        checkpointGraceExtended: this.checkpointGraceExtended,
+       });
+       this.cancelCursorRun();
+-    }, this.activeClientToolFinalizeGraceMs);
++    }, graceMsOverride ?? this.activeClientToolFinalizeGraceMs);
+   }
+```
+
+Also NEW beside the constants at :114-117:
+`const CHECKPOINT_CAPTURE_GRACE_MS = <measured>;` sized from the arrival latency wp2
+actually observed, not guessed. NEW private fields beside `pendingFinalize`:
+`private checkpointGraceExtended = false;` and
+`private wantsCheckpointCapture = false;` — the latter set where the run request is
+applied (:643, next to `activeClientToolFinalizeGraceMs`) from
+`activeRequest.contextUsageStoreCheckpoints !== false`. Reset
+`checkpointGraceExtended = false` in `open()` (:1033) alongside `framesReceived`.
+
+The added `graceMs` field also repays wp2's instrumentation debt: after this lands,
+the NEVER verdict 010 could not reach becomes measurable from shipped diagnostics.
+
+**Termination.** `checkpointGraceExtended` is set before the re-arm, so at most one
+extension happens per turn; the second pass falls through to `finalizeAfterDrain` and
+cancels. A sibling tool call reopening `openToolCalls` during the window is handled by
+the `size === 0` guard, which also stops the one extension from being spent on a turn
+that was not actually drained.
+
+### A1b — fire early when the frame lands (required, not optional)
+
+A1 alone makes every suspended tool turn pay the full extension, including the turns
+that were never going to send a checkpoint. Measured arrival is well inside the window,
+so waiting out the remainder is pure added latency on the tool path.
+
+Make the timer body reusable and let the capture site run it immediately:
+
+```diff
+   private pendingFinalize?: ReturnType<typeof setTimeout>;
++  private pendingFinalizeRun?: () => void;
++  private checkpointGraceExtended = false;
++  private wantsCheckpointCapture = false;
+```
+
+`scheduleClientToolFinalize` stores the callback instead of inlining it:
+
+```diff
+     this.clearPendingFinalize();
+-    this.pendingFinalize = setTimeout(() => {
++    const run = (): void => {
+       ... body from A1 ...
+-    }, graceMsOverride ?? this.activeClientToolFinalizeGraceMs);
++    };
++    this.pendingFinalizeRun = run;
++    this.pendingFinalize = setTimeout(run, graceMsOverride ?? this.activeClientToolFinalizeGraceMs);
+```
+
+and `handleServerMessage`, right after `capturedCheckpointBytes` is set:
+
+```diff
+     if (message.message.case === "conversationCheckpointUpdate") {
+       try {
+         this.capturedCheckpointBytes = toBinary(ConversationStateStructureSchema, message.message.value);
+       } catch {
+         this.capturedCheckpointBytes = undefined;
+       }
++      // We are only still open because the grace was extended waiting for exactly this
++      // frame. Stop waiting. Deferred by one tick so this frame finishes being mapped
++      // and pushed before the terminal events go out — firing inline would reorder them.
++      if (this.checkpointGraceExtended && this.pendingFinalizeRun && this.capturedCheckpointBytes) {
++        const run = this.pendingFinalizeRun;
++        this.clearPendingFinalize();
++        this.pendingFinalizeRun = undefined;
++        this.pendingFinalize = setTimeout(run, 0);
++      }
+     }
+```
+
+Net effect: a turn whose checkpoint arrives pays roughly the real arrival latency; a turn
+whose checkpoint never arrives pays `CHECKPOINT_CAPTURE_GRACE_MS` once and then dies at a
+known deadline, as before.
+
+### Sizing `CHECKPOINT_CAPTURE_GRACE_MS`
+
+Measured on macbookpro-2 against a live account, 12 tools held constant on the wire:
+
+| Local grace | Post-`toolCallStarted` checkpoint | `capturedBytes` |
+|---|---|---|
+| 50 ms | no | 0 |
+| 1500 ms | yes | 3036 |
+
+750 ms and 1000 ms arms were attempted but their results are void — they were collected
+through the line-count windowing that `012` shows returns empty once the 500-line log
+ring fills. They are not evidence and are not used here.
+
+**Choose 1500 ms**, the only window with a clean positive. With A1b the cost is paid only
+when no checkpoint comes. Revisit with a bracketed rerun using tail-based reading if that
+ceiling proves too slow in practice; do not lower it on the void 750/1000 ms data.
+
+### Acceptance criteria for this work-phase
+
+1. `bun run typecheck` clean.
+2. A focused test proves: checkpoint after `tool_call_end` but past the base grace is
+   captured and committed for an external wire model with `checkpointUsable: false`;
+   a transport that never sends one still refuses and still cancels;
+   a native wire model still refuses (the gate is untouched);
+   the extension happens at most once.
+3. `bun test tests/providers/cursor` green.
+4. No change to `src/router.ts`, `src/server/lifecycle.ts`, `src/server/responses/core.ts`.
+
+## Landed
+
+`src/adapters/cursor/live-transport.ts`: `CHECKPOINT_CAPTURE_GRACE_MS = 1_500`, the
+exported pure predicate `shouldExtendForCheckpointCapture`, the one-shot extension inside
+`scheduleClientToolFinalize` placed before `finalizeAfterDrain`, the early fire from the
+`conversationCheckpointUpdate` branch of `handleServerMessage`, and `graceMs` /
+`checkpointGraceExtended` added to the `client-tool-suspend` diagnostic.
+
+Tests in `tests/providers/cursor/cursor-tool-finalize-race.test.ts`, reusing that file's
+existing transport harness. Measured in the suite: the turn that never sends a checkpoint
+finalizes at 1816 ms, the turn whose checkpoint arrives finalizes at 256 ms. That gap is
+A1b doing its job — without it both would sit out the full window.
+
+Two low findings from the implementation audit were folded rather than accepted:
+`pendingFinalizeRun` is restored alongside the early-fire timer so the pair never
+diverges, and `capturedCheckpointBytes` is reset in `open()` so a reused transport cannot
+inherit a stale snapshot. Neither was reachable in production; folding them removes the
+reachability argument.
+
+**Still open:** the native wire-model gate. `capturedAfterClientTool` is an arrival proof,
+not a coverage proof, so wp5 owns decoding the captured `ConversationStateStructure`
+before that gate moves.
+
+### What branch A is deliberately not doing
+
+The obvious companion edit — dropping `isCursorExternalWireModel` from
+`toolSuspendedCommit` in `src/adapters/cursor.ts:190` so native models also commit a
+tool-suspended checkpoint — is **excluded**, folded from the wp1 audit (high).
+
+`capturedAfterClientTool` is set at `cursor.ts:312` from *arrival order*
+(`capturedAfterClientTool = emittedClientTool` when the byte-set changes). But
+`live-transport.ts:1221` classifies `conversationCheckpointUpdate` as **liveness-only**,
+the same bucket as a heartbeat. A periodic liveness snapshot can arrive after the tool
+call while its *contents* predate it. Arrival order is therefore not coverage, and
+committing on it would claim a prefix the bytes do not contain — the exact failure this
+unit was opened to prevent.
+
+A1 alone is still a real fix: it makes the external tool-suspended path, which the code
+already intends and which has never once succeeded in production, actually work.
+`checkpointUsable` stays `!toolSuspendedCommit`, so nothing widens what a checkpoint
+claims.
+
+Extending this to native models needs content coverage proven, not assumed. That is a
+separate work-phase (wp5) whose first task is to decode a captured
+`ConversationStateStructure` and check whether the tool call is in it. The wp1 auditor
+explicitly left that decode UNVERIFIED; do not skip it.
+
+**Tests.** `tests/providers/cursor/cursor-tool-suspended-checkpoint.test.ts`: a fake
+transport that emits `conversationCheckpointUpdate` after `tool_call_end` but later
+than the base grace must yield `checkpointRef` defined and `checkpointUsable: false`;
+one that never emits must still refuse with `capturedBytes: 0`; and composer-2.5 must
+keep whatever `cursorNeedsExternalToolContinuation` already guarantees.
+
+**Risk.** Every suspended tool turn gets up to one extra bounded wait before the
+stream closes. That is added latency on the tool path, so the constant must come from
+the measurement, and the no-frame case must still terminate.
+
+## Branch B — wp3 = UNSTABLE
+
+Identity, not capture. The checkpoint exists and is simply unreachable because turn
+N+1 derives a different `conversationId`. The fix is in how
+`_cursorConversationId` / `_providerContinuation` are threaded on the Responses path,
+which is request-assembly territory rather than adapter transport.
+
+Do not start this as a patch. Write the observed identity chain into a `021` doc
+first, then decide whether the correct owner is the Cursor adapter or the Responses
+state layer. If it turns out to need `src/server/responses/core.ts`, it is out of this
+unit's scope and becomes NEEDS_HUMAN with the evidence attached.
+
+## Branch C — wp2 = NEVER and wp3 = STABLE
+
+Nothing is safely fixable here. Deliverable is the recorded verdict: this file gains a
+closing section, `000_plan.md` gets the outcome, issue #4245 gets a comment naming
+what was measured and what would change the answer, and the unit moves to `_fin/`.
+
+A recorded negative with captured evidence is a real outcome. The failure mode this
+unit was opened against was a plausible patch that fixed nothing, so shipping nothing
+beats shipping that.
diff --git a/devlog/_plan/260911_cursor_checkpoint_capture/040_wp5_coverage_instrument.md b/devlog/_plan/260911_cursor_checkpoint_capture/040_wp5_coverage_instrument.md
new file mode 100644
index 0000000000..e6a5877a33
--- /dev/null
+++ b/devlog/_plan/260911_cursor_checkpoint_capture/040_wp5_coverage_instrument.md
@@ -0,0 +1,50 @@
+# wp5 — making the coverage question answerable
+
+Branch A landed, so the native wire-model gate now depends on one question: do the captured
+bytes actually cover the tool call, or did they merely arrive after it?
+
+## Why this could not be settled by reading harder
+
+`capturedAfterClientTool` is set from arrival order (`cursor.ts:312`), and
+`conversationCheckpointUpdate` is classified liveness-only (`live-transport.ts:1221`). Every
+diagnostic this adapter emits about a checkpoint reports its size in bytes, and a byte count
+cannot distinguish a snapshot that contains the suspended call from one that does not.
+
+The schema can. `ConversationStateStructure.pendingToolCalls` is documented upstream as
+"raw JSON stringified tool-call content parts awaiting execution" — a non-zero count on a
+suspended turn is the coverage evidence, and the strings themselves are request content that
+must never be logged.
+
+## What landed
+
+`cursorCheckpointShape` in `checkpoint-store.ts`: decodes a snapshot and returns **counts
+only** for `turns`, `turnsOld`, `rootPromptMessages`, `todos`, `pendingToolCalls`. Failure
+returns `undefined`; it never throws into the request path. Wired into
+`checkpoint-commit-refused` as `capturedShape`, behind `isDebugEnabled()` so the decode does
+not run on a normal request.
+
+That converts the remaining question from "build an instrumented binary and decode bytes by
+hand" into "read one log line".
+
+## What is NOT answered yet, and why
+
+The live read needs this code running on a machine with a Cursor login. Attempts to shortcut
+it with a standalone harness failed: driving the adapter outside the server never reaches the
+credential initialisation the proxy does at startup (`getAccountSet` reports not-logged-in
+even after `loadAuthStore`, which points at the keyring path rather than `auth.json`).
+
+Running a second proxy would have worked, but only by either copying the credential store or
+sharing the running instance's `OPENCODEX_HOME` and clobbering its pid and admin-token files.
+Neither is worth it for a question that answers itself one release later.
+
+**So wp5 is split.** The instrument is done. The live read is a follow-up: after this ships,
+run a forced tool call on a Cursor account with `ocx debug provider on` and read
+`capturedShape.pendingToolCalls` off `checkpoint-commit-refused`.
+
+- `pendingToolCalls > 0` → the snapshot covers the call; the native gate can be removed with
+  the ordering proof upgraded to a coverage proof.
+- `pendingToolCalls === 0` → arrival is not coverage, the current gate is correct, and the
+  native half of #4245 is not fixable this way. Record it and close.
+
+Either answer is a real outcome. What was not acceptable was guessing, which is what the
+original triage did and what this unit has now avoided four separate times.
diff --git a/devlog/_plan/260911_deepseek_v41_transition/000_plan.md b/devlog/_plan/260911_deepseek_v41_transition/000_plan.md
new file mode 100644
index 0000000000..9c2493b74a
--- /dev/null
+++ b/devlog/_plan/260911_deepseek_v41_transition/000_plan.md
@@ -0,0 +1,45 @@
+# 260911 — DeepSeek V4.1 전환
+
+DeepSeek가 2026-09-10에 V4.1-Flash를 내면서 V4 계열의 이름이 한 번에 움직였다. `deepseek-v4-flash`와 `deepseek-v4-flash-vision-exp`는 모델로서 은퇴하고 이름만 V4.1-Flash로 라우팅되는 별칭이 됐고, `deepseek-v4-pro`는 2026-09-14 04:00 UTC부터 단계적으로 퇴역하며 그 시점부터 요청이 V4.1-Flash로 넘어간다. opencodex는 이 두 id를 13개 프로바이더 프리셋에 손으로 박아두고 있어서, 그대로 두면 Pro 컨텍스트 창과 Pro 가격을 광고하면서 실제로는 Flash를 서빙하는 상태가 된다. 이 유닛은 V4.1을 전개하고 v4-pro를 걷어내고, 같은 영역을 건드리는 기여자 PR을 먼저 정리한 뒤 둘 다 dev에 머지한다. 바뀌는 사람은 DeepSeek 경로를 쓰는 모든 사용자다.
+
+근거는 `001_evidence.md`, 출현 지점 집계는 `002_inventory.md`에 있다.
+
+## 루프 스펙
+
+| 항목 | 내용 |
+| --- | --- |
+| Loop archetype | satisfy-spec |
+| Trigger | 사용자 지시: v4.1-flash를 v4-flash가 있는 모든 곳에 전개하고, 퇴역한 v4-pro를 전부 제거하고, PR #4258과 #4274를 머지하라 |
+| Goal | V4.1 전개 + v4-pro 제거가 focused 테스트와 함께 dev에 머지되고, #4258/#4274도 머지된다 |
+| Non-goals | 새 사용자 config 필드, 어댑터 와이어 동작 변경, main/preview 승격, 릴리스, 생성 메타데이터 수작업 편집 |
+| Verifier | `bun test` 영향 도메인, `bun run typecheck`, `bun run privacy:scan`, 머지 전 exact-head CI |
+| Stop condition | 두 PR과 이번 변경이 dev에 머지된 시점 |
+| Memory artifact | `devlog/_plan/260911_deepseek_v41_transition/` |
+| Expected terminal outcomes | DONE = 머지 완료. BLOCKED = CI가 이 변경과 무관한 이유로 반복 실패하거나 머지 권한이 거부될 때 |
+| Escalation condition | 사용자가 머지를 명시 승인했다. main/preview 승격과 릴리스는 별도 승인 필요 |
+| Resource bounds | 쓰기 범위: `src/`, `tests/`, `docs-site/`, 이 플랜 유닛. 전체 스위트는 사용자 지시로 로컬에서 돌리지 않고 CI에 위임한다 |
+
+## 작업 단계 지도
+
+| work-phase | 문서 | 내용 |
+| --- | --- | --- |
+| wp1 | 000-002 | 근거·인벤토리·로드맵 잠금 (docs only) |
+| wp2 | `010_phase1_pr4258.md` | 기여자 PR #4258 리뷰와 머지 |
+| wp3 | `020_phase2_v41_rollout.md` | V4.1-Flash 전개 |
+| wp4 | `030_phase3_v4pro_removal.md` | v4-pro 퇴역 제거 |
+| wp5 | `040_phase4_merge.md` | docs-site 동기화, PR 게시와 머지 |
+
+## 이 유닛이 내린 두 가지 판단
+
+**1. id는 프로바이더별로 다르다.** DeepSeek 1st-party API의 공식 id는 `deepseek-flash`다. 게이트웨이가 노출하는 철자는 `deepseek-v4.1-flash`이고, 이건 이슈 #4253과 PR #4258이 저장소 안에서 확인해 준 사실이다. "모든 곳에 같은 id"로 넣으면 네이티브 쪽이 틀린 id를 갖는다.
+
+**2. 벤더 호스팅 스냅샷은 DeepSeek 수명주기와 별개다.** Volcengine Ark는 `deepseek-v4-pro-260425`처럼 날짜가 박힌 스냅샷을 고정하고, Alibaba·Ollama Cloud·NVIDIA NIM·Baseten도 각자 로스터를 따로 발표한다. DeepSeek 1st-party 퇴역 공지가 그 벤더들의 배포까지 끝내지는 않는다. 그래서 제거는 **DeepSeek 1st-party와 그것을 되파는 Zen 계열을 먼저** 확정하고, 벤더 호스팅 프리셋은 같은 커밋에서 분리해 PR 본문에 근거와 함께 드러낸다 — 리뷰어가 한 커밋만 떼어낼 수 있게.
+
+## wp1 감사 반영 (2026-09-11)
+
+독립 감사가 로드맵 초안의 결함 6건을 잡았고 전부 수용했다. 가장 큰 것 둘:
+
+- 초안은 공유 상수 `DEEPSEEK_THINKING_MODELS`에 V4.1을 넣으려 했는데, 그 상수는 `deepseek` 1st-party 프리셋의 `models:` 배열 자체를 포함해 6개 프리셋 21곳이 소비한다(`registry.ts:2045`). 그대로 하면 게이트웨이 철자가 네이티브 프리셋으로 새서 020의 수용기준이 자기모순이 된다. 상수를 분리하는 설계로 다시 썼다.
+- 초안의 "Pro 사다리를 광고한다"는 근거가 없다. `DEEPSEEK_PRO_*`와 `DEEPSEEK_FLASH_*` 효율 맵은 값이 같다(`registry.ts:701-715`). 실제로 어긋나는 건 **컨텍스트 창과 가격**이다.
+
+나머지는 002/020/030의 해당 절에 반영했다.
diff --git a/devlog/_plan/260911_deepseek_v41_transition/001_evidence.md b/devlog/_plan/260911_deepseek_v41_transition/001_evidence.md
new file mode 100644
index 0000000000..2d4e93b1ce
--- /dev/null
+++ b/devlog/_plan/260911_deepseek_v41_transition/001_evidence.md
@@ -0,0 +1,25 @@
+# 001 — 근거
+
+2026-09-11 웹 조사. 출처는 DeepSeek 공식 API 문서와 9/10 공지.
+
+## 확인된 사실
+
+| 사실 | 출처 |
+| --- | --- |
+| V4.1-Flash 출시 2026-09-10 | <https://api-docs.deepseek.com/news/news260910/> |
+| 공식 API id는 `deepseek-flash` | <https://api-docs.deepseek.com/> |
+| `deepseek-v4-flash`와 `deepseek-v4-flash-vision-exp`는 모델로서 은퇴, 이름은 V4.1-Flash로 라우팅되는 호환 별칭으로 유지, Flash 가격 과금 | <https://api-docs.deepseek.com/> |
+| `deepseek-v4-pro`는 2026-09-14 04:00 UTC부터 단계적 퇴역, 이후 요청은 V4.1-Flash로 자동 라우팅, 신규 연동은 `deepseek-flash` 권고 | <https://api-docs.deepseek.com/news/news260910/> |
+
+## 기록해 두는 불일치
+
+같은 체인지로그를 근거로, 질의 표현에 따라 상반된 요약이 돌아왔다. 한쪽은 위 표대로 v4-pro 퇴역과 Flash 요금 적용을 말했고, 다른 쪽은 "9월 14일 이후에도 서비스 계속, 과금 변동 없음, 7월 24일 퇴역한 건 `deepseek-chat`/`deepseek-reasoner`"라고 답했다.
+
+이 유닛은 전자를 따른다. 다만 두 해석이 공통으로 인정하는 사실 하나만으로도 변경 근거는 충분하다: **9월 14일부터 `deepseek-v4-pro` 요청은 V4.1-Flash로 라우팅된다.** 퇴역이냐 임시 라우팅이냐와 무관하게, 그 시점 이후 `deepseek-v4-pro` 행은 Pro 사다리·Pro 컨텍스트·Pro 가격을 광고하면서 Flash를 서빙한다. 잘못된 광고를 남겨두는 쪽이 제거보다 나쁘다.
+
+저장소 내부 근거로는 이슈 #4253과 PR #4258이 Command Code 라이브 로스터에서 `deepseek/deepseek-v4.1-flash`가 실제로 서빙되는 것을 확인해 준다.
+
+## 이 유닛이 주장하지 않는 것
+
+- 벤더 호스팅(Volcengine, Alibaba, Ollama Cloud, NVIDIA NIM, Baseten, cline-pass, orcarouter, codebuddy, qoder) 로스터에서 v4-pro가 중단됐다는 주장은 **하지 않는다**. 그쪽은 각자 스냅샷과 일정이 있고, Volcengine은 `deepseek-v4-pro-260425`처럼 날짜가 박힌 id를 쓴다.
+- Zen 게이트웨이가 `deepseek-flash` 철자를 받는다는 주장도 하지 않는다. 게이트웨이 쪽은 관측된 `deepseek-v4.1-flash`를 쓴다.
diff --git a/devlog/_plan/260911_deepseek_v41_transition/002_inventory.md b/devlog/_plan/260911_deepseek_v41_transition/002_inventory.md
new file mode 100644
index 0000000000..bb774fff9a
--- /dev/null
+++ b/devlog/_plan/260911_deepseek_v41_transition/002_inventory.md
@@ -0,0 +1,49 @@
+# 002 — 출현 지점 집계
+
+`rg` 기준, 2026-09-11 브랜치 `codex/260911-opencode-go-free-stabilization`.
+
+| id | 파일 수 | 히트 수 |
+| --- | --- | --- |
+| `deepseek-v4-pro` | 62 | 293 |
+| `deepseek-v4-flash` | 99 | 585 |
+
+## `DEEPSEEK_THINKING_MODELS` 소비처 (감사 정정)
+
+이 상수(`registry.ts:619`)는 Zen 3종만 먹이는 게 아니다. **6개 프리셋 21곳**이 소비하며, 그중에는 `deepseek` 1st-party 프리셋의 `models:` 배열 자체가 포함된다.
+
+| 프리셋 | 앵커 |
+| --- | --- |
+| `opencode-go` | 1760, 1768, 1776, 1803, 1813 |
+| `deepseek` 1st-party | **2045 (`models:` spread)**, 2114-2121 |
+| `alibaba-token-plan` | 2813-2818 |
+| `opencode-zen` | 3047-3064 |
+| `opencode-free` | 3108 |
+
+이것 때문에 "공유 상수에 V4.1을 추가" 설계는 성립하지 않는다. 020이 상수 분리로 다시 설계됐다.
+
+## v4-pro를 선언하는 프로바이더 (registry.ts)
+
+| 프로바이더 | 성격 | 앵커 |
+| --- | --- | --- |
+| `deepseek` (1st-party) | **DeepSeek 직접** | 2038-2078 (`modelContextWindows`, `modelWireDefaults`, `modelResponsesTerminalRepair`) |
+| `opencode-go` / `opencode-zen` / `opencode-free` | Zen 게이트웨이가 DeepSeek을 되팜 | 619 `DEEPSEEK_THINKING_MODELS`, 1793 |
+| `command-code` (OAuth + API key) | 게이트웨이 | 631, 1180-1190, 2305 |
+| `alibaba-token-plan` / `-intl` | 벤더 호스팅 | 736, 749, 758, 2832, 2857-2913 |
+| `volcengine` ark / coding / agent | 벤더 호스팅, **날짜 스냅샷** `deepseek-v4-pro-260425` | 791, 807, 816, 838, 850, 2785, 2791 |
+| `ollama` cloud | 벤더 호스팅 | 2951, 2963 |
+| `nvidia-nim` | 벤더 호스팅 | 969 |
+| `baseten` | 벤더 호스팅 (`deepseek-ai/DeepSeek-V4-Pro`) | 1010-1059 |
+| `cline-pass` | 게이트웨이 | 1144, 1199 |
+| `orcarouter` | 게이트웨이 | 1180-1190 |
+| `codebuddy` / `qoder` | 게이트웨이 | `codebuddy-models.ts`, `qoder-models.ts` |
+
+## 손대지 않는 영역과 이유
+
+| 영역 | 이유 |
+| --- | --- |
+| `scripts/model-metadata.source.json` (47건), `src/generated/model-metadata.ts` (3건) | 벤더 스냅샷에서 **생성되는** 파일이다. 손으로 지우면 다음 생성에서 되돌아온다. 게다가 `src/usage/cost.ts`가 과거 요청 비용을 이 표로 계산하므로, 행을 지우면 이미 기록된 사용량의 원가가 깨진다 |
+| 임의 fixture id로 v4-pro를 쓰는 테스트 | 레지스트리 멤버십을 주장하지 않는 테스트는 모델 id를 문자열로만 쓴다. 깨지는 것만 고친다 |
+
+## 테스트 영향 예상
+
+감사 정정: 영향 파일은 5개가 아니라 **24개**다. 위 다섯 외에 `tests/routing/router.test.ts:450`(정확 목록), `tests/providers/orcarouter-provider.test.ts:139`, `tests/gui/alibaba-intl-token-plan.test.ts:31`, `tests/routing/fastwire-policy.test.ts`, `tests/codex-integration/slug-codec.test.ts`, `tests/server/adapter-resolve.test.ts` 등이 포함된다.
diff --git a/devlog/_plan/260911_deepseek_v41_transition/010_phase1_pr4258.md b/devlog/_plan/260911_deepseek_v41_transition/010_phase1_pr4258.md
new file mode 100644
index 0000000000..abafbf70c4
--- /dev/null
+++ b/devlog/_plan/260911_deepseek_v41_transition/010_phase1_pr4258.md
@@ -0,0 +1,31 @@
+# 010 — wp2: 기여자 PR #4258 리뷰와 머지
+
+<https://github.com/lidge-jun/opencodex/pull/4258> · `gitgarmin` · base `dev` · head `codex/command-code-v41-qwen-efforts`
+
+파일 2개: `src/providers/command-code-efforts.ts` (+23/-0), `tests/providers/command-code-provider.test.ts` (+33/-0).
+
+## 왜 먼저인가
+
+같은 파일을 wp3에서 건드린다. 기여자 PR을 먼저 넣고 그 위에 리베이스하는 게 순서다. 반대로 하면 기여자가 리베이스 부담을 진다.
+
+## 리뷰 항목
+
+1. 추가된 두 행(`deepseek/deepseek-v4.1-flash`, `Qwen/Qwen3.8-Flash`)이 `COMMAND_CODE_MODEL_EFFORTS` 조회 계약과 맞는가.
+2. 사다리 값의 출처가 본문 주장과 일치하는가. 본문은 같은 패밀리 행에서 추론했다고 밝히고, 라이브 200 응답을 근거로 든다.
+3. 신규 테스트가 케이스 폴딩과 두 프리셋(OAuth/API key)을 모두 고정하는가.
+4. AGENTS.md 리뷰 규칙: base `dev` ✓, 보안 표면 미접촉, 테스트 동반.
+5. CI가 exact head에서 green인가.
+
+## 수용 기준
+
+- 리뷰 코멘트가 영어로 남는다 (AGENTS.md 리뷰 규칙).
+- exact-head CI green을 확인한 뒤 머지한다.
+- 머지 후 `dev`를 받아 내 브랜치를 리베이스하고 충돌이 없음을 확인한다.
+
+## 검증
+
+```
+gh pr checks 4258
+gh pr view 4258 --json mergeStateStatus,reviewDecision
+bun test tests/providers/command-code-provider.test.ts
+```
diff --git a/devlog/_plan/260911_deepseek_v41_transition/020_phase2_v41_rollout.md b/devlog/_plan/260911_deepseek_v41_transition/020_phase2_v41_rollout.md
new file mode 100644
index 0000000000..c2cf34f776
--- /dev/null
+++ b/devlog/_plan/260911_deepseek_v41_transition/020_phase2_v41_rollout.md
@@ -0,0 +1,67 @@
+# 020 — wp3: V4.1-Flash 전개 (2차 감사 후 재설계)
+
+## 두 번 틀렸던 지점
+
+**1차 초안**: `DEEPSEEK_THINKING_MODELS`에 V4.1을 그냥 얹으려 했다. 그 상수는 `deepseek` 1st-party 프리셋의 `models:`를 포함해 6개 프리셋이 공유하므로, 게이트웨이 철자가 네이티브로 샌다.
+
+**2차 초안**: 그래서 상수를 레거시 전용으로 고정하고 신규 id를 따로 넣으려 했다. 감사가 `fail`을 냈고 이유가 맞다 — `deepseek` 프리셋의 모델별 맵 **다섯 개**가 전부 그 상수에서 파생된다(`registry.ts:2121-2124, 2128`). 상수를 레거시로 묶으면 `deepseek-flash`는 사다리·요약·`reasoning_content` 리플레이·비전 차단을 **전부** 잃고 #78형 400이 재발한다.
+
+## 확정 설계: 상수를 세 갈래로 파생시킨다
+
+```ts
+// 업스트림이 호환 별칭으로 유지하는 레거시 V4 id
+const DEEPSEEK_V4_LEGACY_MODELS = ["deepseek-v4-pro", "deepseek-v4-flash"];
+// DeepSeek 1st-party: 공식 id는 deepseek-flash
+const DEEPSEEK_NATIVE_THINKING_MODELS = ["deepseek-flash", ...DEEPSEEK_V4_LEGACY_MODELS];
+// Zen 게이트웨이가 노출하는 철자
+const DEEPSEEK_GATEWAY_THINKING_MODELS = ["deepseek-v4.1-flash", ...DEEPSEEK_V4_LEGACY_MODELS];
+```
+
+기존 이름 `DEEPSEEK_THINKING_MODELS`는 `DEEPSEEK_V4_LEGACY_MODELS`로 바뀐다. 벤더 호스팅 프리셋(volcengine 플랜, alibaba)은 그 레거시 상수를 계속 쓴다 — 그쪽은 V4 스냅샷을 자기 일정으로 서빙한다.
+
+## 파일 변경 지도
+
+| 위치 | 변경 |
+| --- | --- |
+| `registry.ts:619` | 상수 3개로 재구성 |
+| `registry.ts:2121-2124, 2128` (deepseek 프리셋) | 다섯 맵을 `DEEPSEEK_NATIVE_THINKING_MODELS`로 전환 |
+| `registry.ts:2049` (`models:`) | 같은 상수로 전환 |
+| `registry.ts:2053` | `defaultModel`을 `deepseek-flash`로 |
+| `registry.ts:2062, 2078` | `modelContextWindows`·`modelWireDefaults`·`modelResponsesTerminalRepair`에 `deepseek-flash` 항목 추가 |
+| `registry.ts:1760, 1768, 1776, 1803, 1813` (opencode-go) | `DEEPSEEK_GATEWAY_THINKING_MODELS`로 전환 |
+| `registry.ts:1791` (go `noVisionModels`, 리터럴) | `deepseek-v4.1-flash` 추가 |
+| `registry.ts:3053-3071` (opencode-zen) | 게이트웨이 상수로 전환. 이 프리셋엔 `modelSupportsReasoningSummaries` 필드 자체가 없다 — 새로 만들지 않는다 |
+| `registry.ts:3115` (opencode-free `noJsonSchemaModels`) | 게이트웨이 상수로 전환 |
+| `src/providers/default-aliases.ts:54` 앞 | `/^deepseek-v4\.1/ → "ds41"` 을 `/^deepseek-v4/` **앞**에 둔다(첫 매치 승리). `/^deepseek-flash/ → "dsf"` 는 위치 무관 |
+
+**건드리지 않는 것**: `opencode-free`의 `noVisionModels`(`3111`)는 `OPENCODE_ZEN_TEXT_ONLY_MODELS` 참조라 여기에 넣으면 zen까지 오염된다. free는 원래 DeepSeek id를 이 목록에 갖고 있지 않으므로 그대로 둔다. `command-code`는 PR #4258 소유. 벤더 호스팅 9곳은 V4.1 서빙 근거가 없어 제외.
+
+## 수용 기준
+
+1. `deepseek` 프리셋에서 `deepseek-flash`가 사다리·효율맵·요약·replay·noVision **다섯 곳 모두**에 나타난다. 이게 2차 감사가 잡은 실패 지점이므로 테스트로 직접 관측한다.
+2. `opencode-go`에서 `deepseek-v4.1-flash`가 같은 대우를 받는다.
+3. **반대 증거**: `deepseek` 프리셋에 `deepseek-v4.1-flash`가 없고, Zen 프리셋에 `deepseek-flash`가 없다.
+4. 벤더 호스팅 프리셋(volcengine coding plan)의 DeepSeek 목록은 변하지 않는다.
+5. `deepseek` `defaultModel`이 `deepseek-flash`다.
+
+## 갱신해야 하는 기존 테스트 (감사 열거)
+
+`tests/providers/provider-registry-parity.test.ts`: `197`(deepseek preserveReasoningContentModels `toEqual`), `199-201`(deepseek noVisionModels `toEqual`), `309`(defaultModel), `73-80`(go noVision `toEqual`), `86-92`(3종 noJsonSchema `toEqual`), `1421-1453`(DeepSeek id 열거). `tests/providers/opencode-go-deepseek.test.ts:159-160`(noJsonSchema `toEqual`). `tests/codex-integration/reasoning-effort.test.ts:274`(동일 `toEqual`).
+
+`parity:184`는 `toContain`이라 안전하고, `model-metadata-sync.test.ts`는 `scripts/model-metadata.source.json`만 입력으로 재생성·바이트 비교하므로 레지스트리 추가로 깨지지 않는다.
+
+## 기록해 두는 부수 사실
+
+`scripts/model-metadata.source.json`에 `deepseek-flash`와 `deepseek-v4.1-flash` 행이 모두 없어 두 id의 비용 추정이 빈다. 생성 파일은 손대지 않는 방침(002)이므로 다음 메타데이터 생성에서 채워진다. PR 본문에 명시한다.
+
+`opencode-free`는 `liveModels: true`인데 게이트웨이 상수 전환이 `noJsonSchemaModels` 한 곳뿐이라 `deepseek-v4.1-flash`가 사다리와 replay를 받지 못한다. 기존 `deepseek-v4-pro`/`-flash`도 같은 비대칭이므로 신규 결함은 아니다. PR 본문에 한 줄 남긴다.
+
+## 검증
+
+```
+bun test tests/providers/provider-registry-parity.test.ts
+bun test tests/providers/opencode-go-deepseek.test.ts
+bun test tests/providers/deepseek-reasoning-replay.test.ts
+bun test tests/codex-integration/slug-codec.test.ts
+bun run typecheck
+```
diff --git a/devlog/_plan/260911_deepseek_v41_transition/030_phase3_v4pro_removal.md b/devlog/_plan/260911_deepseek_v41_transition/030_phase3_v4pro_removal.md
new file mode 100644
index 0000000000..f4ea052422
--- /dev/null
+++ b/devlog/_plan/260911_deepseek_v41_transition/030_phase3_v4pro_removal.md
@@ -0,0 +1,90 @@
+# 030 — wp4: `deepseek-v4-pro` 퇴역 제거
+
+## 커밋 분리
+
+제거 근거의 강도가 프로바이더마다 다르므로 두 커밋으로 나눈다. 리뷰어가 뒤쪽만 떼어낼 수 있어야 한다.
+
+**커밋 A — DeepSeek 1st-party와 그것을 되파는 경로 (근거 강함)**
+
+| 대상 | 앵커 |
+| --- | --- |
+| `deepseek` 프리셋 | `registry.ts:2038-2078` — `modelContextWindows`, `modelWireDefaults`, `modelResponsesTerminalRepair`에서 제거 |
+| `DEEPSEEK_THINKING_MODELS` | `registry.ts:619` — v4-pro 제거. Zen 3종과 volcengine 플랜이 이 상수를 공유하므로 파급을 각 사용처에서 확인 |
+| `opencode-go` `noVisionModels` | `registry.ts:1793` |
+| `command-code` 계열 | `registry.ts:631, 1180-1190, 2305`, `command-code-efforts.ts`, `adapters/command-code.ts:498` |
+| `cline-pass` | `registry.ts:1144, 1199`, `adapters/cline-pass-deepseek-v4-tool-replay.ts:5` |
+| `orcarouter` | `registry.ts:1180-1190` |
+| `codebuddy` / `qoder` | `codebuddy-models.ts:38,124,145`, `qoder-models.ts:13` |
+| `router.ts:686` | 잔여 참조 |
+| 주석 (감사 추가) | `registry.ts:631, 719, 2038, 2305` — 코드에서 사라진 뒤에도 주석이 남으면 수용기준 1이 성립하지 않는다 |
+
+## wp4 감사 반영 (2026-09-11): 삭제만으로는 사라지지 않는다
+
+감사가 결정적인 사실을 잡았다. `liveModels: true`인 프로바이더(cline-pass, orcarouter, baseten, commandcode, command-code, digitalocean, qoder)는 **정적 행을 지워도 모델이 라이브 디스커버리로 다시 올라온다.** 지워지는 건 모델이 아니라 컨텍스트 창·사다리·text-only 힌트뿐이다. 그 결과는 제거가 아니라 순수 퇴행이다 — 비전 사이드카가 이미지를 떨구고 replay 완화가 사라진 채로 모델이 계속 보인다.
+
+그래서 제거는 두 메커니즘으로 갈린다.
+
+| 프로바이더 성격 | 대상 | 방법 |
+| --- | --- | --- |
+| 정적 `models:` 로스터 | alibaba-token-plan, alibaba-token-plan-intl, volcengine ark/coding/agent, ollama, nvidia-nim | 행 삭제 — 실제로 사라진다 |
+| 라이브 디스커버리 | cline-pass, orcarouter, baseten, commandcode, command-code, digitalocean, qoder | `ROUTED_MODEL_COMPATIBILITY_EXCLUSIONS`(`src/codex/catalog/parsing.ts:180`)에 슬러그 등록 — 이게 실제로 카탈로그에서 빼는 유일한 수단이다. 그 위에서 정적 메타데이터 행도 함께 정리한다 |
+
+### 제외 슬러그 형식 (확인됨)
+
+`catalogModelSlug`(`parsing.ts:842`)는 `model.alias ?? routedSlug(provider, id)`이고, 모델 id 안의 슬래시는 하이픈이 된다. 실제 예시가 테스트에 박혀 있다: `commandcode/deepseek-deepseek-v4-pro`(`tests/codex-integration/codex-catalog.test.ts:2230`).
+
+따라서 등록할 슬러그는 다음 형태다. **각각 실제 카탈로그 출력으로 확인한 뒤 넣는다 — 형식이 틀리면 제외가 조용히 아무 일도 하지 않는다.**
+
+| 프로바이더 | 모델 id | 슬러그 |
+| --- | --- | --- |
+| `commandcode` | `deepseek/deepseek-v4-pro` | `commandcode/deepseek-deepseek-v4-pro` |
+| `command-code` | `deepseek/deepseek-v4-pro` | `command-code/deepseek-deepseek-v4-pro` |
+| `orcarouter` | `deepseek/deepseek-v4-pro` | `orcarouter/deepseek-deepseek-v4-pro` |
+| `cline-pass` | `cline-pass/deepseek-v4-pro` | `cline-pass/cline-pass-deepseek-v4-pro` |
+| `baseten` | `deepseek-ai/DeepSeek-V4-Pro` | `baseten/deepseek-ai-DeepSeek-V4-Pro` |
+| `digitalocean` | (확인 필요) | (확인 필요) |
+| `qoder` | (확인 필요) | (확인 필요) |
+
+## 감사가 잡은 나머지
+
+- `registry.ts:2864` volcengine-agent-plan `defaultModel`이 `deepseek-v4-pro`다. 같은 커밋에서 로스터 내 다른 id로 교체한다.
+- `ORCAROUTER_TEXT_ONLY_MODELS`(`1204`)와 `ORCAROUTER_MODEL_REASONING_EFFORT_MAP`(`1210`)은 v4-pro만 담고 있어 빈 컬렉션이 된다. `types/provider.ts:735`가 빈 배열을 "명시적 opt-out"으로 정의하므로 **빈 채로 두지 말고 상수와 소비 필드를 함께 삭제**한다.
+- 대문자 id는 소문자 `rg`에 안 잡힌다: `registry.ts:1031,1042,1052`(baseten `deepseek-ai/DeepSeek-V4-Pro`), `qoder-models.ts:13`. 완료 기준의 `rg`는 `-i`를 쓴다.
+- 내가 baseten이라고 적었던 `registry.ts:1080`은 실제로 DigitalOcean 목록이다.
+- `command-code-efforts.ts:4` 행을 지우면 `router.ts:107`의 `knownModelIdsForProvider`가 그 키맵을 known-id 소스로 쓰므로 슬러그 디코드가 사라진다. 방금 머지된 v4.1-flash 행은 다른 키라 대체가 아니다. `146`행 주석도 사라진 행을 가리키게 되므로 같이 고친다.
+- 후속 대상: 9개 로케일 문서, `frontier-benchmarks.json`, `src/generated/model-metadata.ts`, `model-rename-migration.ts:111`(사용자 config 마이그레이션), `structure:check`.
+
+**커밋 B — 벤더 호스팅 (근거 약함, 분리)**
+
+`alibaba-token-plan`/`-intl`, `volcengine` ark/coding/agent (`deepseek-v4-pro-260425` 포함), `ollama`, `nvidia-nim`, `baseten`.
+
+**`volcengine-agent-plan`의 `defaultModel`이 `deepseek-v4-pro`다(`registry.ts:2832`).** 제거하면 기본 모델이 비므로 같은 커밋에서 대체 기본값을 정해야 한다. 이 프리셋의 나머지 로스터에서 고른다.
+
+이 벤더들은 자체 스냅샷과 일정으로 배포한다. DeepSeek 1st-party 퇴역 공지가 그들의 로스터를 끝내지 않는다. 지시는 전부 제거였으므로 실행하되, PR 본문에 이 구분과 되돌리는 방법을 명시한다.
+
+## 손대지 않는 것
+
+`scripts/model-metadata.source.json`과 `src/generated/model-metadata.ts`. 생성 파일이고, `src/usage/cost.ts`가 과거 사용량 원가를 이 표로 계산한다. 행을 지우면 이미 기록된 요청의 비용이 깨진다. 002 참조.
+
+## 수용 기준
+
+1. `rg "deepseek-v4-pro" src`가 생성 파일을 제외하고 0건이다.
+2. 레지스트리 멤버십을 고정하던 테스트가 갱신되고 통과한다.
+3. 반대 증거: `deepseek-v4-flash` 별칭은 남는다 — DeepSeek이 이름을 유지한다고 명시했고, 그걸 지우면 기존 사용자 config가 깨진다.
+4. **어느 프리셋의 `defaultModel`도** 퇴역 id를 가리키지 않는다. `deepseek`뿐 아니라 `volcengine-agent-plan`(2832)을 포함한다.
+5. 주석에도 `deepseek-v4-pro`가 남지 않는다.
+
+## 검증
+
+```
+bun test tests/providers tests/codex-integration/codex-catalog.test.ts
+bun test tests/gui/volcengine-providers.test.ts tests/providers/baseten-provider.test.ts
+bun run typecheck
+rg "deepseek-v4-pro" src --glob "!src/generated/**"
+```
+
+## 리스크
+
+영향 파일이 62개이고, 레지스트리 멤버십을 고정하는 테스트만 24개다(002 정정). 전체 스위트를 로컬에서 돌리지 않으므로(사용자 지시) 놓친 참조는 CI가 잡는다. CI 실패 시 해당 파일만 좁혀 고친다.
+
+사다리 자체는 바뀌지 않는다는 점도 기록해 둔다: `DEEPSEEK_PRO_THINKING_EFFORTS`와 `DEEPSEEK_FLASH_THINKING_EFFORTS`는 값이 같다(`registry.ts:701-715`). 퇴역으로 실제로 어긋나는 건 컨텍스트 창과 가격이다.
diff --git a/devlog/_plan/260911_deepseek_v41_transition/040_phase4_merge.md b/devlog/_plan/260911_deepseek_v41_transition/040_phase4_merge.md
new file mode 100644
index 0000000000..b9f263923e
--- /dev/null
+++ b/devlog/_plan/260911_deepseek_v41_transition/040_phase4_merge.md
@@ -0,0 +1,31 @@
+# 040 — wp5: PR 게시와 머지
+
+## docs-site 동기화 (감사 추가)
+
+`deepseek-v4-pro`는 9개 로케일의 `guides/providers.md`, `guides/sidecars.md`, `guides/model-ordering.md`, `reference/configuration/providers.md`와 `docs-site/src/data/frontier-benchmarks.json`에 등장한다. 코드에서 모델을 지우면서 문서가 그대로면 영문 원문과 로케일이 동시에 거짓이 된다.
+
+범위: 제거된 모델을 **사용 가능한 모델로 제시하는** 문장만 고친다. 벤치마크 데이터(`frontier-benchmarks.json`)는 과거 측정 기록이므로 손대지 않는다 — 생성 메타데이터를 남기는 것과 같은 이유다.
+
+## 순서
+
+1. #4258 머지 (wp2에서 완료) → `dev` fetch → 내 브랜치 리베이스
+2. #4274(Zen 프리셋 안정화) CI green 확인 후 머지
+3. V4.1 전환 변경을 새 PR로 게시하고 CI green 확인 후 머지
+
+#4274를 먼저 머지하는 이유: 이미 리뷰가 끝났고 CI가 거의 다 통과했다. V4.1 변경과 같은 파일(`registry.ts`)을 건드리므로, 뒤에 올리는 쪽이 리베이스한다.
+
+## 머지 조건 (MAINTAINERS.md)
+
+- base `dev`
+- exact-head CI green — 머지 직전 `gh pr checks`로 확인하고 커밋 SHA와 함께 기록
+- 유지관리자 단독 통합 시 결정 근거를 남긴다
+- `main`/`preview` 승격과 릴리스는 이번 범위 밖
+
+## PR 본문에 반드시 들어갈 것
+
+- V4.1 전환 근거와 출처 링크
+- 조사 결과가 갈렸다는 사실과 어느 해석을 택했는지 (001 참조)
+- id 분기 이유: 네이티브 `deepseek-flash` vs 게이트웨이 `deepseek-v4.1-flash`
+- v4-pro 제거를 두 커밋으로 나눈 이유와, 벤더 호스팅 커밋만 되돌리는 방법
+- 생성 메타데이터를 손대지 않은 이유 (과거 사용량 원가 계산)
+- 전체 스위트를 로컬에서 돌리지 않았다는 사실
diff --git a/devlog/_plan/260911_devin_two_providers/001_plan.md b/devlog/_plan/260911_devin_two_providers/001_plan.md
new file mode 100644
index 0000000000..16a72b7d57
--- /dev/null
+++ b/devlog/_plan/260911_devin_two_providers/001_plan.md
@@ -0,0 +1,76 @@
+# 001 — Devin/Cognition as two providers
+
+Objective: opencodex gains two Devin-family providers.
+
+- `devin` — cloud-direct. Connect-RPC to Cognition's `exa.api_server_pb.ApiServerService`,
+  carried from PR #4078 (author @wtfsayo) onto current `dev` and hardened.
+- `devin-cli` — local. Spawns the Devin CLI and speaks Agent Client Protocol
+  (newline-delimited JSON-RPC on stdio), modeled on the user-supplied working
+  `server.mjs` proxy and the reference executor in `.tmp/openproxy-ref`.
+
+`.tmp/openproxy-ref` (quangdang46/openproxy) is read-only reference. No code or
+license-bearing text from it enters this repository.
+
+## Work phases
+
+| id | outcome |
+|---|---|
+| wp1 | Carry + harden the cloud-direct `devin` adapter on current `dev` |
+| wp2 | Live Cognition evidence (free signup + client download via aside), fold verified constants in |
+| wp3 | Second provider `devin-cli` over ACP stdio |
+| wp4 | Docs/locale parity, full gates, PR, merge into `dev` |
+
+## wp1 — what changes and why
+
+The carry itself is done: `git merge --squash pr4078` applied cleanly onto
+`9ea5759226`, the root-level test moved to its layout domain
+(`tests/providers/devin-adapter.test.ts`) with `scripts/test-layout/layout.json`
+and `tests/fixtures/test-layout-expected.json` updated, and the focused suites pass
+(36/36). Four independent reviewers audited the result. Their findings define wp1's
+diff:
+
+### 1. Tenant api-server routing (major, real runtime failure)
+
+`src/oauth/devin.ts` stores RegisterUser's `api_server_url` on the credential, but
+`src/adapters/devin.ts` always posts GetUserJwt / GetCascadeModelConfigs /
+GetChatMessage to `provider.baseUrl`, which `src/providers/registry.ts` hardcodes to
+`https://server.codeium.com`. EU and FedStart tenants return a different host
+(`eu.windsurf.com/_route/api_server`, `windsurf.fedstart.com/_route/api_server`), so
+those accounts log in and then send every call to the wrong server. GitHub Copilot
+already threads `credential.apiBaseUrl` through; Devin must do the same, falling back
+to the default host only when RegisterUser returned nothing.
+
+### 2. Portal/register override (major, real runtime failure)
+
+Login always signs in against `DEFAULT_REGION`. `src/oauth/devin/types.ts` documents
+a `--portal-url` override that nothing wires, so a non-US tenant never reaches its
+matching RegisterUser host. Honor the override and persist it next to the api-server
+URL on the credential.
+
+### 3. Model-id normalization (minor, degraded path)
+
+`src/adapters/devin.ts` has no dotted-to-hyphen map. With the live catalog missing we
+append `-medium` to the raw id, turning `swe-1.6` into `swe-1.6-medium`, which
+Cognition answers with an opaque `permission_denied`. Normalize `.` to `-` before
+lookup and suffix only ids that actually carry an effort segment.
+
+### 4. Docs/locale parity (major, deferred to wp4)
+
+English `providers.md` and `reference/adapters.md` gained `devin`; the seven locales
+(`ko ja zh-cn zh-tw fr ru tr`) still jump from `cursor` to `github-copilot` and from
+`cursor` to `azure-openai`. No test compares them, but AGENTS.md forbids a locale
+contradicting the English source. Both providers land in every locale in wp4, once
+the final surface is known.
+
+### 5. Auth and streaming findings
+
+Two reviewers (credential handling; streaming terminal/abort semantics) are still
+running. Their blockers and majors fold into this same wp1 diff before A closes.
+
+## Boundaries
+
+- No change to `src/router.ts`, `src/server/lifecycle.ts`, or
+  `src/server/responses/core.ts` reaching `src/lab/`.
+- No new CLI command, so `skills/ocx/` and `src/cli/capabilities.ts` stay as they are.
+- `devin` keeps `dashboardPreset: false` and stays out of the featured lists.
+- Security notes stay in `.tmp/`, never in `devlog/`.
diff --git a/devlog/_plan/260911_devin_two_providers/002_audit.md b/devlog/_plan/260911_devin_two_providers/002_audit.md
new file mode 100644
index 0000000000..257db1d2e1
--- /dev/null
+++ b/devlog/_plan/260911_devin_two_providers/002_audit.md
@@ -0,0 +1,69 @@
+# 002 — wp1 audit: folded reviewer findings
+
+Four independent reviewers (xai/grok-4.6, high effort) audited the carried commit
+`142c095673`. Three returned; the streaming reviewer is still running and its
+findings fold into this same cycle if they arrive before C. Verdicts below are mine
+after reading the cited code.
+
+## Accepted — blocker
+
+**Raw upstream bodies in auth error messages.** `register-user.ts:96,113` and
+`cloud-direct/auth.ts:99,126` copy the response body into `Error.message`. That
+message reaches CLI output, the adapter's `emit({ type: "error" })`, and
+`/api/logs`. A Connect error that echoes `firebase_id_token`, or a 200 whose
+`user_jwt` fails the shape regex, publishes a live credential; `redactSecretString`
+does not match a bare `eyJ…` JWT. Confirmed by reading both files. Fix: status plus
+allowlisted Connect code plus trace id, never the body.
+
+## Accepted — major
+
+1. **Tenant api-server routing.** `credential.apiBaseUrl` is written at login but
+   no call site reads it, and `store.ts:461` only persists Copilot origins, so an
+   EU/FedStart host is dropped on the next load anyway. Thread it through
+   `mintUserJwt`, the catalog fetch, and `streamChatEvents`, and teach the store to
+   persist a validated Devin origin.
+2. **Redirect following on credential POSTs.** Both credential POSTs use the default
+   `redirect: "follow"`, so a 307/308 forwards the Firebase token or the protobuf
+   `api_key` to an attacker-chosen `Location`. Set `redirect: "error"` and validate
+   the host the same way `validateCopilotApiBaseUrl` does.
+3. **Credential shape.** `refresh: ""` makes `detectOAuthWarning` report
+   `stale_credentials` for every Devin account from the moment of login, and
+   `refreshDevinToken` extends the expiry without contacting Cognition, so a revoked
+   key keeps looking valid. Use the durable-key house pattern: `refresh` carries the
+   key, expiry is effectively unbounded, and refresh throws so a 401 marks
+   `needsReauth`.
+4. **Paste parsing.** `loginDevin` posts the entire pasted string as
+   `firebase_id_token`. The on-screen value is a token, but a user who pastes the
+   callback URL instead sends a URL. Parse a fragment/query token out of a URL paste
+   and reject a paste that contains no token.
+5. **`clearCachedUserJwt` is never called.** The cached `user_jwt` (its payload
+   contains `api_key`) survives logout in process memory. Wire it into the Devin
+   logout path.
+
+## Accepted — minor
+
+6. `result.name` overwrites the JWT `email` with a display name, so reauth identity
+   comparison collides. Keep the email; the name is not an identity.
+7. `registerUser` does not receive `ctrl.signal`, so cancelling login does not abort
+   the exchange.
+8. No dotted-to-hyphen model-id map, so a degraded-path `swe-1.6` becomes
+   `swe-1.6-medium` and Cognition answers `permission_denied`.
+
+## Rejected / deferred
+
+- **Copying the reference's gRPC-web framing.** `.tmp/openproxy-ref` talks to
+  `LanguageServerService` over gRPC-web with a Bearer header; we talk to
+  `ApiServerService` over Connect-RPC with the key inside `Metadata`. They are two
+  different products. Adopting the reference's headers or field numbers would break
+  auth and proto decode. Reference value is the CLI/ACP executor, which is wp3.
+- **`defaultRefreshPolicy: "disabled"`.** Correct for a durable key; keep it.
+- **Docs/locale parity.** Real and required, but the final surface is not known until
+  `devin-cli` lands, so it is wp4.
+- **Dead plugin types** (`PersistedCredentials`, `syncedViaOpencodeAuth`). Removed
+  where they are genuinely unreferenced; not a leak either way.
+
+## Verification for this cycle
+
+`bun x tsc --noEmit`, the focused Devin/adapter/layout suites, `bun run privacy:scan`,
+plus new regression tests for: error messages that must not contain a token, redirect
+refusal, host allowlist rejection, tenant host threading, and the dotted model id.
diff --git a/devlog/_plan/260911_devin_two_providers/003_live_evidence.md b/devlog/_plan/260911_devin_two_providers/003_live_evidence.md
new file mode 100644
index 0000000000..19901478e1
--- /dev/null
+++ b/devlog/_plan/260911_devin_two_providers/003_live_evidence.md
@@ -0,0 +1,170 @@
+# 003 — wp2: live Cognition evidence
+
+A free Cognition account was created through the browser on 2026-09-12 and the
+shipped desktop client was downloaded. Everything below is measured, not inferred.
+
+## What the account looks like
+
+Devin Desktop 3.9.19 (`Devin-darwin-arm64-3.9.19.dmg`, 337 MB). Windsurf has been
+rebranded: `windsurf.com` now redirects to `devin.ai/desktop`, and the bundled
+extension still identifies itself as `publisher: codeium`, `name: windsurf`,
+`displayName: Devin`. `product.json` reports `windsurfVersion: 3.9.19` and
+`codeiumVersion: 1.48.2`.
+
+## Constants confirmed against the shipped client
+
+Read from `Devin.app/Contents/Resources/app/extensions/windsurf/dist/extension.js`:
+
+- Auth0 client id `3GUryQ7ldAeKEuD2obYnppsnmj58eP5u` — present verbatim. The
+  carried adapter's value is correct.
+- Hosts: `server.codeium.com`, `server-staging.codeium.com`,
+  `server-beta.codeium.com`, `register.windsurf.com`, `eu.windsurf.com/_route/api_server`,
+  `windsurf.fedstart.com/_route/api_server`, and the tenant template
+  `your-company.windsurf.com`. The allowlist in `src/oauth/devin/api-base.ts` was
+  widened to the two staging/beta hosts on this evidence.
+- Method names `RegisterUser`, `GetChatMessage` and `GetCascadeModelConfigs` all
+  appear as string literals.
+
+## What the live calls proved
+
+1. **The sign-in token is not a JWT.** A real sign-in returned a 47-character
+   `ott$<base64url>` one-time token, and RegisterUser exchanged it successfully.
+   The JWT-shape gate added during wp1 would have rejected every real login, so
+   `parseDevinAuthPaste` now checks for one opaque credential-shaped word instead
+   of a token format. The token is single-use: the second exchange of the same
+   value fails, which is why the probe needed a fresh sign-in.
+
+2. **The tenant-routing fix is load-bearing, not theoretical.** RegisterUser
+   returned `api_server_url: https://server.self-serve.windsurf.com` for an
+   ordinary free account — not `server.codeium.com`, which the registry hardcodes
+   and the carried adapter always used. Without wp1's change every free-tier
+   account would have sent its RPCs to a host it is not provisioned on.
+
+3. **The api_key and the catalog work.** `GetCascadeModelConfigs` against that
+   host returned 227 model uids. Exactly one is enabled on the free tier:
+   `swe-1-6-slow`. The site advertises "unlimited SWE-2"; the API does not agree,
+   which is worth knowing before anyone documents a model list.
+
+4. **`GetChatMessage` fails with `invalid_argument`.** Message is the opaque
+   "an internal error occurred (trace ID: …)". Client version strings `3.9.19`,
+   `2.0.0` and `1.48.2` in Metadata fields 2 and 7 all fail identically, so the
+   version pin is not the cause — the comment in `metadata.ts` claiming a version
+   mismatch produces exactly this error is no longer a sufficient explanation.
+   The version default was still moved to the shipped `3.9.19` with an
+   `OPENCODEX_DEVIN_CLIENT_VERSION` override, because `2.0.0` predates the rebrand
+   and nothing argues for keeping it.
+
+   This is the open item. The request encoding is being compared field by field
+   against the shipped bundle and against the two actively maintained references.
+
+## Ecosystem survey
+
+Twelve independent Windsurf/Cognition proxies were catalogued. The two that
+matter here:
+
+- `dwgx/WindsurfAPI` (~2975 stars, updated this week) uses the same
+  `server.codeium.com` `GetChatMessage` Connect-RPC path we do.
+- `rsvedant/opencode-windsurf-auth` (~70 stars) is a direct-cloud Connect-RPC
+  streaming client for an opencode plugin. Our carried files reference
+  `opencode auth login`, `syncedViaOpencodeAuth` and an
+  `opencode-windsurf-auth` CLI in `src/oauth/devin/types.ts`, so #4078 very
+  likely derives from it. Its license and the derivation are being checked; if
+  it is derived, attribution is required before this merges.
+
+`quangdang46/openproxy` talks to a different product (gRPC-web
+`LanguageServerService`), so it is a secondary reference only.
+
+## wp2 outcome: the cloud chat path stays unverified
+
+Every request-shape hypothesis was tried against the live account and none of
+them changed the trailer. In probe order: client version `3.9.19`, `2.0.0`,
+`1.48.2`; the Connect request frame sent uncompressed with
+`Connect-Content-Encoding` dropped; `Metadata` #31 filled with 732 hex
+characters; `GetChatMessageRequest` #2, #15 and #20 added and #22 dropped on the
+first turn; `ChatMessagePrompt` #1 `message_id` added; `Authorization: Basic`
+in both base64 and raw doubled-key forms; and both hosts. Same
+`invalid_argument: an internal error occurred` every time, with a fresh trace id.
+
+The model gate is provably fine. `swe-2-high` and `claude-sonnet-5-medium` are
+refused locally as disabled, and a bogus uid is refused as unlisted, so the
+failure is specific to `swe-1-6-slow` — the one model a free account has, and a
+"slow" lane at that.
+
+**Entitlement now outranks request shape as the explanation.** The site
+advertises "Slow Devin Cloud access with limited quotas" for free accounts, and a
+slow lane plausibly is not served by this RPC at all. #4078's author reported a
+live PONG on 2026-09-09 with the *original* field set, which is the deciding
+fact: shipping unverified wire changes would risk regressing an account that
+works today in exchange for no measured gain here. The whole experimental delta
+was reverted; only the wp1 hardening and the MIT notice remain.
+
+Confirming this needs a paid account or a captured working request. Neither is
+available in this session, so the cloud provider is not merge-ready and the
+adapter's own model gate is what stops a user hitting this blindly.
+
+## The chat path works. What was actually wrong.
+
+A paid account was obtained on 2026-09-12 and the entitlement hypothesis died
+immediately: all 229 catalogue models came back enabled, and `GetChatMessage`
+failed exactly as it had on the free account. The failure was never about the
+plan.
+
+Isolating it took one decisive move. The most actively maintained reference
+(`dwgx/WindsurfAPI`) is zero-dependency ESM, so its request builder can simply be
+imported. Building a turn with the reference builder and sending it through our
+own transport returned **HTTP 200** and a real Connect stream — which proved the
+transport, the headers and the credential were all fine, and put the fault in our
+request encoder. Diffing the two encoded messages field by field left exactly one
+difference: `CompletionConfiguration` (#8).
+
+    reference  #1=1 #2=8192 #3=128000 #5=double #7=40 #8=double
+    ours       #1=1 #2=64000 #3=32    #5=double #6=double #7=50 #8=double #11=double
+
+**#2 is the output cap and #3 is the context window; we had them swapped.** A
+caller asking for 32 output tokens wrote 32 into the context-window field, and
+Cognition answered with an opaque `invalid_argument: an internal error occurred`.
+That is why every account failed identically and why no amount of probing the
+transport helped. The reference's own comments record the same mis-tagging and
+the same re-calibration.
+
+A second, independent trap sat behind it: **a temperature of exactly 0 is
+refused** with the same opaque error. Deterministic output is the common case for
+coding clients, so it is clamped to the smallest accepted value rather than
+silently replaced with the service default.
+
+Three transport facts also had to be right together, and testing them one at a
+time is why they looked useless earlier:
+
+- the credential is the session token doubled and dash-joined in
+  `Authorization: Basic`, while the protobuf body keeps a single copy;
+- the request envelope is uncompressed;
+- `Metadata` #31 carries 732 hex characters, whose length the service checks and
+  whose value it does not.
+
+The metadata identity is also its own shape — seven fields, the optional
+`user_jwt`, and the fingerprint — not the desktop client's fuller telemetry set.
+
+### Verified
+
+Six combinations, two hosts by three models, all returning `PONG` with a finish
+reason and usage:
+
+| host | model | result |
+|---|---|---|
+| `server.codeium.com` | `swe-2-high` | PONG, stop, 476/36 |
+| `server.codeium.com` | `claude-sonnet-5-medium` | PONG, stop, 576/5 |
+| `server.codeium.com` | `gpt-5-6-sol-medium` | PONG, 394/6 |
+| `server.self-serve.windsurf.com` | `swe-2-high` | PONG, stop, 1/36 |
+| `server.self-serve.windsurf.com` | `claude-sonnet-5-medium` | PONG, stop, 576/5 |
+| `server.self-serve.windsurf.com` | `gpt-5-6-sol-medium` | PONG, 394/6 |
+
+The tag map is now pinned by a regression test that builds a request and asserts
+the field layout, so the swap cannot come back silently.
+
+### What this retracts
+
+The earlier conclusion in this document — that entitlement was the leading
+explanation and that the request shape had been ruled out — was wrong. The
+request shape was the whole problem; the probing that "ruled it out" changed one
+variable at a time against a broken `CompletionConfiguration` that no single
+variable could rescue.
diff --git a/devlog/_plan/260911_devin_two_providers/004_devin_cli_split.md b/devlog/_plan/260911_devin_two_providers/004_devin_cli_split.md
new file mode 100644
index 0000000000..f6a41bd7d0
--- /dev/null
+++ b/devlog/_plan/260911_devin_two_providers/004_devin_cli_split.md
@@ -0,0 +1,33 @@
+# 004 — wp5: splitting devin-cli out
+
+The wp4 audit recommended splitting, citing MAINTAINERS.md: a new canonical
+registry destination is a maintained promise, and when the evidence is incomplete
+the repository wants an inert directory row rather than a registry entry. The
+cloud `devin` provider cannot complete a turn on the account we can measure.
+`devin-cli` does not share that RPC.
+
+## What moved
+
+Branch `codex/260912-devin-cli-provider` from a freshly fetched `origin/dev`
+(`29d632ff25`). It carries `src/adapters/devin-cli/` and
+`tests/providers/devin-cli-adapter.test.ts` byte-identical, plus only the
+`devin-cli` hunks of the adapter registry, the provider registry, the routing
+behaviour table, the layout map and the membership fixture. Docs get the English
+provider row and adapters section and the provider row in all seven locales.
+
+The tool-conformance skip lists needed care: on the other branch they name both
+wires, and here only `devin-cli` exists, so naming a wire that is absent would
+have been a silent no-op rather than a skip.
+
+## What stayed
+
+Everything cloud-direct: `src/adapters/devin/`, `src/oauth/devin*`, the `devin`
+registry entry and its documentation, the MIT notice for the derived files, and
+this plan unit. PR #4285 keeps them.
+
+## Verification
+
+`bun x tsc --noEmit` clean; 76 focused tests pass; `privacy:scan` green. An
+independent audit of the split diff (21 files, +925/-5) found no cloud-provider
+leakage, agreeing registries, resolving imports, and a PR description that
+matches the code. Remote CI on the exact head is the suite gate.
diff --git a/devlog/_plan/260911_ocx_login_codex_routing/000_plan.md b/devlog/_plan/260911_ocx_login_codex_routing/000_plan.md
new file mode 100644
index 0000000000..f693dea604
--- /dev/null
+++ b/devlog/_plan/260911_ocx_login_codex_routing/000_plan.md
@@ -0,0 +1,136 @@
+# ocx login codex — route the Codex account names out of the provider wall
+
+## Summary for a reader
+
+`ocx login codex` is the first thing a person types when they want the proxy to
+talk to their ChatGPT/Codex account, and until now it answered with a usage list
+of roughly ninety provider ids that never contains the word `codex`. The
+capability was never missing — the Codex account pool has its own login at
+`ocx account login codex` — so the dead end was vocabulary, not function. This
+unit routes the three Codex spellings (`codex`, `chatgpt`, `openai`) from
+`ocx login` into that existing account-pool flow, and makes the usage wall,
+`ocx help` and the CLI registry entry name the route. Nothing about credential
+handling, the pool ledger, or the `/api/codex-auth` surface changes.
+
+## Loop spec
+
+- **Loop archetype**: satisfy-spec. One work-phase (wp1), one PABCD cycle.
+- **Trigger**: user asked why `ocx login` has no `codex`, then asked to add it
+  because people get confused, under `cxc-loop` with reviewer dispatch and a PR.
+- **Goal**: `ocx login codex|chatgpt|openai` performs the Codex account-pool
+  login; the provider wall and help text name that route; the docs stop
+  advertising the stale `ocx login chatgpt` form.
+- **Non-goals**: `isPublicOAuthProvider`/`listOAuthProviders` semantics and the
+  deliberate `chatgpt` exclusion from the generic `/api/oauth` surface; any
+  credential, token, refresh or `/api/codex-auth` behavior; `ocx logout`;
+  the GUI; every other CLI command.
+- **Verifier**: see the verifier reality table below.
+- **Stop condition**: the PR is open against `dev` with the template filled and
+  every criterion in the bound goalplan carries fresh captured evidence.
+- **Memory artifact**: this unit, plus the goalplan at
+  `.codexclaw/goalplans/opencodex-ship-ocx-login-codex-codex-chatgpt-acc/` and
+  the session ledger.
+- **Expected terminal outcomes**: DONE with the PR URL; NEEDS_HUMAN if the
+  requested `xai/grok-4.6` reviewer cannot be routed and the user must pick
+  another reviewer model; BLOCKED if the push or PR is refused.
+- **Escalation condition**: anything that would touch credential material, log
+  into a provider on the user's behalf, or merge/promote the PR. Main reclaims a
+  slice after two distinct agents fail its packet; moving a slice to a worker
+  requires a P-phase amendment.
+- **Resource bounds**: local repository writes only, plus one authorized push and
+  one PR creation against `lidge-jun/opencodex`. Reviewer dispatch is read-only.
+  No token or wall-clock budget was set by the user, so none is invented.
+
+## Why routing, not a pointer message
+
+`cxc-dev-uiux-design` UX-LAZY-01 orders the options: do nothing, delete, absorb,
+demote. "Print a nicer error naming `ocx account login codex`" is the *demote*
+answer — it still makes the user learn a second noun before they can log in.
+Absorbing is available here because the account flow already accepts the same
+argument shape, so the system can take the complexity instead of the user.
+UX-STATE-01 covers the failure mode that absorption introduces: the pool login
+runs inside the proxy, so it can fail when the proxy is down. That path already
+ends in `Proxy is not running. Start it with: ocx start`
+(`src/cli/runtime-api.ts:48`), which names its own recovery, so the routed
+command never dead-ends either.
+
+Destructive symmetry is deliberately NOT absorbed: `ocx logout codex` keeps its
+current behavior, because UX-LAZY-01 exempts destructive actions from magic
+defaults and removing a pool account is `ocx account remove openai <id> --yes`.
+
+## File change map
+
+| File | Change |
+|------|--------|
+| `src/cli/account-auth.ts` | Export `isCodexAccountLoginName()` over the existing private `CODEX_NAMES` set, so the three spellings keep one source of truth. |
+| `src/cli/dispatch.ts` | `login` runner: lazily import the predicate, and on a match call `handleAccountAuthCommand("login", argv, { findLiveProxy })` instead of `handleLogin`. Full argv is forwarded, so `--reauth`, `--id`, `--device`, `--code`, `--no-wait` and `--json` keep working. |
+| `src/oauth/login-cli.ts` | Extract `loginUsageMessage()` and add a first line naming the Codex route. `handleLogin` prints it. |
+| `src/cli/registry.ts` | `login` entry gains `details` naming the Codex route and its running-proxy precondition. |
+| `src/cli/help.ts` | Banner line for `ocx login` mentions `ocx login codex`. |
+| `tests/cli/cli-dispatch.test.ts` | New describe block: every spelling routes (incl. case/whitespace), flags survive, an unknown flag is still a usage error, the usage text names the route, and `listOAuthProviders()` still excludes `chatgpt`/`codex`. |
+| `docs-site/src/content/docs/guides/providers.md` + 7 locale mirrors | Replace the stale `ocx login chatgpt` line and its prose claim with the routed `ocx login codex` form. |
+
+Dependency order: predicate -> routing -> usage/help text -> tests -> docs. Each
+step is independently verifiable by `bun test tests/cli/cli-dispatch.test.ts`.
+
+## Field chain (PLAN-FIELD-CHAIN-01)
+
+No new type field or enum value is introduced. The only new value class is the
+set of routed names, and its chain is: creation = argv (`deps.args`), matching =
+`isCodexAccountLoginName` (`src/cli/account-auth.ts`), consumption =
+`handleAccountAuthCommand("login", ...)` -> `login()` -> `CODEX_NAMES.has`
+branch -> `/api/codex-auth/login`. Serialization/deserialization: N/A, the value
+never leaves the process as data. The pre-existing consumer
+`src/cli/model-selection-guidance.ts:3` maps `codex`/`chatgpt` to `openai`
+independently and is unaffected.
+
+## Verifier reality (PLAN-VERIFIER-REAL-01)
+
+| Command | Exit | Observes this change? |
+|---------|------|-----------------------|
+| `bun x tsc --noEmit` | 0 (run on the rebased branch head) | Yes — `tsconfig.json` includes `src` and `tests`, so both edited trees typecheck. |
+| `bun test tests/cli/cli-dispatch.test.ts` | 0, 43 pass (rebased head) | Yes — the file is the direct argument and imports `dispatchCommand`, `loginUsageMessage`, `isCodexAccountLoginName`. |
+| `bun test tests/cli/cli-registry.test.ts tests/cli/cli-help.test.ts` | 0, 29 pass | Yes — these cross-check `src/cli/help.ts` against `src/cli/registry.ts`, the two text surfaces edited here. |
+| `bun test tests/oauth/oauth-public-surface.test.ts` | to run in C | Yes — it owns the `chatgpt` public-surface exclusion this change must not reopen. |
+| `bun run test:changed` | to run in C | Partially — it follows Bun's module graph from the changed files; it does not observe the docs-site markdown. |
+| docs-site markdown | no gate | No. Nothing in build/typecheck/test reads `docs-site/` content for this claim, so the docs rows are **human review**, verified by `rg` for the stale string. |
+
+## Enforcement bypass (PLAN-BYPASS-NAMED-01)
+
+This unit adds no enforcement layer; it adds routing plus regression tests.
+Tier E1 (test suite), executing surface = `bun test` in CI and locally. Known
+bypass path: the routing lives in a dispatch runner, so any future caller that
+invokes `handleLogin()` directly bypasses it — `src/cli/dispatch.ts` is the only
+caller today (verified by grep) and the test asserts through `dispatchCommand`.
+Residual risk: a second entry point could reintroduce the wall without failing a
+test. Final layer: none. No wording was downgraded.
+
+## Accept criteria
+
+1. `ocx login codex`, `ocx login chatgpt`, `ocx login openai` reach the account
+   login. Activation scenario for the conditional path: with no live proxy
+   (`findLiveProxy` returning null), the command exits 1 and prints
+   `Proxy is not running. Start it with: ocx start`, which `handleLogin` would
+   never print. Observable effect proving the branch ran = that exact message.
+2. `ocx login codex --reauth --id <id>` reaches the same path (flags forwarded,
+   not dropped); `ocx login codex --nope` is still a usage error (exit 2).
+3. `loginUsageMessage()` names `ocx login codex`, and `listOAuthProviders()`
+   still excludes `chatgpt` and `codex`.
+4. `rg "ocx login chatgpt" docs-site` returns nothing.
+5. tsc and the focused suites above are green on the branch head.
+
+## Source-of-truth sync (SOT-SYNC-01)
+
+The user-facing source of truth for this surface is
+`docs-site/src/content/docs/guides/providers.md` (+ locales) and the CLI's own
+help/registry text; both are patched in this unit. `skills/ocx/` is generated
+from `src/cli/capabilities.ts`, which declares no `login` capability, so no
+surface-map regeneration is required — confirmed by grep before planning.
+
+## Architect consultation
+
+Recorded honestly: this is a C2 slice whose design question (route vs. pointer)
+is decided above from an owned skill rule, and the exposed `architect` role is
+dispatched for a reflection check on this written plan rather than a fresh design
+proposal. Any MISALIGNED finding is folded before A.
+
diff --git a/devlog/_plan/260911_ocx_login_codex_routing/010_audit_round1.md b/devlog/_plan/260911_ocx_login_codex_routing/010_audit_round1.md
new file mode 100644
index 0000000000..ef1e5d1f46
--- /dev/null
+++ b/devlog/_plan/260911_ocx_login_codex_routing/010_audit_round1.md
@@ -0,0 +1,77 @@
+# Audit round 1 — four independent agents on grok-4.6
+
+Dispatched from P with read-only packets (DISPATCH-TASK-01), each required to
+anchor every finding with `path:line` and a verbatim quote.
+
+| Agent | Lens | Verdict |
+|-------|------|---------|
+| `01a08fc7-0e6f` | execution correctness (argv, exit codes, ordering, bypass) | PASS, no findings |
+| `01a08fc7-0fa9` | security and boundary | PASS, 1 minor |
+| `01a08fc7-10fd` | repository conventions and test quality | PASS-WITH-FIXES, 2 major + 3 minor |
+| `01a08fc6-352e` | architect reflection on the written plan | MISALIGNED (read a pre-docs snapshot), 5 gaps |
+
+Synthesis verdict: **near-pass / GO-WITH-FIXES**. No blocker. Eight findings
+folded, one rebutted.
+
+## Folded
+
+1. **Secret echo on the newly reachable parser** (security, minor).
+   `src/cli/account-auth.ts` called `rejectArgs(args, USAGE)` with no
+   redaction, so an authorization code pasted as a bare positional was echoed
+   in `Unexpected argument(s): …`. That parser is now one word away from
+   `ocx login`, so it takes `{ redactValues: true }` — flag-shaped leftovers
+   still print, because a mistyped flag is what the message has to name.
+2. **The "flags survive" test could not fail** (test quality, major).
+   Dropping the flags at the dispatch seam leaves an empty leftover list, so
+   `rejectArgs` stays quiet and the liveness probe prints the same message the
+   test asserted. Replaced with a case that answers the probe with a live proxy,
+   stubs `fetch`, and reads the `/api/codex-auth/login` POST body. Proven red
+   by passing only `loginArgs[0]`.
+3. **Docs not in the commit** (conventions, major). They existed in the working
+   tree when the architect read the committed snapshot; they are in this unit's
+   commit now, across English, seven locales, and both CLI reference pages.
+4. **The wall was asserted in isolation** (minor). A case now spies
+   `process.exit` and asserts what `handleLogin` actually prints.
+5. **Nothing proved a non-Codex name stays off the account path** (minor). The
+   same case asserts the wall appears and `Proxy is not running` does not, so a
+   regression routing every name through the account command fails here.
+6. **No content assertion on the discoverability text** (minor). The registry
+   `details` for `login` are asserted directly.
+7. **No guard against a future key-provider id collision** (architect, minor).
+   `isKeyLoginProvider` is now asserted false for all three spellings and true
+   for `openai-apikey`.
+8. **`ocx login openai` lost its only pointer to `openai-apikey`** (architect,
+   minor). Routing `openai` means that user no longer sees the list that named
+   the platform-key provider, so the wall and the registry details name it.
+   The `?? 1` coalesce is also explained in place rather than left looking dead.
+
+## Rebutted
+
+**The `account-auth` import is unconditional on the `login` path.** Kept.
+Both the architect and the execution reviewer independently judged the cost
+acceptable: one CLI module load on a user-typed browser-login command, acyclic,
+no import-time IO, and none of the three files `AGENTS.md` protects
+(`src/router.ts`, `src/server/lifecycle.ts`, `src/server/responses/core.ts`) is
+on the path. Splitting the predicate into its own module to save it would
+contradict the single-source-of-truth decision for a cost that cannot be
+measured at a login prompt.
+
+## Explicitly cleared by review
+
+- `/api/codex-auth` behavior, token storage and refresh: unchanged.
+- The `chatgpt` exclusion from the generic public OAuth surface: still closed.
+  The routed call never reaches `/api/oauth/login`; `isPublicOAuthProvider` and
+  `listOAuthProviders` are untouched.
+- Name collisions: `openai` is `authKind: "forward"` in the provider registry
+  and was never a key login; the key id is `openai-apikey`. There is no
+  registry id `codex` or `chatgpt`.
+- `handleLogin` has no second caller, and the `login` registry entry declares
+  no alias that could reach the runner by another name.
+- Test placement needs no `layout.json` change: the cases were added to an
+  existing mapped file.
+
+The security reviewer also recorded that this diff sits on the `ocx login`
+authentication entrypoint and therefore falls under the `AGENTS.md` security
+review requirement, and that its review is that review — token storage, OAuth
+internals and the Codex auth routes are not modified by it.
+
diff --git a/devlog/_plan/260911_opencode_go_free_stabilization/000_plan.md b/devlog/_plan/260911_opencode_go_free_stabilization/000_plan.md
new file mode 100644
index 0000000000..55d56096a1
--- /dev/null
+++ b/devlog/_plan/260911_opencode_go_free_stabilization/000_plan.md
@@ -0,0 +1,38 @@
+# 260911 — opencode-go / zen / free 안정화
+
+OpenCode Zen 게이트웨이(go, zen, free)로 붙는 세 프리셋은 정적 `models:` 배열이 없고, 카탈로그가 `liveModels !== false`인 프로바이더를 live로 훑는다(`src/codex/catalog/provider-fetch.ts:440`). free만 `liveModels: true`를 명시하고(`src/providers/registry.ts:3049`) go/zen은 선언 없이 기본값으로 그 경로를 탄다. 반면 모델별 능력은 손으로 적은 정확-id 표에 묶여 있다. 그래서 새 모델 id가 게이트웨이에 뜨면 추론 강도 사다리, reasoning 재생, 비전 사이드카가 조용히 빈 채로 통과하고, 게이트웨이가 거절하는 요청 형태(특히 `response_format` json_schema)는 프리셋이 표현할 수단조차 없어 사용자가 직접 config를 고쳐야 한다. 이 유닛은 그 세 가지를 고친다: 프리셋이 그 거절을 표현할 수 있게 하고, 이미 증명된 프리셋 내부 불일치 두 건을 맞추고, 같은 종류의 드리프트를 다음번엔 테스트가 잡게 만든다. 바뀌는 사람은 Zen Go/Free를 쓰는 운영자다 — 지금 손으로 넣고 있는 설정이 기본값이 되고, 새 id가 들어와도 능력 표가 어긋나면 CI가 먼저 운다.
+
+연구 근거는 `001_issue_triage.md`(GitHub 트리아지), `002_cross_proxy_survey.md`(다른 프록시 교차 조사), `003_registry_gap_inventory.md`(코드 갭 인벤토리)에 있다.
+
+## 루프 스펙
+
+| 항목 | 내용 |
+| --- | --- |
+| Loop archetype | satisfy-spec. 열린 최적화가 아니라 확정된 갭 목록을 닫는다 |
+| Trigger | 사용자 요청: opencode go/free 이슈·PR을 묶어 안정화 PR을 올려라 |
+| Goal | dev를 base로 하는 PR 하나. 프리셋 능력 표현 + 내부 불일치 수정 + 회귀 가드 + 문서 동기화 |
+| Non-goals | `src/providers/command-code-efforts.ts`(열린 PR #4258 소유), 어댑터 와이어 동작 변경, 새 사용자 config 필드, 라이브 업스트림 프로브가 필요한 주장, 무키 free 티어 정책 변경 |
+| Verifier | `bun test tests/providers/provider-registry-parity.test.ts`, `bun test tests/providers/opencode-go-deepseek.test.ts`, `bun test tests/adapters/openai/openai-chat-hardening.test.ts`, `bun run typecheck`. 신설 가드는 수정 전 실패를 먼저 확인한다 |
+| Stop condition | PR이 dev를 base로 열리고 템플릿 3개 섹션이 채워진 시점 |
+| Memory artifact | `devlog/_plan/260911_opencode_go_free_stabilization/` |
+| Expected terminal outcomes | DONE = PR 게시 + 모든 검증 명령 green. BLOCKED = 업스트림 사실 확인이 필요해 근거 없이 시드할 수 없는 항목이 남을 때 |
+| Escalation condition | push 권한은 사용자가 이미 준 PR 게시로 한정한다. 머지·릴리스는 별도 승인. 라이브 프로브가 필요한 주장은 시드하지 않고 보고한다 |
+| Resource bounds | 도구: repo 읽기/쓰기, gh 읽기 + PR 생성, grok-4.6 서브에이전트. 쓰기 범위: `src/providers`, `src/types`, `tests/providers`, `docs-site`, 이 플랜 유닛. 벽시계: 사용자 세션 내 |
+
+## 작업 단계 지도 (의존 순서)
+
+| work-phase | 문서 | 내용 | 선행 |
+| --- | --- | --- | --- |
+| wp1 | 000-003 | 조사 종합과 로드맵 잠금 (docs only) | — |
+| wp2 | `010_phase1_preset_structured_output.md` | 프리셋이 `noStructuredOutputModels`를 표현하고 Zen 계열 DeepSeek에 시드 | wp1 |
+| wp3 | `020_phase2_preset_consistency_guard.md` | 프리셋 내부 불일치 G1·G2 수정과 parity 회귀 가드 | wp2 |
+| wp4 | `030_phase3_docs_and_pr.md` | docs-site 동기화와 PR 게시 | wp3 |
+
+goalplan의 wp3 제목은 초기 등록 시 "어댑터 전송 계층"이었다. 조사 결과 어댑터 와이어 결함은 이미 랜딩되었거나(`002`) 우리 구조상 발생하지 않아, 이 문서가 wp3의 실제 범위를 정합성·가드로 확정한다.
+
+## 자문과 감사 기록
+
+- **아키텍트**: grok-4.6. 첫 턴이 끊겨 한 번 재촉한 뒤 제안서를 받았다. 초안의 `noStructuredOutputModels` 시딩을 MISALIGNED로 반박했고 main이 수용했다(010 수정절).
+- **독립 감사 2레인**: grok-4.6과 상속 모델로 각각 한 번. 둘 다 `VERDICT: near-pass`. 지적은 010/020에 전부 반영했다.
+- **G2 불일치**: 두 리뷰어가 갈렸다. grok 레인은 "free 로스터에 paid id 증거가 없으니 넣지 말라", 상속 레인은 "같은 엔트리가 이미 #1043 근거로 공유 text-only 목록을 free에 통째로 싣는 선례가 있고(`registry.ts:3076`), 능력 표는 정확 일치라 없는 id면 무해하다"고 했다. main은 후자를 채택한다 — 능력 표는 카탈로그 로스터를 만들지 않으므로(`applyProviderConfigHints`는 이미 들어온 id만 장식한다) 없는 모델을 광고하지 않는다.
+- **실패한 레인**: GitHub 트리아지 레인과 첫 리뷰어 레인은 grok-4.6에서 최종 메시지 없이 턴이 끝나는 증상으로 각각 두 번 실패해 은퇴시켰고, 해당 작업은 main이 직접 수행했다.
diff --git a/devlog/_plan/260911_opencode_go_free_stabilization/001_issue_triage.md b/devlog/_plan/260911_opencode_go_free_stabilization/001_issue_triage.md
new file mode 100644
index 0000000000..aec84399c1
--- /dev/null
+++ b/devlog/_plan/260911_opencode_go_free_stabilization/001_issue_triage.md
@@ -0,0 +1,38 @@
+# 010 — opencode-go / zen / free 이슈·PR 트리아지
+
+수집일 2026-09-11. 소스: `gh issue list` / `gh pr list` (lidge-jun/opencodex), dev HEAD `b550d24e1`.
+
+## 열린 이슈 중 이 영역에 걸리는 것
+
+| 번호 | 제목 | 판정 | 근거 |
+| --- | --- | --- | --- |
+| #4253 | Command Code live model `deepseek/deepseek-v4.1-flash` advertises no reasoning efforts | 유효, 단 **인접 PR #4258이 담당** | PR #4258이 `src/providers/command-code-efforts.ts`에 v4.1-flash / Qwen3.8-Flash 행 추가, base dev, mergeable, CI green |
+
+열린 이슈 60건 중 opencode-go/zen/free 고유 결함은 없다. 이 영역의 최근 결함은 대부분 닫혔다.
+
+## 최근 닫힌 항목 (2026-08-15 이후, 32건 중 발췌)
+
+| 번호 | 종료 | 제목 요약 | 현재 의미 |
+| --- | --- | --- | --- |
+| #4172 | COMPLETED | Go sessionless 요청이 `x-opencode-session` 누락 | 랜딩됨. `src/providers/opencode-go-transport.ts` |
+| #4121 | COMPLETED | opencode-free: Zen이 세션 헤더 없는 요청 거부 | 랜딩됨. 무키 티어는 레지스트리 note로 차단 고지 |
+| #3945 / #3857 / #3378 | COMPLETED | Claude/Pi 경로의 Go 세션 친화성 | 랜딩됨 |
+| #3402 | COMPLETED | muse-spark via go: 미선언 클라이언트 툴이 서브에이전트 턴을 죽임 | 랜딩됨 |
+| #2442 | COMPLETED | Go Responses가 `search_content_types` 거부 | 랜딩됨 |
+| #2410 | COMPLETED | 신규 opencode-go 모델의 reasoningEfforts 누락 | **재발 구조 남음**: 030 참조 |
+| #2193 / #2194 / #2156 | COMPLETED | muse-spark 502 / 스트림 중단 | 랜딩됨 |
+| #1338 / #1415 | COMPLETED | Console Go 업스트림이 `response_format` json_schema를 400으로 거절 | **노브만 추가됨(#1424)**, 프리셋 시딩 없음 |
+
+## NOT_PLANNED로 닫혔지만 사실은 유효했던 것
+
+| 번호 | 사유 | 실제 상태 |
+| --- | --- | --- |
+| #3362 | `#3378`로 통합 | 메인테이너가 유효·재현 가능으로 확인. `indexed_web_access` 미제거. #3378에서 처리 |
+| #3344 | `#3378`로 통합 | 동일 |
+| #2480 / #2394 | 템플릿 미비로 봇이 자동 종료 | 재현 정보 없음. 정보부족으로 남김 |
+| #2484 | 템플릿 미비 | 보고자 스스로 `preserveResponsesReasoningContent` 미설정이 교란 변수였다고 정정 |
+
+## 남는 실물 갭
+
+1. **구조화 출력 400**: #1338/#1415는 per-model 옵트아웃 노브(#1424)로만 닫혔다. Zen Go DeepSeek에 대한 기본 시딩은 없어서 사용자가 직접 config를 고쳐야 한다. 2026-09-11 커뮤니티 제보(디시인사이드 ai_utilize)에서 실제로 사용자가 `noStructuredOutputModels`에 deepseek를 넣어 해결했다.
+2. **정확-id 표 드리프트**: #2410이 한 번 고쳐진 부류의 결함이 구조적으로 재발 가능하다. 030 참조.
diff --git a/devlog/_plan/260911_opencode_go_free_stabilization/002_cross_proxy_survey.md b/devlog/_plan/260911_opencode_go_free_stabilization/002_cross_proxy_survey.md
new file mode 100644
index 0000000000..828ff07253
--- /dev/null
+++ b/devlog/_plan/260911_opencode_go_free_stabilization/002_cross_proxy_survey.md
@@ -0,0 +1,37 @@
+# 020 — opencode zen/go를 커넥터로 붙이는 다른 프록시 교차 조사
+
+조사일 2026-09-11. 판정 기준: 해당 저장소 **소스/설정**에 `opencode.ai/zen` 또는 `zen/go/v1`이 실제로 있는지. README 스니펫만 있으면 unverified.
+
+## 지원 인벤토리
+
+| 프로젝트 | zen go 지원 근거 | 비고 |
+| --- | --- | --- |
+| musistudio/claude-code-router | `packages/core/src/agents/local-providers/opencode.ts`, 테스트가 `https://opencode.ai/zen/go/v1` 고정 | 세션 헤더 주입 구현 있음 |
+| Kiowx/opencode-cc | `OPENCODE_CC_UPSTREAM=https://opencode.ai/zen/go` | reasoning 캐시·thinking 정규화 구현 있음 |
+| kartikkabadi/opencode-go-proxy | `src/opencode_go_proxy/upstream.py` | 세션 헤더 미구현 |
+| tbosancheros39/opencode-thinking-fix | `proxy/proxy.js`, `proxy/core.js` | 라우트별 reasoning 키 분기 |
+| NousResearch/hermes-agent | `plugins/model-providers/opencode-zen/__init__.py` | thinking XOR effort 처리 |
+| cline/cline | `sdk/packages/llms/src/providers/providers.generated.ts` | 클라이언트 카탈로그 |
+| chatboxai/chatbox | `src/shared/providers/definitions/opencode-go.ts` | 모델별 엔드포인트 분기 |
+| openclaw/openclaw | first-class `opencode-go` | 카탈로그 드리프트 이슈 다수 |
+| sst/opencode (anomalyco/opencode) | 게이트웨이 본체 | 업스트림 결함의 출처 |
+
+**미지원으로 확인된 것** (`gh search code "opencode.ai/zen"` 빈 결과): router-for-me/CLIProxyAPI, BerriAI/litellm, songquanpeng/one-api, QuantumNous/new-api, oai2ollama. LiteLLM은 사용자 yaml에 `api_base: https://opencode.ai/zen/go/v1` + `drop_params: true`로 붙이는 방식이고 first-class 어댑터가 아니다.
+
+## 증상별 교차표 (opencodex 관점)
+
+| 증상 | 다른 프록시의 대응 | opencodex 현황 |
+| --- | --- | --- |
+| `MissingSessionID` 400 | CCR `upstream-header-sanitizer.ts:202-206`이 공식 Go 호스트에만 주입 | 이미 구현 (`src/providers/opencode-go-transport.ts`) |
+| tool-call 이어가기 reasoning 재생 | opencode-cc v1.2.5 `4ac61aa` | 이미 구현 (`preserveReasoningContentModels` + `src/responses/reasoning-replay-cache.ts`) |
+| compaction이 thinking을 버린 뒤 tool_use id로 회수 | opencode-cc v1.3.0 `internal/proxy/reasoning_cache.go` | 유사 캐시 존재. Chat 경로 커버리지는 **검증 필요** |
+| Kimi/Go에서 `thinking`과 `reasoning_effort` 동시 전송 시 "cannot specify both" | hermes `__init__.py:45-55`가 XOR 강제 | `src/adapters/openai-chat.ts:1500-1565`가 if-else로 하나만 선택 → **현재 구조상 동시 전송 없음** |
+| GLM `thinking.type=adaptive` + tools 400 | opencode-cc `b52b661`이 adaptive→auto | opencodex의 adaptive는 Anthropic 계열 전용. Go GLM chat 경로엔 해당 enum 미사용 |
+| glm-5.2가 `reasoning` 거부, `reasoning_content`만 수용 | thinking-fix 3.3.0 라우트별 키 | `reasoningWireFormat` 분기 존재. Go glm 계열 실제 수용 필드는 **unverified** |
+| 429 / Retry-After 없음 | ogp 백오프 재시도 | 이미 구현 (`src/providers/opencode-zen-rate-limit.ts`) |
+| 모델 id 드리프트 | sst/opencode `ba72a6f` 문서 id 교체, ogp가 2회 거절 시 카탈로그에서 숨김 | **갭**. 030 참조 |
+| `response_format` structured output 400 | 이 조사에서 외부 이슈 URL 미검출 | opencodex는 #1338/#1415 근거 보유 |
+
+## 결론
+
+외부 프록시가 이미 해결했고 opencodex에 없는 항목은, 재확인 결과 대부분 **이미 랜딩되어 있거나 우리 코드 구조상 발생하지 않는다.** 실제로 남는 교차 갭은 **모델 id 드리프트 대응** 하나이며, 이는 030의 정확-id 표 문제와 같은 뿌리다.
diff --git a/devlog/_plan/260911_opencode_go_free_stabilization/003_registry_gap_inventory.md b/devlog/_plan/260911_opencode_go_free_stabilization/003_registry_gap_inventory.md
new file mode 100644
index 0000000000..40b54b4ed7
--- /dev/null
+++ b/devlog/_plan/260911_opencode_go_free_stabilization/003_registry_gap_inventory.md
@@ -0,0 +1,41 @@
+# 030 — 세 프리셋의 정확-id 표 갭 인벤토리
+
+조사 대상 `src/providers/registry.ts` (opencode-go 1695-1791, opencode-zen 3016-3039, opencode-free 3042-3079).
+
+## 매칭 방식
+
+| 메커니즘 | 방식 | 비교 지점 |
+| --- | --- | --- |
+| `noVisionModels`, `noReasoningModels`, `thinkingToggleModels`, `thinkingBudgetModels`, `preserveReasoningContentModels`, sampling 목록 | 정확 일치 + colon-family(`gpt-oss`→`gpt-oss:120b`)만 예외 | `src/types/tools.ts:241` |
+| `modelReasoningEfforts`, `modelReasoningEffortMap`, `modelContextWindows`, `modelInputModalities` | 정확 own-property + colon-family + case-fold | `src/reasoning-effort.ts:115`, `src/codex/catalog/provider-fetch.ts:668,799` |
+| `noStructuredOutputModels` | 정확 `Array.includes`만 (colon-family도 없음) | `src/adapters/openai-chat.ts:142,1580` |
+| generated metadata | 정확 `r[0] === modelId` | `src/generated/model-metadata.ts:62` |
+
+`isDeepseekFlashModel`(`registry.ts:718`)은 substring이지만 **시드 루프 안에서만** 호출된다(`1754`, `3024`, `3065`). 런타임 조회 경로에는 쓰이지 않는다.
+
+## live 로스터와 시드의 비대칭
+
+세 프리셋 모두 정적 `models:` 배열이 없고 live `/models`로 로스터를 받는다(go/zen은 `liveModels` 미지정 → 기본 ON, free는 `liveModels: true`). 새 id는 카탈로그에는 들어오지만(`tests/providers/provider-live-models.test.ts:111-146`), `applyProviderConfigHints`는 **이미 시드된 맵만** 조회한다(`provider-fetch.ts:766,799`).
+
+결과: 시드에 없는 live id는 reasoning ladder, replay, vision sidecar, context window, wire default가 전부 빈 채로 통과한다. #2410이 한 번 수동으로 메운 것과 같은 종류의 구멍이다.
+
+## 증명된 내부 불일치 (upstream 사실 없이도 고칠 수 있는 것)
+
+| # | 불일치 | 앵커 | 영향 |
+| --- | --- | --- | --- |
+| G1 | opencode-go `thinkingBudgetModels`는 `THINKING_BUDGET_MODELS` 전체(Neuralwatt 전용 `qwen3.5-397b`, `qwen3.6-35b` 포함)인데, 같은 프리셋의 `modelReasoningEfforts`는 `OPENCODE_GO_THINKING_BUDGET_MODELS`(4개)만 spread한다 | `registry.ts:1755` vs `1771` | 해당 id가 live로 오면 budget 게이트는 켜지고 광고할 ladder는 없다 |
+| G2 | opencode-free는 같은 Zen 게이트웨이인데 paid DeepSeek id(`deepseek-v4-flash`, `deepseek-v4-pro`)를 reasoning/replay/noVision 어디에도 넣지 않는다. opencode-zen은 넣는다 | `registry.ts:3042-3079` vs `3016-3039` | free 로스터에 paid id가 등장하면 replay와 sidecar가 동시에 빠진다 |
+| G3 | `noStructuredOutputModels`는 `ProviderRegistryEntry` 타입(`160-353`)에 필드 자체가 없고 `providerConfigSeed`(`src/providers/derive.ts:218`)도 복사하지 않는다 | 위 | 프리셋이 이 옵트아웃을 표현할 수단이 아예 없다. 사용자 config로만 가능 |
+
+## parity 테스트가 강제하지 않는 것
+
+`tests/providers/provider-registry-parity.test.ts`는 알려진 id를 고정한다. 강제하지 **않는** 것:
+
+- live discovery로 들어온 미등록 id의 메타데이터 완전성
+- `noStructuredOutputModels`
+- go `thinkingBudgetModels` ↔ `modelReasoningEfforts` 정합 (G1)
+- zen ↔ free의 DeepSeek 처리 대칭 (G2). Zen은 DeepSeek ladder 케이스 배열에 아예 없다(`1385-1417`)
+
+## 이 유닛이 건드리지 않는 것
+
+`src/providers/command-code-efforts.ts` — 열린 PR #4258이 소유한다.
diff --git a/devlog/_plan/260911_opencode_go_free_stabilization/004_audit_rounds.md b/devlog/_plan/260911_opencode_go_free_stabilization/004_audit_rounds.md
new file mode 100644
index 0000000000..0f523c3e9b
--- /dev/null
+++ b/devlog/_plan/260911_opencode_go_free_stabilization/004_audit_rounds.md
@@ -0,0 +1,39 @@
+# 004 — 자문·감사 라운드 원문 기록
+
+## 라운드 1 — 아키텍트 (grok-4.6, 읽기 전용)
+
+판정: `ALIGNED if Main keeps the six slices below, keeps #4258 out of scope, and treats (i)/(ii) as the two judgment calls rather than as new subsystems. MISALIGNED if Main seeds noStructuredOutputModels as a registry field, invents live-id facts, or reopens landed transport/cache work.`
+
+핵심 반박 (main 수용):
+
+> Treat the community report as "users are disabling structured output entirely to escape a json_schema 400," not as proof that json_object is also rejected. … Live probe: impossible in this unit. Therefore we must not promote a full structured-output ban into the seed tables.
+
+main 처분: **수용.** 010을 `noJsonSchemaModels` 좁은 계약으로 다시 썼다. 다만 아키텍트가 제안한 "어댑터에서 provider id로 분기" 방식은 채택하지 않았다 — 이 저장소의 관용은 프로바이더 설정 필드가 어댑터 동작을 구동하는 것이고, 어댑터에 프로바이더 id를 박으면 새 결합이 생긴다.
+
+## 라운드 2 — 독립 감사 2레인
+
+두 레인 모두 `VERDICT: near-pass`.
+
+### 레인 A (상속 모델)
+
+- 배선: `선례가 noPenaltyModels로 완결돼 있다: registry.ts:323 → router.ts:351 병합 + router.ts:475 emit → openai-chat.ts:134`
+- 지적: `142는 delete 후 downgrade가 다시 넣지 않도록 else-if 순서를 명시해야 한다 — 계획에 순서 언급이 없다`
+- 지적: `라인 드리프트: 실제 게이트는 registry.ts:1773, 사다리는 1753(문서의 1755/1771 아님)`
+- 지적: `G2 — 판단이 약하다. 같은 엔트리 registry.ts:3076이 이미 "같은 게이트웨이·같은 로스터"를 근거로 free에 공유 text-only 목록 전체를 싣는 선례(#1043)다`
+- 지적: `000_plan 첫 문단 "세 프리셋은 로스터를 live /models로 받지만" — liveModels는 free만(registry.ts:3049)`
+
+### 레인 B (grok-4.6)
+
+- 지적: `010 상단 파일지도는 구설계(noStructuredOutputModels 시드)라 수정절과 충돌한다`
+- 반대 의견: `G2 타당. live 로스터에 paid id 증거가 없고, zen처럼 paid id를 넣으면 없는 모델을 광고한다`
+- 두 레인 공통: `#4258 교집합 없음`
+
+## 불일치 처분 — G2
+
+레인 B의 "없는 모델을 광고한다"는 부정확하다. 능력 표는 카탈로그 로스터를 만들지 않는다: `applyProviderConfigHints`는 이미 로스터로 들어온 id만 장식한다(`src/codex/catalog/provider-fetch.ts:766,799`). 로스터는 live `/models` 또는 정적 `models:` 배열에서 나오고, 세 프리셋은 정적 배열이 없다. 따라서 등장하지 않는 id를 능력 표에 시드해도 광고는 발생하지 않는다.
+
+레인 A의 선례가 더 강하다. main은 레인 A를 채택한다.
+
+## 실패한 레인 기록
+
+GitHub 트리아지 레인과 1차 리뷰어 레인은 grok-4.6에서 턴이 `completed` 로 끝나면서 최종 메시지가 비는 증상으로 각각 두 번 실패했다(중간 commentary만 남음). 은퇴시키고 해당 작업은 main이 직접 수행했다. 같은 모델의 아키텍트·감사 레인은 한 번 재촉 후 정상 산출했으므로 모델 전면 배제는 하지 않았다.
diff --git a/devlog/_plan/260911_opencode_go_free_stabilization/010_phase1_preset_structured_output.md b/devlog/_plan/260911_opencode_go_free_stabilization/010_phase1_preset_structured_output.md
new file mode 100644
index 0000000000..c688f9b51f
--- /dev/null
+++ b/devlog/_plan/260911_opencode_go_free_stabilization/010_phase1_preset_structured_output.md
@@ -0,0 +1,103 @@
+# 010 — wp2: 프리셋이 구조화 출력 옵트아웃을 표현하게 한다
+
+## 왜
+
+`noStructuredOutputModels`는 #1424로 들어왔지만 사용자 config / management API 전용이다. `ProviderRegistryEntry`에 필드 자체가 없어서(`src/providers/registry.ts:160-353`) 어떤 프리셋도 "이 게이트웨이의 이 모델은 `response_format`을 거절한다"를 표현할 수 없다. 그래서 Zen Go에서 DeepSeek를 쓰는 운영자는 매번 손으로 config를 고친다(#1338, #1415, 2026-09-11 커뮤니티 제보).
+
+## wp2 P 재검증 (2026-09-11, 사이클 진입 시)
+
+문서가 지목한 편집 지점을 현재 트리에서 전부 다시 확인했다. 드리프트 없음.
+
+| 지점 | 현재 내용 |
+| --- | --- |
+| `src/types/provider.ts:643` | `noStructuredOutputModels?: string[];` 선언과 계약 주석 |
+| `src/providers/registry.ts:319-323` | `noVisionModels`…`noPenaltyModels` 선언 블록 |
+| `src/router.ts:351` | `const noPenaltyModels = mergeStringArray(registryEntry.noPenaltyModels, provider.noPenaltyModels);` |
+| `src/router.ts:475` | `...(noPenaltyModels ? { noPenaltyModels } : {}),` |
+| `src/adapters/openai-chat.ts:142` | `if (provider.noStructuredOutputModels?.includes(modelId)) delete body.response_format;` |
+| `src/adapters/openai-chat.ts:1580` | 번역 경로의 `if (!provider.noStructuredOutputModels?.includes(parsed.modelId)) { … }` |
+
+추가로 발견한 선례: `registry.ts:315`의 `directReasoningEffortModels`가 `registry-only and is never persisted as user config`라고 명시한다. 즉 레지스트리 전용 필드는 이 저장소에 이미 있는 범주다. 새 필드도 같은 범주로 두되, 사용자가 config에 직접 적어도 검증을 통과하도록 zod 스키마에는 넣는다.
+
+## 선례
+
+`noPenaltyModels`가 같은 배선을 이미 완결해 두었다: 선언 `src/providers/registry.ts:323` → 병합 `src/router.ts:351` → emit `src/router.ts:475` → 소비 `src/adapters/openai-chat.ts:134`. 새 필드는 이 네 지점을 그대로 따른다. 아래 "배선 경로" 표가 확정 파일 지도다.
+
+## 설계 수정 (아키텍트 반박 수용, 2026-09-11)
+
+초안은 `noStructuredOutputModels`를 세 프리셋에 그대로 시드하려 했다. 독립 아키텍트 자문이 이를 반박했고 main이 수용한다.
+
+반박 요지: 확인된 400은 `json_schema` **타입** 한정이다(`This response_format type is unavailable now`). 그런데 이 노브의 계약은 "`response_format` 필드를 통째로 생략"이라, 시드하면 `json_object`를 쓰던 클라이언트까지 같이 죽는다. 커뮤니티 제보는 운영자가 고른 무딘 킬스위치이지 "json_object도 거절된다"는 증거가 아니다. 그걸 기본값으로 올리면 앞으로 json_object가 실제로 거절되는지 여부를 관측할 신호까지 덮어버린다.
+
+수정된 설계: **확인된 사실만 표현하는 좁은 필드를 새로 만든다.**
+
+`noJsonSchemaModels` — "이 모델은 `response_format` `json_schema`를 거절한다. `json_object`에 대해서는 아무 주장도 하지 않는다."
+
+동작:
+
+| 요청 | 시드된 모델 | 시드되지 않은 모델 |
+| --- | --- | --- |
+| `json_schema` | `{"type":"json_object"}`로 낮춰 보낸다 | 그대로 `json_schema` |
+| `json_object` | 그대로 | 그대로 |
+| 사용자가 `noStructuredOutputModels`에 넣음 | 기존대로 필드 전체 생략(우선한다) | 동일 |
+
+낮추기를 택한 이유: 클라이언트가 원한 건 JSON이다. 필드를 지우면 산문이 돌아오고, `json_object`로 낮추면 최소한 JSON이 온다. Zen Go가 `json_object`를 수용하는지는 **unverified**이지만, 거절한다면 400이 다시 뜨고 그건 새로운 검증된 사실이 되어 시드를 넓힐 근거가 된다. 킬스위치로 덮으면 그 신호가 사라진다.
+
+## 시드 내용
+
+```ts
+// opencode-go
+noJsonSchemaModels: [...DEEPSEEK_THINKING_MODELS],
+// opencode-zen
+noJsonSchemaModels: [...DEEPSEEK_THINKING_MODELS, ...OPENCODE_FREE_DEEPSEEK_MODELS],
+// opencode-free
+noJsonSchemaModels: [...OPENCODE_FREE_DEEPSEEK_MODELS],
+```
+
+매칭은 기존 목록과 같은 정확 일치다. `deepseek-v4.1-flash` 같은 신규 id는 걸리지 않는다 — 의도적이다. 게이트웨이가 그 id를 서빙한다는 근거가 없다.
+
+## 배선 경로 (최소 경로를 택한다)
+
+라우터는 레지스트리 엔트리와 사용자 config를 요청 시점에 병합한다(`src/router.ts:346-358`의 `mergeStringArray`, `471-482`의 emit). 따라서 프리셋 값은 `providerConfigSeed`로 config.json에 **영속시키지 않아도** 요청 경로에 도달한다. 새 사용자 설정 화면이나 management PATCH는 이번 범위가 아니다.
+
+| 파일 | 성격 | 내용 |
+| --- | --- | --- |
+| `src/types/provider.ts` | MODIFY | `noStructuredOutputModels`(`639-643`) 바로 아래에 `noJsonSchemaModels?: string[]` + 계약 주석 |
+| `src/providers/registry.ts` | MODIFY | `ProviderRegistryEntry`에 같은 필드(`321` 부근), 세 프리셋에 시드 |
+| `src/router.ts` | MODIFY | `mergeStringArray` 한 줄 + emit 한 줄 |
+| `src/config.ts` | MODIFY | zod 스키마에 한 줄(`622` 패턴) — 사용자가 손으로 넣어도 검증을 통과하게 |
+| `src/adapters/openai-chat.ts` | MODIFY | `142`(네이티브 패스스루)와 `1580`(번역 경로) 두 지점 모두에 낮추기 분기 |
+| `tests/adapters/openai/openai-chat-hardening.test.ts` | MODIFY | 낮추기 동작과 경계 |
+| `tests/providers/provider-registry-parity.test.ts` | MODIFY | 세 프리셋 시드 고정 |
+
+## 수용 기준
+
+1. `routeModel`을 거쳐 materialize한 opencode-go 프로바이더가 `noJsonSchemaModels`에 DeepSeek 두 id를 갖는다.
+2. 같은 프로바이더로 `deepseek-v4-flash` + `textFormat: json_schema` 요청을 만들면 직렬화된 `body.response_format`이 `{"type":"json_object"}`다. 활성 시나리오: 번역 경로는 `buildOpenAIChatRequest`, 네이티브 경로는 `buildOpenAIChatPassthroughRequest`에 각각 넣고 결과 본문을 읽는다.
+3. 같은 프로바이더로 `glm-5.3`(시드에 없음) + json_schema면 `response_format.type`이 `json_schema`로 **남는다** — 정확 일치 경계가 살아 있다는 반대 증거.
+4. 시드된 모델 + `json_object` 요청은 그대로 `json_object`다 — 낮추기가 json_object를 건드리지 않는다는 반대 증거.
+5. 같은 모델이 `noStructuredOutputModels`에도 있으면 `response_format`이 아예 없다 — 킬스위치 우선순위.
+
+### 분기 순서와 누락 지점 (wp2 감사 반영)
+
+- 패스스루(`142`): 킬스위치가 `delete body.response_format`을 먼저 실행하므로, 그 뒤의 낮추기는 `body.response_format?.type === "json_schema"`를 조건으로 두면 자동으로 발화하지 않는다. 감사 지적대로 `else if`는 맞지만 실질적으로 무의미하므로, 조건에 타입 검사를 넣고 킬스위치 우선임을 주석으로 남긴다. `.includes` 정확 일치는 유지한다.
+- 번역 경로(`1580`): 킬스위치 게이트가 json_object/json_schema 두 분기를 함께 감싸므로, 낮추기는 json_schema 분기 **안**에 둔다.
+- **config 검증은 선택이 아니다**: provider 스키마는 `.passthrough()`다. zod 검증을 빼면 사용자가 배열 대신 문자열을 넣어도 통과하고, `.includes()`가 부분 일치로 오작동한다.
+- **관리 API 왕복 누락**(감사가 새로 찾음): `src/server/auth-cors.ts`의 검증기(`711` 패턴)와 `PROVIDER_CONFIG_FIELD_POLICY`(`868` 부근), `src/server/management/provider-routes.ts`의 PATCH 처리(`563` 패턴)와 DTO(`732` 부근)에 필드를 넣지 않으면, 대시보드 raw 에디터 왕복에서 값이 거부되거나 사라진다. `noStructuredOutputModels`와 동일하게 네 지점을 모두 추가한다.
+- **처분 보류**: 스키마 계약이 조용히 free-form JSON으로 강등되는 것을 debug 로그로 남기라는 권고는 이번 범위에서 채택하지 않는다. 요청 본문 로깅 금지 규칙과 인접해 별도 판단이 필요하고, 필드 계약 주석과 PR 본문에 명시하는 것으로 대체한다. 후속 후보로 남긴다.
+- **건드리지 말 것**: parity 테스트가 opencode-go `noVisionModels`를 리터럴 배열로 고정한다. 이번 슬라이스는 그 필드를 수정하지 않는다.
+
+## 검증
+
+```
+bun test tests/providers/provider-registry-parity.test.ts
+bun test tests/providers/opencode-go-deepseek.test.ts
+bun test tests/adapters/openai/openai-chat-hardening.test.ts
+bun run typecheck
+```
+
+## 리스크
+
+- Zen Go가 `json_object`도 거절하면 낮추기는 400을 막지 못한다. 그건 감추지 않고 드러내는 선택이며, 그때는 검증된 사실로 `noStructuredOutputModels` 쪽으로 넓히면 된다.
+- 스키마를 요구한 클라이언트가 느슨한 JSON을 받는다. 필드를 지워 산문을 받는 기존 대안보다 낫고, 두 지점 모두 테스트로 고정한다.
+- 새 필드가 라우터 병합 목록에서 빠지면 프리셋 값이 요청에 도달하지 않는다. 수용 기준 1이 이걸 직접 관측한다.
diff --git a/devlog/_plan/260911_opencode_go_free_stabilization/020_phase2_preset_consistency_guard.md b/devlog/_plan/260911_opencode_go_free_stabilization/020_phase2_preset_consistency_guard.md
new file mode 100644
index 0000000000..db570faab0
--- /dev/null
+++ b/devlog/_plan/260911_opencode_go_free_stabilization/020_phase2_preset_consistency_guard.md
@@ -0,0 +1,65 @@
+# 020 — wp3: 프리셋 내부 불일치 수정과 회귀 가드
+
+## G1 — opencode-go의 thinking budget 게이트와 사다리가 어긋난다
+
+`registry.ts:1773`이 `thinkingBudgetModels: THINKING_BUDGET_MODELS`(6개, Neuralwatt 전용 `qwen3.5-397b`·`qwen3.6-35b` 포함)인데, 같은 프리셋의 `modelReasoningEfforts`(`1753` 부근의 spread)는 `OPENCODE_GO_THINKING_BUDGET_MODELS`(4개)만 넣는다. Go 로스터에 397b가 등장하면 어댑터는 `thinking_budget` 경로를 타는데(`src/adapters/openai-chat.ts:1539`) 카탈로그가 광고할 사다리는 없다.
+
+실행 근거(`.tmp/preset-probe.ts`로 레지스트리를 직접 로드):
+
+```
+thinkingBudgetModels: ["qwen3.5-397b","qwen3.6-35b","qwen3.5-plus","qwen3.6-plus","qwen3.7-max","qwen3.7-plus"]
+budget ids missing from ladder: ["qwen3.5-397b","qwen3.6-35b"]
+```
+
+감사 확인: 이 6원소를 equality로 고정한 테스트는 없다. `qwen3.5-397b`를 고정하는 건 neuralwatt 경로뿐이다(`tests/codex-integration/reasoning-effort.test.ts:875`, parity `356-376`).
+
+변경: `thinkingBudgetModels: OPENCODE_GO_THINKING_BUDGET_MODELS`.
+
+수용 기준: opencode-go 레지스트리 엔트리의 `thinkingBudgetModels`가 `modelReasoningEfforts`에 사다리를 가진 id의 부분집합이다. 활성 시나리오: parity 테스트가 두 컬렉션을 직접 비교한다.
+
+## G2 — opencode-free가 같은 게이트웨이인데 DeepSeek 처리가 비대칭이다
+
+opencode-zen(`3016-3039`)은 `DEEPSEEK_THINKING_MODELS` + `OPENCODE_FREE_DEEPSEEK_MODELS`를 reasoning/replay/noVision에 넣는다. opencode-free(`3042-3079`)는 `-free` id만 넣는다. free는 `liveModels: true`이고 같은 `opencode.ai/zen/v1` 게이트웨이다.
+
+실행 근거:
+
+```
+zen  preserveReasoningContentModels: ["deepseek-v4-pro","deepseek-v4-flash","deepseek-v4-flash-free"]
+free preserveReasoningContentModels: ["deepseek-v4-flash-free"]
+zen  noVisionModels: [... text-only 6 ..., "deepseek-v4-pro", "deepseek-v4-flash"]
+free noVisionModels: [... text-only 6 ...]
+```
+
+판단(감사 후 변경): **zen과 동일한 id를 free에도 싣는다.** 초안은 "free 로스터에 paid id 증거가 없으니 넣지 않는다"였고 grok 리뷰어도 같은 의견이었지만, 상속 모델 리뷰어가 같은 엔트리의 선례를 들어 반박했고 그쪽이 맞다:
+
+- free는 이미 zen과 공유하는 text-only 목록 전체를 "같은 게이트웨이·같은 로스터"라는 근거로 싣는다(`registry.ts:3076`, #1043).
+- 능력 표는 카탈로그 로스터를 만들지 않는다. `applyProviderConfigHints`는 이미 들어온 id만 장식하므로(`src/codex/catalog/provider-fetch.ts:766,799`), 등장하지 않는 id를 시드해도 아무것도 광고되지 않는다. 무해하고, 등장하면 정확하다.
+- "상수에서 부분집합 파생"은 필터가 여전히 수작업이라 드리프트를 구조적으로 막지 못한다.
+
+변경: free의 `modelReasoningEfforts` / `modelReasoningEffortMap` / `preserveReasoningContentModels` / `noVisionModels`가 zen과 같은 DeepSeek 집합을 쓰도록 같은 상수에서 파생시킨다.
+
+수용 기준: free와 zen의 DeepSeek 관련 목록이 같은 집합을 갖는다. 반대 증거로, zen 전용이 아닌 free 고유 항목(text-only 무료 id)은 그대로 남는다.
+
+## 회귀 가드
+
+`tests/providers/provider-registry-parity.test.ts`에 추가:
+
+1. **Go budget ⊆ ladder**: `thinkingBudgetModels`의 모든 id가 `modelReasoningEfforts`에 키를 가진다.
+2. **Zen 계열 DeepSeek 대칭**: go/zen/free 각각에서, `modelReasoningEfforts`에 DeepSeek id가 있으면 `preserveReasoningContentModels`에도 있다. (#78/#950 계열 400의 구조적 방지)
+3. **구조화 출력 시드 고정**: wp2가 넣은 세 프리셋의 시드 배열을 그대로 고정한다.
+
+세 가드 모두 수정 전 코드에서 먼저 실패시켜 red-green을 확인한다. 특히 1번은 현재 코드에서 `qwen3.5-397b`로 실패해야 한다 — 실패하지 않으면 가드가 무의미하다는 뜻이므로 가드를 다시 쓴다.
+
+## 검증
+
+```
+bun test tests/providers/provider-registry-parity.test.ts
+bun test tests/providers/opencode-zen-deepseek-reasoning.test.ts
+bun test tests/providers/opencode-free-provider.test.ts
+bun test tests/codex-integration/catalog-go-exact-efforts.test.ts
+```
+
+## 리스크
+
+- `thinkingBudgetModels` 축소가 Go에서 397b를 실제로 쓰는 사용자에게 영향? 해당 id는 Go `modelReasoningEfforts`에 없어서 지금도 사다리가 없다. 축소는 광고되지 않던 경로를 끄는 것이다.
+- parity 테스트는 배열 equality를 쓰는 곳이 있어(`73-80`) 시드 변경 시 같이 갱신해야 한다.
diff --git a/devlog/_plan/260911_opencode_go_free_stabilization/030_phase3_docs_and_pr.md b/devlog/_plan/260911_opencode_go_free_stabilization/030_phase3_docs_and_pr.md
new file mode 100644
index 0000000000..6285398fe6
--- /dev/null
+++ b/devlog/_plan/260911_opencode_go_free_stabilization/030_phase3_docs_and_pr.md
@@ -0,0 +1,30 @@
+# 030 — wp4: 문서 동기화와 PR 게시
+
+## 문서
+
+`noStructuredOutputModels`는 이미 `docs-site/src/content/docs/reference/configuration/providers.md`와 각 로케일에 설명이 있다. 이번 변경은 그 옆에 **새 필드 `noJsonSchemaModels`** 를 추가하고, opencode go/zen/free 프리셋이 이를 기본으로 싣는다는 사실을 적는다.
+
+| 파일 | 변경 |
+| --- | --- |
+| `docs-site/src/content/docs/reference/configuration/providers.md` | `noStructuredOutputModels` 항목 바로 뒤에 `noJsonSchemaModels` 항목 추가: json_schema만 json_object로 낮추고 json_object는 건드리지 않는다, 두 필드가 함께 있으면 `noStructuredOutputModels`가 우선한다, opencode go/zen/free 프리셋이 Zen 게이트웨이의 DeepSeek id에 기본 시드한다 |
+| `docs-site/src/content/docs/ko|ja|fr|ru|tr|zh-cn|zh-tw/reference/configuration/providers.md` | 같은 항목의 로케일 번역. 영문 원문과 모순되지 않게 유지 |
+
+로케일 파일이 영문과 구조가 다르면 해당 위치에만 맞춰 넣고, 번역이 불가능한 항목은 영문 문장을 그대로 두지 않는다.
+
+## PR
+
+- base `dev`, head `codex/260911-opencode-go-free-stabilization`
+- 템플릿 3개 섹션(Summary / Verification / Checklist) 전부 채운다
+- 본문에 반드시 포함: 닫는 이슈가 아니라 **묶음의 근거**(#1338, #1415, #1424, #2410), Zen Go의 `json_object` 수용 여부가 unverified라는 점과 그래서 킬스위치 대신 낮추기를 택한 이유, 라이브 프로브 불가로 시드하지 않은 항목(`deepseek-v4.1-flash`), PR #4258과의 비충돌(파일 교집합 없음)
+- `gui` 단어를 제목/본문에 쓰지 않는다(스크린샷 게이트 유발)
+- `Closes #`는 쓰지 않는다. 이 PR이 단독으로 닫는 열린 이슈는 없다
+
+## 검증
+
+```
+bun run typecheck
+bun run test
+bun run privacy:scan
+```
+
+PR을 review-ready로 올리기 전 전체 스위트를 돌린다(AGENTS.md PR-ready 게이트).
diff --git a/devlog/_plan/260911_opencode_go_free_stabilization/031_wp4_outcome.md b/devlog/_plan/260911_opencode_go_free_stabilization/031_wp4_outcome.md
new file mode 100644
index 0000000000..134c115214
--- /dev/null
+++ b/devlog/_plan/260911_opencode_go_free_stabilization/031_wp4_outcome.md
@@ -0,0 +1,31 @@
+# 031 — wp4 결과
+
+PR: <https://github.com/lidge-jun/opencodex/pull/4274> (base `dev`, head `codex/260911-opencode-go-free-stabilization`)
+
+## 최종 변경 범위
+
+| 커밋 | 내용 |
+| --- | --- |
+| `d0e4e5218` | `noJsonSchemaModels` 계약: 타입, 레지스트리 필드와 세 프리셋 시드, 라우터 병합/emit, config zod + superRefine, auth-cors 검증기 + 필드 정책, provider-routes PATCH + DTO, 어댑터 두 와이어의 낮추기, 회귀 테스트 10건 |
+| `58fe2b07f` | opencode-go `thinkingBudgetModels` 를 Go 전용 목록으로 좁힘 + 구조 가드 2종 |
+| `4ed244bca` | docs-site en + 7개 로케일 |
+| `ecb6a14a4` | 프랑스어 문서의 기존 행 조판 원복 (감사 지적) |
+
+## 검증
+
+포커스 스위트만 돌렸다. 사용자가 전체 스위트를 명시적으로 금지했고, 푸시는 `--no-verify` 로 지시했다.
+
+- 어댑터/프리셋 155 pass / 0 fail
+- parity + 카탈로그 효율 97 pass / 0 fail
+- config/management 637 pass / 0 fail
+- `bun run typecheck` exit 0, `bun run privacy:scan` 통과
+- red-green: 세 가드 모두 수정 전 실패를 직접 확인
+
+전체 스위트는 CI 에 맡겼다. 이전에 로컬에서 한 번 시도했을 때 879초가 걸렸고 exit 1 로 끝났는데, 출력이 잘려 어떤 파일이 실패했는지는 확인하지 못했다. 이 브랜치가 원인인지도 확인되지 않았다 — 재확인은 CI 결과로 대체한다.
+
+## 남긴 것
+
+- `deepseek-v4.1-flash` 는 시드하지 않았다. 게이트웨이가 서빙한다는 근거가 트리에 없다.
+- `json_object` 수용 여부는 미검증이다. DeepSeek 계열이 프롬프트에 `json` 문자열을 요구하는 구현이면 낮추기가 400 대신 빈 응답이 될 수 있다. PR 본문에 후속 조건으로 명시했다.
+- 구조 가드는 세 프리셋 id 를 루프로 돈다. 네 번째 Zen 계열 프리셋이 생기면 목록에 추가해야 한다.
+- 스키마 강등을 관측 가능한 신호로 남기는 건(요청 본문 로깅 금지와 인접) 후속 판단으로 미뤘다.
diff --git a/devlog/_plan/260911_r2_merge_train/000_plan.md b/devlog/_plan/260911_r2_merge_train/000_plan.md
new file mode 100644
index 0000000000..48fc4be82d
--- /dev/null
+++ b/devlog/_plan/260911_r2_merge_train/000_plan.md
@@ -0,0 +1,97 @@
+# 260911 R2 merge train — land #4244, #4248, #4246, #4247 on dev
+
+## Objective
+
+Four open PRs authored on 2026-09-11 (`codex/260911-r2-*`) are each 65 commits behind
+`origin/dev` at `18e553a52`. All four were green at their pre-rebase heads, and two of
+them have since gone `CONFLICTING`. This unit rebases each onto the current `dev`,
+re-proves it, and merges it — one at a time, as a serialized train.
+
+The train is serialized rather than parallel for one concrete reason: #4246 and #4248
+both append to `scripts/test-layout/layout.json` and
+`tests/fixtures/test-layout-expected.json`. Those two files are sorted registries that
+`tests/test-layout.test.ts` and `tests/test-layout-tooling.test.ts` enforce, so two
+branches that each add one line to the same sorted block will conflict textually no
+matter how trivially compatible the changes are. Rebasing the second one only after the
+first is already on `dev` turns a two-sided conflict into a one-sided replay.
+
+## Scope
+
+In scope: the files already touched by the four branches, their conflict resolutions
+against `dev`, and this planning unit.
+
+Out of scope: every other open PR (#4256, #4258, #4259 and all third-party PRs), any new
+feature work, any promotion of `main` or `preview`, any force-push to a protected
+branch, and any edit to another author's branch.
+
+## Authority
+
+The user explicitly authorized rebase, force-push to these four PR branches, and merge
+into `dev` in this session. `MAINTAINERS.md` permits a maintainer with `maintain` or
+`admin` access to integrate their own PR into `dev` through a PR without a second
+approval, provided the decision and exact-head CI evidence are recorded. This document
+plus the per-phase records below are that record.
+
+That authority stops at `dev`. It does not cover `main`/`preview` promotion, releases,
+branch deletion beyond the merged PR branches, or any other author's work.
+
+## Work-phase map (dependency-ordered)
+
+| Phase | PR | Branch | Pre-state | Doc |
+|-------|----|--------|-----------|-----|
+| wp1 | — | — | this roadmap | `000_plan.md` |
+| wp2 | #4244 | `codex/260911-r2-catalog-pool` | MERGEABLE, clean replay | `010_phase1_pr4244.md` |
+| wp3 | #4248 | `codex/260911-r2-pool-account-attribution` | MERGEABLE, clean replay | `020_phase2_pr4248.md` |
+| wp4 | #4246 | `codex/260911-r2-client-display` | CONFLICTING, registry-only | `030_phase3_pr4246.md` |
+| wp5 | #4247 | `codex/260911-r2-docs-locales` | CONFLICTING, substantive | `040_phase4_pr4247.md` |
+
+Order is cheapest-and-safest first. #4244 and #4248 replay cleanly onto `dev`
+(`git merge-tree --write-tree` exits 0 for both, and `dev` has no commits touching their
+source files since the merge base), so they land first and shrink the train before the
+two conflicting branches are touched. #4246's conflict is a single sorted-registry line.
+#4247's is the only one where `dev` and the PR edited the same prose and the same test
+oracle, so it goes last, when nothing else is queued behind it.
+
+## Verification protocol (every implementation phase)
+
+Each of wp2–wp5 runs one full PABCD cycle and clears the same gate before its merge:
+
+1. `git rebase origin/dev` on the PR branch, conflicts resolved by hand, PR intent preserved.
+2. `bun run typecheck` — exit 0.
+3. The PR's own test files, run by path. Whenever `layout.json` or
+   `test-layout-expected.json` is in the touch set, add `tests/test-layout.test.ts` and
+   `tests/test-layout-tooling.test.ts`; those two are the guards that a hand-resolved
+   registry conflict can silently break.
+4. `git push --force-with-lease` to that PR branch only.
+5. `gh pr checks <n>` green at the exact new head SHA — not at a previous head.
+6. A comment on the PR recording the maintainer-integration decision and the exact head
+   SHA that CI verified. `MAINTAINERS.md:59-64` permits a maintainer with `admin` or
+   `maintain` access to integrate their own PR into `dev` without a second approval, and
+   requires that the choice and the exact-head verification be recorded in the PR
+   description or a comment. The account driving this train holds `admin`.
+7. `gh pr merge <n> --merge` only after steps 5 and 6.
+8. `git fetch origin` and re-check the remaining branches' mergeability, because the
+   merge just moved the base out from under them.
+
+The merge method is `--merge`, not `--squash`. The repository allows both, but every
+recent integration on `dev` is a merge commit (`18e553a52`, `42184ead0`, `6d8ed37ad`,
+`5557612d4`, ...) with the branch's individual commits preserved beneath it. Squashing
+these four would break that convention and, for #4246, would discard the two review-round
+commit messages that explain what the adversarial review changed.
+
+`AGENTS.md` reserves the repository-wide `bun run test` for the PR-ready gate and for
+touch sets whose dependencies are not visible to Bun's module graph. Every phase here is
+already a published PR, so CI runs the full suite on three platforms at step 5 regardless;
+the local runs above exist to catch a bad conflict resolution before it costs a CI cycle.
+
+## Acceptance
+
+DONE when all four PRs are merged into `dev`, each with green required CI recorded at its
+own rebased head SHA, and no target PR is left open or conflicting.
+
+BLOCKED if a conflict cannot be resolved without changing what the PR meant, or CI fails
+at a rebased head for a reason the rebase did not introduce, and the same blocker survives
+three goal turns.
+
+NEEDS_HUMAN if merging requires authority this session does not hold — for example a
+branch protection rule that refuses the maintainer self-integration path.
diff --git a/devlog/_plan/260911_r2_merge_train/010_phase1_pr4244.md b/devlog/_plan/260911_r2_merge_train/010_phase1_pr4244.md
new file mode 100644
index 0000000000..3ee73f39d4
--- /dev/null
+++ b/devlog/_plan/260911_r2_merge_train/010_phase1_pr4244.md
@@ -0,0 +1,47 @@
+# wp2 — PR #4244 `provider: seed GLM-5.3-Flash on the BigModel Responses preset`
+
+Branch `codex/260911-r2-catalog-pool`, head `481230445`, one commit, base `dev`.
+
+## What it changes
+
+MODIFY `src/providers/registry.ts` — the `zhipu-bigmodel-responses` entry gains
+`glm-5.3-flash` in `models`, plus matching entries in `modelContextWindows`
+(`1_048_576`), `modelInputModalities` (`["text", "image"]` — the only vision-capable row
+on this preset), `modelReasoningEfforts` (`ZAI_GLM_53_REASONING_EFFORTS`),
+`modelDefaultReasoningEfforts` (`"max"`) and `modelSupportsReasoningSummaries` (`true`).
+`liveModels: false` and `apiKeyValidation: "unknown"` are deliberately unchanged, because
+no upstream page establishes an authenticated `/models` contract for this endpoint.
+
+MODIFY `tests/providers/provider-registry-parity.test.ts` — the oracle test is renamed
+from "exports only the officially documented static Codex models" to "exports the
+documented Coding Plan roster for the Codex endpoint" and its expected `models` array
+becomes `["glm-5.3", "glm-5.3-flash", "glm-5-turbo"]`. The locked-down assertions on
+`liveModels` and `apiKeyValidation` stay.
+
+## Rebase expectation
+
+Clean. `git merge-tree --write-tree origin/dev origin/codex/260911-r2-catalog-pool` exits
+0, and `git log <merge-base>..origin/dev -- src/providers/registry.ts` is empty, so no
+commit on `dev` has touched the registry since this branch forked. The replay should be a
+straight fast-forward of one commit onto `18e553a52` or its successor.
+
+If a conflict does appear, it means another provider row landed on `dev` between this
+plan and execution; re-read the incoming hunk before resolving, and keep this PR's row
+additive rather than reordering neighbours.
+
+## Verification
+
+```
+bun run typecheck
+bun test tests/providers/provider-registry-parity.test.ts
+```
+
+No layout-registry files are touched, so the test-layout guards are not required here.
+
+## Land
+
+```
+git push --force-with-lease origin codex/260911-r2-catalog-pool
+gh pr checks 4244 --watch
+gh pr merge 4244 --merge
+```
diff --git a/devlog/_plan/260911_r2_merge_train/020_phase2_pr4248.md b/devlog/_plan/260911_r2_merge_train/020_phase2_pr4248.md
new file mode 100644
index 0000000000..8798597029
--- /dev/null
+++ b/devlog/_plan/260911_r2_merge_train/020_phase2_pr4248.md
@@ -0,0 +1,59 @@
+# wp3 — PR #4248 `pool: name the account when a refresh fails or its models vanish`
+
+Branch `codex/260911-r2-pool-account-attribution`, head `605034a6d`, one commit, base `dev`.
+
+## What it changes
+
+MODIFY `src/codex/catalog/sync.ts`, `src/server/responses/compact.ts`,
+`src/server/responses/core.ts` — pool refresh failures and disappearing model rosters are
+attributed to the specific account they came from instead of being reported anonymously.
+
+MODIFY `scripts/test-layout/layout.json` and `tests/fixtures/test-layout-expected.json` —
+registry entries for the new test files.
+
+NEW `tests/responses/responses-pool-refresh-attribution.test.ts` and
+`tests/codex-integration/catalog-gated-native-suppression-reason.test.ts`.
+
+## Rebase expectation
+
+Clean. `git merge-tree --write-tree` exits 0 against the current `dev`, and `dev` has no
+commits touching `sync.ts`, `compact.ts` or `core.ts` since the merge base. The two
+registry files auto-merge because this branch's added keys do not collide with the key
+`dev` added (`cli-config-show-client.test.ts`).
+
+This phase runs *before* #4246 deliberately: #4246 adds `cli-connect-readiness.test.ts` to
+the same sorted block that `dev` just touched and does conflict. Landing the non-conflicting
+registry change first means #4246 later replays against one settled block instead of two
+moving ones.
+
+Note the core-path constraint from `AGENTS.md`: `src/server/responses/core.ts` is one of
+the three files that must not reach `src/lab/`. The conflict resolution must not introduce
+an import that violates it; `tests/lab/core-lab-boundary.test.ts` is the guard.
+
+## Verification
+
+```
+bun run typecheck
+bun test tests/responses/responses-pool-refresh-attribution.test.ts
+bun test tests/codex-integration/catalog-gated-native-suppression-reason.test.ts
+bun test tests/test-layout.test.ts tests/test-layout-tooling.test.ts
+bun test tests/lab/core-lab-boundary.test.ts
+```
+
+The layout guards are mandatory here because both registry files are in the touch set.
+The lab-boundary guard is cheap and `core.ts` is in the touch set.
+
+`compact.ts` has no focused test of its own in this list. Its change threads the account
+namespace into `poolCredentialRefreshIncompleteResponse`, which lives in `core.ts` and is
+covered by `responses-pool-refresh-attribution.test.ts`, so the behaviour is reached
+indirectly rather than unverified. Accepted as-is for a phase that is replaying an already
+green PR: CI runs the full suite at the rebased head, which is where a compact-path
+regression would surface. Worth a dedicated test if this code is touched again.
+
+## Land
+
+```
+git push --force-with-lease origin codex/260911-r2-pool-account-attribution
+gh pr checks 4248 --watch
+gh pr merge 4248 --merge
+```
diff --git a/devlog/_plan/260911_r2_merge_train/030_phase3_pr4246.md b/devlog/_plan/260911_r2_merge_train/030_phase3_pr4246.md
new file mode 100644
index 0000000000..cfbed7601e
--- /dev/null
+++ b/devlog/_plan/260911_r2_merge_train/030_phase3_pr4246.md
@@ -0,0 +1,83 @@
+# wp4 — PR #4246 `client: report local Codex readiness instead of bare connected state`
+
+Branch `codex/260911-r2-client-display`, head `e53999762`, three commits, base `dev`.
+State before rebase: `CONFLICTING` / `DIRTY`.
+
+## What it changes
+
+MODIFY `src/cli/connect.ts`, `src/cli/status.ts`, `src/client/catalog-compatibility.ts`.
+MODIFY `scripts/test-layout/layout.json`, `tests/fixtures/test-layout-expected.json`.
+NEW `tests/cli/cli-connect-readiness.test.ts`.
+MODIFY `tests/cli/cli-status-json.test.ts`, `tests/clients/client-catalog-compatibility.test.ts`.
+
+Three commits, the second and third of which fold an adversarial review and give the
+write-time gate the same observer in production. Keep all three on the rebase and do not
+squash them locally: this repository merges with merge commits, so all three land on
+`dev` individually and their messages stay the record of what the review changed.
+
+## The conflict, exactly
+
+Two files, one hunk each, and both are the same shape. In `scripts/test-layout/layout.json`:
+
+```
+      "cli-config-command.test.ts": "cli",
+<<<<<<< origin/dev
+      "cli-config-show-client.test.ts": "cli",
+=======
+      "cli-connect-readiness.test.ts": "cli",
+>>>>>>> origin/codex/260911-r2-client-display
+      "cli-dispatch.test.ts": "cli",
+```
+
+`tests/fixtures/test-layout-expected.json` carries the identical conflict at the same
+position with two fewer spaces of indentation.
+
+This is an additive collision, not a disagreement: `dev` registered
+`cli-config-show-client.test.ts` while this branch registered
+`cli-connect-readiness.test.ts`. The resolution keeps **both** lines, in sorted order —
+`cli-config-show-client.test.ts` first, because `config` sorts before `connect` at the
+fourth character (`f` < `n`).
+
+Resolved form, in both files:
+
+```
+      "cli-config-command.test.ts": "cli",
+      "cli-config-show-client.test.ts": "cli",
+      "cli-connect-readiness.test.ts": "cli",
+      "cli-dispatch.test.ts": "cli",
+```
+
+Taking either side alone is a silent failure with two different signatures, which is why
+the guards below are not optional: dropping `dev`'s line un-registers a test file that is
+already on `dev` (`tests/test-layout.test.ts` fails — a file that resolves to no domain),
+and dropping this branch's line un-registers the new one (`tests/test-layout-tooling.test.ts`
+fails and names the missing entry).
+
+The guards catch *membership*, not ordering. `tests/test-layout-tooling.test.ts` compares
+the fixture with `toEqual` on a parsed object, which is key-order independent, and
+`tests/test-layout.test.ts` carries no sort assertion at all. So the sorted placement above
+is file hygiene — it keeps the next diff on this block one line instead of a reshuffle —
+while the thing the guards would actually fail on is a dropped or mismatched entry. Both
+matter; only one of them is machine-enforced, and the resolution should not lean on the
+wrong one.
+
+## Verification
+
+```
+bun run typecheck
+bun test tests/test-layout.test.ts tests/test-layout-tooling.test.ts
+bun test tests/cli/cli-connect-readiness.test.ts
+bun test tests/cli/cli-status-json.test.ts
+bun test tests/clients/client-catalog-compatibility.test.ts
+```
+
+The two layout guards run first here, not last: they are the direct oracle for the only
+hand-edit the rebase requires.
+
+## Land
+
+```
+git push --force-with-lease origin codex/260911-r2-client-display
+gh pr checks 4246 --watch
+gh pr merge 4246 --merge
+```
diff --git a/devlog/_plan/260911_r2_merge_train/040_phase4_pr4247.md b/devlog/_plan/260911_r2_merge_train/040_phase4_pr4247.md
new file mode 100644
index 0000000000..a4aa41a222
--- /dev/null
+++ b/devlog/_plan/260911_r2_merge_train/040_phase4_pr4247.md
@@ -0,0 +1,127 @@
+# wp5 — PR #4247 `docs(i18n): make the remote hub guide runnable in every locale`
+
+Branch `codex/260911-r2-docs-locales`, head `7730f08a7`, one commit, base `dev`.
+State before rebase: `CONFLICTING` / `DIRTY`. This is the only substantive conflict in
+the train, which is why it is last.
+
+## What it changes
+
+MODIFY the seven translated copies of the remote hub guide —
+`docs-site/src/content/docs/{fr,ja,ko,ru,tr,zh-cn,zh-tw}/guides/remote-hub.md` — so each
+one carries the corrected command ordering that round one (#4200) applied to the English
+source only.
+
+MODIFY `tests/ci-workflows/docs-remote-hub-claims.test.ts` — the oracle stops reading one
+file. It gains `TRANSLATED` and `LOCALE_GUIDES` and a `remote hub guide translations`
+describe block that runs the same expectations over all eight locales, English included.
+
+## Why it conflicts
+
+`dev` landed #4236 in the same two files while this branch was open. #4236 rewrote the
+Korean guide for the one-port recipe and added its own `the one-port hub recipe` describe
+block plus a `KO_GUIDE` constant to the same test file. So both sides added a block to the
+same oracle and both sides rewrote `ko/guides/remote-hub.md`.
+
+`git merge-tree` reports two conflicted files: the test file with three conflicted regions,
+and `ko/guides/remote-hub.md` with four (twelve markers).
+
+## Resolution contract
+
+Both sides are additive in intent and neither may be dropped. Concretely:
+
+**`tests/ci-workflows/docs-remote-hub-claims.test.ts`**
+
+1. *Header comment.* Keep both paragraphs. `dev`'s explains why the manual
+   `export OPENCODEX_API_AUTH_TOKEN` step must stay gone; this branch's explains why the
+   oracle stopped reading one file. They document different groups and neither replaces
+   the other.
+2. *Constants.* Keep `GUIDE`, then this branch's `TRANSLATED` / `LOCALE_GUIDES`, and keep
+   `dev`'s `KO_GUIDE` — `the one-port hub recipe` block references it directly. Do not
+   try to derive one from the other; a lookup into `LOCALE_GUIDES` to save four lines would
+   make `dev`'s block depend on this branch's array ordering for no benefit.
+3. *Describe blocks.* Keep both, side by side: `the one-port hub recipe` (en + ko) from
+   `dev`, and `remote hub guide translations` (all eight) from this branch.
+
+**`docs-site/src/content/docs/ko/guides/remote-hub.md`**
+
+The Korean page must satisfy both oracles after the merge, and that is the actual
+acceptance test for this resolution rather than any judgement about prose. It must keep
+#4236's one-port content — the port-less companion form
+`ocx config set unauthenticatedLoopbackListener '{"enabled":true}'`, the ported
+`{"enabled":true,"port":10104}` alternative, `service-api-token`, `ocx hub invite`,
+`ocx config set corsAllowOrigins '["http://localhost:10100"]'`, `--pairing-code-stdin`, and
+**no** line matching `/^\s*export\s+OPENCODEX_API_AUTH_TOKEN/m` — while also keeping this
+branch's ordering fix: `ocx config set hub '{}'` before any `ocx config set hub.`, the same
+for `remoteGui`, and the literal string `config parent path not found: hub`.
+
+Where the two rewrites touch the same paragraph, `dev`'s newer one-port wording wins on
+content and this branch's corrected command ordering wins on sequence. They are compatible:
+the ordering fix is about which `ocx config set` line comes first, not about what the
+recipe says.
+
+## The port reconciliation (audited blocker, must be done)
+
+This branch's translations block includes `"en"` in `LOCALE_GUIDES` and asserts the same
+markers over every locale. #4236 rewrote the English guide after this branch forked, and
+the A-phase audit found one marker pair that genuinely diverged. This is not a risk to
+check — it is a confirmed conflict with a required fix.
+
+The branch asserts, for all eight locales:
+
+```
+socat TCP-LISTEN:10100,bind=127.0.0.1
+tailscale serve --bg --https=8443 http://127.0.0.1:10100
+```
+
+`origin/dev` now carries `10110` in both lines, in the English guide and in the Korean one,
+and all seven translated guides on this branch still carry `10100`.
+
+**10110 is the correct value and 10100 is now a defect.** #4236 enabled the loopback
+companion listener, which binds `127.0.0.1:10100` — the proxy port itself. The English
+guide says so in the comment directly above the command: "Pick a port the hub is not
+already using: with the loopback companion enabled, `127.0.0.1:10100` belongs to opencodex
+itself." A reader following any of the seven translations would bind socat onto the
+companion listener's own port and get a collision.
+
+So the resolution is not "make the assertion match the file". It is to finish the job this
+PR exists to do — carry the English fix into the translations:
+
+1. In all seven translated guides, change `socat TCP-LISTEN:10100,bind=127.0.0.1` to
+   `socat TCP-LISTEN:10110,bind=127.0.0.1` and
+   `tailscale serve --bg --https=8443 http://127.0.0.1:10100` to `...:10110`. The forwarder
+   *destination* `TCP:100.64.0.10:10100` stays 10100 — that is the tailnet-bound proxy
+   port and it did not move. Only the loopback listen port changes.
+2. Carry the explanatory comment above the command too, in each locale's own language,
+   and the `tailscale serve status   # expect both mappings: 443 -> 10101, 8443 -> 10110`
+   line. A translation that changes the port without the reason is a worse artifact than
+   one that is merely stale.
+3. Update the two assertions in the translations block to `10110`.
+4. Keep `dev`'s `10110` in the Korean guide when resolving its four conflicted regions.
+
+Every other marker the block pins was audited against the current `dev` English guide and
+is still satisfied: the `hub` / `remoteGui` `'{}'` initializer ordering, the literal
+`config parent path not found: hub`, the whole-object `ocx config set hub '{"managementPublicOrigin"`
+form with its replace-not-merge caveat, `403 origin_rejected`, `X-Forwarded-Host`, and the
+absence of `--allow-insecure-http`.
+
+## Verification
+
+```
+bun run typecheck
+bun test tests/ci-workflows/docs-remote-hub-claims.test.ts
+```
+
+The oracle reads the eight markdown files as data, which `bun run test:changed` cannot see
+through its module graph. That is the indirect-dependency exception in `AGENTS.md`, so run
+this file by path and do not rely on change detection to select it.
+
+No source under `src/` is touched, so this is docs-only work with a test oracle attached;
+the relevant consistency gate is the oracle itself.
+
+## Land
+
+```
+git push --force-with-lease origin codex/260911-r2-docs-locales
+gh pr checks 4247 --watch
+gh pr merge 4247 --merge
+```
diff --git a/devlog/_plan/260911_ws_commit_boundary/000_plan.md b/devlog/_plan/260911_ws_commit_boundary/000_plan.md
new file mode 100644
index 0000000000..2194f3c901
--- /dev/null
+++ b/devlog/_plan/260911_ws_commit_boundary/000_plan.md
@@ -0,0 +1,56 @@
+# WS commit boundary — 260911
+
+Base: `origin/dev` `babb76449f` (fetched 2026-09-11 KST). Branch `codex/260911-ws-commit-boundary`,
+worktree `/Users/jun/.codex/worktrees/260911-wsc/opencodex`.
+
+## Why this unit exists
+
+#4191 reports a long Codex thread that fails only while routed through OpenCodex, as either
+`codex websocket closed before a Responses terminal event (close 1006 Connection ended)` or
+`codex websocket response prelude timed out`, and works immediately when the proxy is bypassed.
+#4083 raised the fixed prelude deadline from 30 s to 90 s for slow multi-image starts; #3976 asked
+for the number to be configurable; #2471 fixed the 16 MiB create-frame ceiling.
+
+The lane dispatch round (`260911_lane_dispatch_round`) added the #4191 failure-stage counters so
+a user can tell an unanswered socket from one that carried only quota frames. That was
+diagnosis. This unit is the fix to the boundary the diagnosis exposed, after an external
+semantic review (`010_journey_evaluation.md`) overturned the first framing.
+
+## Scope
+
+- `src/server/responses/codex-ws-exchange.ts` — settle post-send, pre-response failures as an
+  honest HTTP status; replace the fixed prelude timer with silence-based liveness; cancel the
+  upstream turn on a pre-commit client abort.
+- `src/server/responses/codex-ws-wire.ts` — liveness constants and the non-replayable body shape.
+- `src/lib/upstream-retry.ts` — a non-replayable marker that `fetchWithTransientRetry` honours, and the
+  structured error codes the other resend paths stop on.
+- `src/server/responses/core.ts` — two early returns on the marker (pool quota rotation, opaque-blob
+  recovery); `src/combos/failover.ts` — structured-code stop. See 025.
+- `docs-site/src/content/docs/reference/configuration/server.md` — the prelude paragraph.
+- `tests/responses/ws-upstream.test.ts`, `tests/lib/upstream-retry.test.ts` — oracle updates and
+  new cases.
+
+Out of scope, recorded in `020_design_record.md`: resume-by-id after 1006 (Codex does not request
+background responses, so the vendor resume surface does not apply), the opt-in provider path
+without a metadata channel (it commits at send today and keeps doing so), the create-frame size
+predicate, and any core.ts change beyond the two marker guards named in 025.
+
+## Rules for this unit
+
+- No local product suite: no `bun test`, `bun run test`, `test:changed`, `typecheck`,
+  `build:gui`, or `bun install` in this worktree. Every verification line reads NOT RUN until
+  remote CI on the final head says otherwise.
+- Push with `--no-verify` and `core.hooksPath=/dev/null`.
+- xai/grok-4.6 subagents are read-only verifiers of the diff; aside/web research is free.
+- One work-phase is one PABCD cycle: wp1 this roadmap, wp2 honest status + marker, wp3 liveness
+  and abort propagation, wp4 PR, review, CI.
+
+## Work phases
+
+| wp | unit | doc | exit |
+|---|---|---|---|
+| wp1 | roadmap | 000, 010, 020 | docs committed on the branch |
+| wp2 | honest post-send status | 030 | code + tests committed, NOT RUN |
+| wp3 | liveness + abort | 040 | code + tests committed, NOT RUN |
+| wp4 | PR + review + CI | 050 | final-head CI green, review dispositioned |
+
diff --git a/devlog/_plan/260911_ws_commit_boundary/010_journey_evaluation.md b/devlog/_plan/260911_ws_commit_boundary/010_journey_evaluation.md
new file mode 100644
index 0000000000..a4dd9c48f8
--- /dev/null
+++ b/devlog/_plan/260911_ws_commit_boundary/010_journey_evaluation.md
@@ -0,0 +1,50 @@
+# Journey evaluation — how the framing changed
+
+## What was done before this unit
+
+1. Lane dispatch round: seven file-disjoint lanes from `6d3ad12e3`, each a worktree and a
+   Codex thread, merged serially on final-head green CI (#4217 … #4248). One of those lanes landed
+   the #4191 failure-stage counters in `codex-ws-wire.ts`: request bytes, sent, frames, control
+   frames, relayed events, first-frame and elapsed durations. The counters are content-free by
+   construction and only classify; they were never a fallback signal.
+2. Structure question from the owner: `codex -> http -> opencodex -> ws -> openai` — is the
+   asymmetry itself the bug? Source reading said no: WS is chosen only for streaming POSTs on a
+   bounded-relay Bun, the create frame is measured before dialling, and the one reversible point is
+   the send. First framing: the reversible window is too narrow and judged by size alone; widen the
+   HTTP path below the ceiling and scale the prelude budget by frame size.
+3. Semantic review by anthropic/claude-fable-5-1. Three corrections were accepted after source
+   confirmation:
+   - The no-resend-after-send rule is not a defect. RFC 9110 §9.2.2 forbids an intermediary from
+     automatically repeating a non-idempotent request; the user agent owns that decision. Offering
+     "allow fallback after send" as an option was the wrong question.
+   - The broken contract is the status code. `commitResponse` builds `new Response(stream,
+     { status: 200 })` before any upstream frame, and `failStream` commits that 200 on the failure
+     path (`if (sent) commitResponse()`) precisely so the pre-stream wrapper cannot resend. The proxy
+     therefore converts "no response" into "a response that failed", removes the status the client
+     would use for its own retry policy, and neuters the client's first-byte timeout with chunked
+     headers. Direct-to-vendor Codex survives the same at-most-once lane through its own retry; the
+     proxy is stricter than the party whose money is at stake and pays for it with a hard failure.
+   - The 90 s prelude is the wrong kind of quantity: it folds "dead" and "slow" into one number.
+     Dead is a liveness question with a native answer (ping/pong); slow already has an owner (the
+     client deadline). A fixed proxy deadline in series always inherits the tighter bound.
+
+## What the evaluation keeps and drops
+
+Kept: every existing oracle (no HTTP fallback after send, one `response.create` per exchange,
+refused-create 4xx projection, correlation before conversion, bounded queue). Kept: the 90 s
+number, but demoted from "time to first response event" to "unanswered silence with no pong",
+which is unreachable on a socket whose peer answers pings.
+
+Dropped: post-send HTTP fallback (never acceptable), size-scaled prelude budgets (treats the
+symptom), resume-by-id after 1006 (Codex sends `stream: true` without `background: true`; the
+vendor resume endpoint requires a background response, so there is nothing to resume for this
+client; recorded as a follow-up for callers that do opt in).
+
+## What this unit does not claim
+
+It does not claim the Codex backend answers WebSocket pings; the exchange feature-detects
+`ws.ping` and degrades to the previous 90 s behaviour when no pong ever arrives. It does not run
+any local suite. Whether the honest 504 improves the #4191 user's experience is a live question
+that only a field report can answer; what this unit guarantees is that the proxy stops hiding the
+signal that user's client needs.
+
diff --git a/devlog/_plan/260911_ws_commit_boundary/020_design_record.md b/devlog/_plan/260911_ws_commit_boundary/020_design_record.md
new file mode 100644
index 0000000000..36dbd8b533
--- /dev/null
+++ b/devlog/_plan/260911_ws_commit_boundary/020_design_record.md
@@ -0,0 +1,95 @@
+# Design record — commit boundary, liveness, abort
+
+## Invariants that stay
+
+- I1 No HTTP SSE fallback once `ws.send()` has returned (`sent === true`).
+- I2 One `response.create` frame per exchange; no proxy-internal resend after send.
+- I3 A refused create (`type: error`, no `stream_id`, 4xx status) before any response event is
+  projected as that 4xx with the metadata snapshot (#3740); correlation runs first.
+- I4 After the first `response.*` or `error` event has been relayed, every later failure is a
+  body error on the already-committed 200 (the relay synthesizes `response.failed`).
+
+## New invariant
+
+- I5 (exchanges with a metadata channel, i.e. the canonical Codex backend) The client commit never
+  precedes the upstream acknowledgment. Before the first
+  `response.*`/`error` event the exchange holds no client Response. A failure in that window
+  settles as a JSON error with an honest gateway status, marked non-replayable.
+
+## Diff-level plan
+
+### `src/lib/upstream-retry.ts`
+
+Add a `WeakSet<Response>` with `markResponseNonReplayable(res)` and
+`isNonReplayableResponse(res)`. In `fetchWithTransientRetry` the loop guard becomes
+`if (res.ok || !isTransientUpstreamStatus(res.status) || isNonReplayableResponse(res)) return res;`.
+Rationale in the doc comment: the origin may already be executing the request (RFC 9110 §9.2.2),
+so a gateway status from a post-send transport is returned to the caller for its own policy.
+
+### `src/server/responses/codex-ws-wire.ts`
+
+- `CODEX_WS_LIVENESS_PING_INTERVAL_MS = 15_000`.
+- `CODEX_WS_RESPONSE_PRELUDE_TIMEOUT_MS` keeps its value (90 000) and gains a new meaning in its
+  comment: the longest inbound silence (no message frame, no pong) tolerated before the first
+  response event.
+- `codexWsPreResponseFailure(status, message, prelude: Headers): Response` — builds
+  `{ error: { type: "upstream_error", code, message } }` with `content-type: application/json`,
+  `cache-control: no-store`, the metadata snapshot headers, and calls
+  `markResponseNonReplayable`. `code` is `upstream_timeout` for 504 and
+  `upstream_closed_before_response` for 502.
+- `CodexWsFailureStage` gains `pings` and `pongs`; `codexWsFailureDetail` appends
+  ` pings=N pongs=N` inside the bracket, after `elapsed`. `tests/responses/ws-failure-stage.test.ts`
+  is updated in the same commit.
+
+### `src/server/responses/codex-ws-exchange.ts`
+
+- `failStream(error, status: 502 | 504 = 502)`: when `sent && !responseCommitted`, resolve
+  `codexWsPreResponseFailure(status, message, metadata.snapshot())` instead of committing a 200,
+  close the controller, dispose the session. When committed, unchanged.
+- `cancelExchange(reason)` when `sent && !responseCommitted`: mark terminal, cleanup, dispose the
+  session (this closes the socket, which is the upstream cancel), `reject(reason)`. The caller's
+  own abort is never retried by the wrappers (`isConnectionResetError` excludes AbortError and the
+  retry loops check `abortSignal.aborted`).
+- Liveness replaces the single `preludeTimer`:
+  - `armSilence()` (re)starts a `CODEX_WS_RESPONSE_PRELUDE_TIMEOUT_MS` timer whose expiry calls
+    `failStream("codex websocket response prelude timed out" + detail, 504)`.
+  - `onMessage` and `onPong` call `armSilence()` while `!responseCommitted`.
+  - After send, when `typeof ws.ping === "function"`, a repeating
+    `CODEX_WS_LIVENESS_PING_INTERVAL_MS` timer calls `ws.ping()` until commit or terminal; a
+    throwing `ping()` stops the pinger only.
+  - `cleanup()` clears both timers and removes the `pong` listener; `commitResponse()` clears
+    them too.
+- The non-metadata path (`if (!metadata) commitResponse()`) is unchanged.
+
+### Tests (`tests/responses/ws-upstream.test.ts`)
+
+Updated oracles: prelude overflow → 502 JSON, not a WS-marked stream; first-response deadline
+through `fetchWithTransientRetry` → 504, one send, zero HTTP; foreign-stream identity mismatch →
+502; close 1006 / 1009 before any response event → 502 carrying the same messages; abort after send
+before commit → the pending fetch rejects with the caller reason and the socket is closed.
+
+New cases: a pong resets the silence clock past 90 s and the response still completes with one
+send; a socket exposing `ping` is pinged every 15 s of prelude and stops after commit; a socket
+without `ping` is never pinged and keeps the 90 s bound; `fetchWithTransientRetry` returns a
+non-replayable 504 without a second call (`tests/lib/upstream-retry.test.ts`).
+
+## Audit amendments
+
+See `025_audit_round1.md`; its deltas override this file where they differ.
+
+## Risks and their answers
+
+- Client behaviour on 504: Codex retries stream requests on 5xx with backoff, which is the same
+  policy it applies on the direct path; the proxy no longer substitutes its own.
+- Pool recovery on 5xx: `shouldRetryCodexPoolAccountQuota` rotates only on body-confirmed quota
+  evidence; the new body carries none. Opaque-blob recovery excludes 5xx other than 502 with an
+  encrypted-output body, which this is not.
+- Backend pong support unknown: feature-detected and degrades to the current bound.
+- Request log: the failure is now a 504/502 row instead of a 200 with `streamAborted`; this is
+  the intended diagnostic change.
+
+## Verification
+
+NOT RUN locally by rule. Remote CI on the final head is the only executable proof; the read-only
+grok-4.6 review of the diff is the second pair of eyes.
+
diff --git a/devlog/_plan/260911_ws_commit_boundary/025_audit_round1.md b/devlog/_plan/260911_ws_commit_boundary/025_audit_round1.md
new file mode 100644
index 0000000000..69ff1642b9
--- /dev/null
+++ b/devlog/_plan/260911_ws_commit_boundary/025_audit_round1.md
@@ -0,0 +1,29 @@
+# Audit round 1 — xai/grok-4.6 (read-only), dispositions
+
+Verdict received: FAIL as written. Every finding below is dispositioned; the design record is
+amended in place and the scope in 000 is widened to match.
+
+| # | severity | finding | disposition |
+|---|---|---|---|
+| 1 | blocker | A marker honoured only by `fetchWithTransientRetry` leaves the Codex pool quota rotation (`shouldRetryCodexPoolAccountQuota`, core.ts:1120) and the combo 5xx hop (core.ts:3004 → `comboFailureDecision`) free to send again after `ws.send()`. | ACCEPTED. core.ts and src/combos/failover.ts enter scope minimally: (a) `shouldRetryCodexPoolAccountQuota` and `opaqueBlobRejectionBodyForRecovery` return early on `isNonReplayableResponse`; (b) the JSON body carries a structured `error.code` (`upstream_no_response`, `upstream_closed_before_response`) and `comboFailureDecision` returns `stop` for those codes, the same mechanism `origin_rejected` already uses. The code set lives in `src/lib/upstream-retry.ts` so combos need no server import. |
+| 2 | major | Resetting the 90 s clock on quota/control frames removes the cap for a quota-only socket; it then runs to `connectTimeoutMs` (default 200 s) and settles as a `TimeoutError` 502 from `transportFailureResponse`, not the 504 the record promises. | ACCEPTED as a named behaviour change, with the status fixed. A socket that keeps sending frames or pongs is alive; the record now says so and names the quota-only case explicitly: it waits up to the operator's `connectTimeoutMs`, then the composite signal aborts with `TimeoutError`, and `cancelExchange` maps a pre-commit `TimeoutError` to the same non-replayable 504 instead of rejecting. Only a caller abort (AbortError) rejects. |
+| 3 | major | Oracle list is short: metadata budget overflow rows (794), cumulative prelude bound (807), pre-response oversized frame (1064), and the `failureMessage()` helper cases in ws-failure-stage (171, 182, 208) all leave the 200 body-error shape. Foreign-stream 502 conflicts with the in-source note that a reused socket's foreign error must not become an HTTP refusal. | ACCEPTED. All listed tests are updated in wp2. The foreign-stream note was about a 4xx conversion that could authorize account replay; a non-replayable 502 authorizes nothing, and the test now asserts status 502, one send, zero fallback. The source comment is reworded to say that. |
+| 4 | major | `failStream` rewrite could skip `cleanup()` and leak the pinger, silence timer, pong listener, or double-settle via `onClose`. | ACCEPTED. Order fixed in the record: `terminal = true; cleanup();` then settle, then `session.dispose()`. `cleanup()` and `commitResponse()` both clear the liveness timers and detach `pong`. |
+| 5 | minor | I5 is stated globally while the no-metadata path commits at send. | ACCEPTED. I5 is scoped to exchanges with a metadata channel (the canonical Codex backend). |
+| 6 | minor | `connectTimeoutMs` < 90 s makes a post-send abort a 502 connect timeout, not a 504. | ACCEPTED via finding 2: any pre-commit `TimeoutError` becomes the non-replayable 504. |
+| 7 | minor | `docs-site/` paragraph on the fixed 90-second prelude deadline (reference/configuration/server.md:38-47) becomes wrong. | ACCEPTED. The paragraph is rewritten in wp3 to describe silence-based liveness and the honest status. |
+| 8 | nit | Exact `codexWsFailureDetail` pin, `stage()` fixture defaults, fake-timer stepping for pong tests, feature-detect `ping` not pong. | ACCEPTED. `stage()` defaults `pings: 0, pongs: 0`; pinned strings updated; pong tests step the clock. |
+
+Not accepted: none.
+
+## Amended plan deltas (authoritative over 020 where they differ)
+
+- Scope adds `src/server/responses/core.ts` (two early returns), `src/combos/failover.ts` (one
+  structured-code stop), `docs-site/src/content/docs/reference/configuration/server.md` (one
+  paragraph), `tests/responses/ws-failure-stage.test.ts`, `tests/combos/*` only if an existing
+  decision table needs the new row.
+- `cancelExchange(reason)` pre-commit: `reason?.name === "TimeoutError"` → non-replayable 504
+  with `upstream_no_response`; anything else → `reject(reason)`.
+- Liveness semantics: silence = no inbound message frame and no pong. Any inbound frame resets.
+  Quota-only sockets are alive and wait for the client or `connectTimeoutMs`.
+
diff --git a/devlog/_plan/260911_ws_commit_boundary/030_wp2_plan.md b/devlog/_plan/260911_ws_commit_boundary/030_wp2_plan.md
new file mode 100644
index 0000000000..29176614f0
--- /dev/null
+++ b/devlog/_plan/260911_ws_commit_boundary/030_wp2_plan.md
@@ -0,0 +1,36 @@
+# wp2 — honest post-send status and the non-replayable marker
+
+Previous D (wp1): roadmap locked at c3c1ea6731; direction unchanged — the fix is the commit
+boundary, not the transport choice. 025 deltas are authoritative over 020.
+
+## Files and exact changes
+
+### src/lib/upstream-retry.ts
+- Add a WeakSet<Response> with markResponseNonReplayable(res) and isNonReplayableResponse(res).
+- Add NON_REPLAYABLE_UPSTREAM_CODES = {"upstream_no_response", "upstream_closed_before_response"} and isNonReplayableUpstreamCode(code).
+- fetchWithTransientRetry loop guard: return res when isNonReplayableResponse(res).
+
+### src/combos/failover.ts
+- comboFailureDecision: after the 499/origin_rejected checks, return "stop" when isNonReplayableUpstreamCode(options?.code).
+
+### src/server/responses/core.ts
+- shouldRetryCodexPoolAccountQuota: first line returns false on isNonReplayableResponse(response).
+- opaqueBlobRejectionBodyForRecovery: same early return undefined.
+
+### src/server/responses/codex-ws-wire.ts
+- codexWsPreResponseFailure(status: 502 | 504, message, prelude: Headers): Response — JSON body { error: { type: "upstream_error", code, message } }, code by status (504 upstream_no_response, 502 upstream_closed_before_response), headers = prelude snapshot + content-type application/json + cache-control no-store, marked non-replayable.
+
+### src/server/responses/codex-ws-exchange.ts
+- failStream(error, status = 502): when sent && !responseCommitted && metadata: terminal = true; cleanup(); resolve(codexWsPreResponseFailure(status, message, metadata.snapshot())); close the unused controller; session.dispose(). Otherwise the existing body-error path. (The non-metadata path commits at send.)
+- cancelExchange(reason) when sent && !responseCommitted && metadata: TimeoutError -> failStream(reason, 504); otherwise terminal = true; cleanup(); session.dispose(); reject(reason).
+- The prelude timer expiry calls failStream(..., 504); liveness itself is wp3.
+- Reword the foreign-stream comment: a pre-response failure settles as a non-replayable 502; the 4xx projection stays reserved for a genuine refused create.
+
+### Tests
+- ws-upstream.test.ts: update 794/807 (metadata overflow -> 502 JSON, isCodexWsUpstreamResponse false), 873 foreign -> 502 + one send, 1064 oversized pre-response -> 502, 1180 abort after open -> the fetch rejects with the caller reason and the socket is closed, 1218 -> 502, 1262 -> 504 with sends === 1, 1533/1547 -> 502 with the same messages in error.message.
+- ws-failure-stage.test.ts: failureMessage() returns error.message from a 5xx JSON body, else the thrown body error.
+- New: upstream-transient-retry.test.ts — a marked 504 returns after one send; an unmarked 504 still retries. combos test — comboFailureDecision(504, "Provider error 504", { code: "upstream_no_response" }) is stop.
+
+## Verification
+NOT RUN locally (owner rule). Remote CI on the final head in wp4.
+
diff --git a/devlog/_plan/260911_ws_commit_boundary/040_wp3_plan.md b/devlog/_plan/260911_ws_commit_boundary/040_wp3_plan.md
new file mode 100644
index 0000000000..8034ba2721
--- /dev/null
+++ b/devlog/_plan/260911_ws_commit_boundary/040_wp3_plan.md
@@ -0,0 +1,30 @@
+# wp3 — liveness replaces the fixed prelude deadline
+
+Previous D (wp2): honest 502/504 with the non-replayable marker landed at 42988a1693; draft PR #4256 opened so remote CI runs on that head. Direction unchanged.
+
+## Files and exact changes
+
+### src/server/responses/codex-ws-wire.ts
+- CODEX_WS_LIVENESS_PING_INTERVAL_MS = 15_000.
+- CODEX_WS_RESPONSE_PRELUDE_TIMEOUT_MS keeps 90_000; its comment now defines it as the longest inbound silence (no message frame, no pong) tolerated before the first response event.
+- CodexWsFailureStage gains pings and pongs (numbers); codexWsFailureDetail appends " pings=N pongs=N" after elapsed, inside the bracket.
+
+### src/server/responses/codex-ws-exchange.ts
+- Counters pings, pongs. Timers silenceTimer (replaces preludeTimer) and pingTimer.
+- armSilence(): clearTimeout(silenceTimer); if (responseCommitted || terminal) return; silenceTimer = setTimeout(() => failStream("codex websocket response prelude timed out" + detail, 504), CODEX_WS_RESPONSE_PRELUDE_TIMEOUT_MS).
+- schedulePing(): only when typeof ws.ping === "function"; pingTimer = setTimeout(() => { if (responseCommitted || terminal) return; try { ws.ping(); pings += 1; } catch { return; } schedulePing(); }, CODEX_WS_LIVENESS_PING_INTERVAL_MS).
+- onPong(): pongs += 1; if (!responseCommitted) armSilence(). Listener added with the others, removed in cleanup().
+- After a successful send on the metadata path: armSilence(); schedulePing(). onMessage calls armSilence() while !responseCommitted (after the terminal guard).
+- commitResponse() and cleanup() clear both timers; cleanup() removes the pong listener.
+- The non-metadata path is untouched (commits at send; no liveness).
+
+### docs-site/src/content/docs/reference/configuration/server.md
+- Replace the "fixed 90-second response-prelude deadline" paragraph: silence-based liveness, ping every 15 s, any inbound frame or pong resets, 90 s of nothing settles a non-replayable 504, closes/transport errors before the first response event settle 502, connectTimeoutMs remains the outer bound and a pre-response connect timeout is the same 504; no HTTP resend either way.
+
+### Tests
+- tests/responses/ws-upstream.test.ts, new describe "prelude liveness": (a) a socket whose ping() emits pong stays alive across 7 x 15 s steps (105 s > 90 s) and the response still completes with one send and zero HTTP; (b) a socket whose ping() never pongs settles 504 at 90 s with pongs=0 in the message; (c) after response.created the pinger stops (no further ping calls across 60 s). The existing first-response-deadline test already covers a socket without ping().
+- tests/responses/ws-failure-stage.test.ts: stage() defaults pings: 0, pongs: 0; the two exact toBe strings gain " pings=0 pongs=0".
+
+## Verification
+NOT RUN locally (owner rule). Remote CI on the final head in wp4.
+
diff --git a/devlog/_plan/260911_ws_commit_boundary/045_wp4_plan.md b/devlog/_plan/260911_ws_commit_boundary/045_wp4_plan.md
new file mode 100644
index 0000000000..02ec4a0393
--- /dev/null
+++ b/devlog/_plan/260911_ws_commit_boundary/045_wp4_plan.md
@@ -0,0 +1,13 @@
+# wp4 — PR, read-only diff review, final-head CI
+
+Previous D (wp3): liveness landed at 075b9f39f5 and is pushed to draft PR #4256. Direction unchanged.
+
+## Steps
+- xai/grok-4.6 read-only review of the full diff origin/dev...HEAD (t2); findings fixed or dispositioned in 050_review.md.
+- Mark PR #4256 ready for review with the final description (t1).
+- Every newest-per-workflow pull_request run on the final head SHA success (t3); record run ids in 060_ci_evidence.md.
+- Merge is not part of this goal (owner said "PR까지"); report readiness.
+
+## Verification
+NOT RUN locally. Remote CI only.
+
diff --git a/devlog/_plan/260911_ws_commit_boundary/050_review.md b/devlog/_plan/260911_ws_commit_boundary/050_review.md
new file mode 100644
index 0000000000..6ac5ddea26
--- /dev/null
+++ b/devlog/_plan/260911_ws_commit_boundary/050_review.md
@@ -0,0 +1,27 @@
+# wp4 review — xai/grok-4.6 read-only diff review (agent 01a08e96)
+
+Verdict received: FAIL with two majors and one minor.
+
+| # | severity | finding | disposition |
+|---|---|---|---|
+| 1 | major | commitResponse bailing on terminal leaves the non-metadata body-error path unsettled (failStream sets terminal first, then calls commitResponse, then controller.error with no resolve). | ACCEPTED, real bug. commitResponse guards only responseCommitted again; the JSON settle path sets responseCommitted = true before resolving so a second 200 can never be committed. |
+| 2 | major | bun-types WebSocketEventMap lists only close/error/message/open, so a client pong event may never reach onPong; ping-alive would be harness-only. | REBUTTED with a runtime probe. Bun 1.4.0 (the minimum version the bounded relay gate accepts) was probed on 2026-09-11 with a local Bun.serve websocket and a client new WebSocket: ws.ping is a function, ws.pong is a function, and addEventListener("pong") fired with the ping payload (seen: open, pong:x, message:ack). The type map is incomplete; the runtime dispatches the event. The exchange still feature-detects ping() and degrades to the message-only 90 s bound where no pong arrives, which is exactly the never-pongs oracle. Probe script kept below. |
+| 3 | minor | The never-pongs oracle used one 90 s jump and relied on recursive fake-timer scheduling. | ACCEPTED. The test now steps 15 s at a time like its sibling. |
+
+Findings 4-6 were confirmations (harness oracles, TypeScript after a00ef49af7, privacy of the JSON body).
+
+## Probe (not product code, run once in /tmp)
+
+```js
+const srv = Bun.serve({ port: 0, fetch(req, s){ if (s.upgrade(req)) return; return new Response("no"); },
+  websocket: { open(ws){}, message(ws,m){ if (m==="hi") ws.send("ack"); }, ping(ws,data){ }, pong(ws,data){ } } });
+const ws = new WebSocket("ws://127.0.0.1:"+srv.port);
+const seen = [];
+for (const ev of ["open","message","close","error","ping","pong"]) ws.addEventListener(ev, e => seen.push(ev + (e.data!==undefined? ":"+String(e.data):"")));
+await new Promise(r => ws.addEventListener("open", r, {once:true}));
+ws.ping("x"); ws.send("hi"); await new Promise(r => setTimeout(r, 400));
+console.log(JSON.stringify({ bun: Bun.version, ping: typeof ws.ping, pong: typeof ws.pong, seen }));
+```
+
+Output: {"bun":"1.4.0","ping":"function","pong":"function","seen":["open","pong:x","message:ack"]}
+
diff --git a/devlog/_plan/260912_accounts/000_plan.md b/devlog/_plan/260912_accounts/000_plan.md
new file mode 100644
index 0000000000..df54929c99
--- /dev/null
+++ b/devlog/_plan/260912_accounts/000_plan.md
@@ -0,0 +1,48 @@
+# Accounts work is delivered as independent policy and lifecycle changes
+
+Readers: the integration maintainer deciding which PRs can land and which issue acceptance remains open. OAuth callback retirement is independent of pool scheduling; history precedes capacity estimation; dedicated native-main reauthorization precedes its dashboard control. Existing reset activation, reset-credit operation identity, and canonical Fake-IP transport are preserved and verified rather than reimplemented.
+
+## Execution contract
+
+Satisfy-spec HOTL, triggered by the accounts-lane delegation on 2026-09-12. Scope: PRs #4280/#4080 and issues #3375/#3376/#4211/#3781/#3898. Goal: reviewed, attributed implementation PRs and final-tip hosted CI evidence with truthful remaining acceptance. Non-goals: merges, releases, service/account/config/network changes, native GitHub stacks, local product test execution of any size, heavy local build/typecheck/install. Existing credential/tool scope only; no user-imposed token/time/agent-count cap.
+
+Verification: source inspections and `git diff --check` are text checks only; regression test sources run on GitHub-hosted CI at each final cumulative tip. Intermediate cycle C records source review and deferred remote evidence, never local test passes. Stop: all implementation/disposition and final CI criteria met, or actual inaccessible field acceptance distinctly recorded. Outcomes: DONE for demonstrated delivered scope; PARTIAL/NEEDS_HUMAN for authenticated field or maintainer security acceptance still missing; actual tool rejections retained without bypass. Main owns implementation; inherited-model read-only agents advise on design, reflect the concrete plan, and independently audit A. No native architect role is exposed, so none is claimed. No extra setup is required by that limitation.
+
+Memory artifacts: this numbered unit, session-bound goalplan/ledger, and task-local `.tmp/accounts-20260912/000_handoff.md`. Security analysis stays only in scratch. Escalation: actual tool permission denial or new out-of-scope action; main reclaims failed read-only work after two distinct failed dispatches, retaining any independence gap.
+
+## Delivery map
+
+| Cycle | Outcome | Dependency | Branch relationship |
+| --- | --- | --- | --- |
+| roadmap | Lock these documents, no product edit | none | local docs checkpoint |
+| callback | Carry latest #4280 with author credit | roadmap | independent dev PR |
+| eligibility | Automatic pool selection honors excluded plans; explicit route preserved | roadmap | independent dev PR |
+| reset | Carry #4080 reset-first ordering | roadmap | independent dev PR |
+| generic-family | Family headroom and cooldown context | roadmap | independent dev PR |
+| lifecycle | Generic affinity and classified recovery | generic-family | child of generic-family |
+| generic-health | Selection reasons and health presentation | lifecycle | child of lifecycle |
+| warmup | Durable one-shot zero-usage activation | roadmap | independent dev PR |
+| history | Bounded raw quota observations, generation-safe retention | roadmap | independent dev PR |
+| capacity | Estimated capacity with evidence/sample count | history | child of history |
+| tun | Safe probe failure classification and consumer projection | roadmap | independent dev PR |
+| reauth-api | Dedicated native-main device grant persistence and CLI | roadmap | independent dev PR |
+| reauth-ui | Main-card start/poll/cancel | reauth-api | child of reauth-api |
+| final | Repair hosted final-tip CI, collect reviews and disposition | all implementation | no merge |
+
+Per-phase decade documents carry before/after contracts and conditional acceptance. Every later P revalidates source anchors. Ordinary manual chains express only real dependencies. `.github/workflows/ci.yml` runs pull_request without a base filter; no workflow modification or cancellation is authorized. Source ownership comes from `structure/manifest.json` and `structure/INDEX.md`; update all owners when their area changes, preserving relevant facts with cross-links.
+
+## Current evidence and limitations
+
+Baseline `origin/dev`: 69e3dcda755a52feb1327edad6c8ea6cefd6e871. PR #4280 live head: 1f826d92c7205f31ce174bbd987c04b2b08f7da4; its follow-up includes 404 closure and all three OAuth structure owners. PR #4080 live head: ecf6b4e48a4c2992c296fada2caf6a8132313eaa. Both remain open. Fresh source/issue snapshots are in scratch; historic CI claims in PR bodies are contributor evidence only.
+
+`cxc map src/codex --limit 18` is unavailable in the installed plugin (requires a source checkout); use source ownership and bounded text searches instead. Session is bound to this managed worktree and host goal exists; hooksVerified=false does not prove Stop continuation. Local tests/build/typecheck/install: NOT RUN. Authenticated TUN field acceptance cannot be inferred from injected-DNS tests.
+
+## Source reconciliation decisions
+
+#4238 already implements the excludedPlans selector; this unit completes reasons and removes automatic all-excluded fallback, preserving explicit routing and native-main exemption. #2562 latest maintainer comment chooses generic pooling, so both Google-specific routers remain design inputs. Generic work is split into family context → lifecycle → health presentation; a separate warmup cycle covers one-shot zero-usage scheduling. These units are registered in the same goalplan. #3588 reset activation and manual reset operation-id are already implemented.
+
+Two design follow-ups encountered inherited-model capacity errors; one same-handle retry was requested, no model/settings were changed. Independent A audit remains required.
+
+## Roadmap cycle outcome
+
+Independent design reflection and A re-audit passed with the source restrictions in 001_roadmap_audit.md. B freezes the contracts as documentation only. C checks document paths/numbering and git whitespace; local product suites NOT RUN. D next direction: execute 010_callback.md independently, then the remaining dependency-ordered cycles. Runtime behavior has not improved yet; the rejected hypotheses were native history identity by sentinel alone, attempt timing inferred from untimed attempts, and one-shot implying one physical request through a retrying primitive.
diff --git a/devlog/_plan/260912_accounts/001_roadmap_audit.md b/devlog/_plan/260912_accounts/001_roadmap_audit.md
new file mode 100644
index 0000000000..794bd2144f
--- /dev/null
+++ b/devlog/_plan/260912_accounts/001_roadmap_audit.md
@@ -0,0 +1,11 @@
+# Roadmap audit locks implementation boundaries
+
+The source audit separates landed work from remaining acceptance. Pool design reflection (Pauli), eligibility/native-main reflection (Singer), and TUN reflection (Faraday) all aligned after concrete amendments. These are inherited-model independent reads; no native architect role or runtime execution is claimed.
+
+Independent A reviewer Leibniz found three blockers: native history identity across offline login replacement, capacity attempt timing and truncated ledger attribution, and a warmup primitive that retries despite a one-attempt promise. Main accepted all three. Native history is not persisted in this slice, stored-pool history binds generation, capacity uses whole contained request intervals and rejects incomplete evidence, and scheduled warmup explicitly disables model fallback. Focused re-audit returned VERDICT: PASS on 2026-09-12, against 69e3dcda755a52feb1327edad6c8ea6cefd6e871.
+
+Reader result: separate PRs deliver callback transport, policy reasons/selection, reset ordering, generic lifecycle, quota history/capacity, diagnostic classification, and native-main reauth. Source-backed findings justify each slice; next step is the independent callback implementation cycle. No implementation or remote verification exists yet. Local tests/build/typecheck/install: NOT RUN by user instruction. Source and doc checks do not establish runtime behavior.
+
+Remaining acceptance constraints: authenticated TUN field evidence; native-main cross-restart history/token capacity intentionally omitted; generic recovery requires positive provider/post-refresh evidence (permanent refresh rejection and sidecar auth without such evidence stay terminal); one-shot warmup supports stored pool only. All remain visible in final issue dispositions and are not silently marked complete.
+
+C correction: first git diff --cached --check rejected spaces in blank lines of the quoted public patch, so the chained commit did not run. Those documentation-only spaces were removed before retry. The B-to-C narrative mentioned a commit prematurely; the actual commit and receipt follow this correction.
diff --git a/devlog/_plan/260912_accounts/010_callback.md b/devlog/_plan/260912_accounts/010_callback.md
new file mode 100644
index 0000000000..57cb4130c8
--- /dev/null
+++ b/devlog/_plan/260912_accounts/010_callback.md
@@ -0,0 +1,239 @@
+# Retire every OAuth callback response connection
+
+Cycle callback; C4 auth transport. Independent of account pool features. Existing public #4280 is the change source; source read: `src/oauth/callback-server.ts:177`, `tests/oauth/oauth-callback-server.test.ts:1`. No-op leaves pooled connections reaching retired handlers; reuse the contributor patch rather than introduce a second listener implementation.
+
+MODIFY `src/oauth/callback-server.ts`: add private `closingResponse(body, status, contentType = "text/html")`; both 404 and callback success/error return it. Before: ordinary Response headers contain only Content-Type, 404 has no explicit headers. After: each path includes `Connection: close`; state validation and graceful listener shutdown stay intact.
+MODIFY `tests/oauth/oauth-callback-server.test.ts`: sequential fixed-port login and held-exchange favicon scenarios from #4280, with deterministic flow-publication barriers and cancellation cleanup rather than new polling sleeps.
+MODIFY `structure/runtime.md`, `structure/transports/inventory.md`, `structure/providers/xai-grok.md`: carry the contributor's invariant and owner links. Public troubleshooting docs describe repeat login connection retirement if needed.
+
+The exact reviewed public diff is reproduced below as the implementation contract. Credit: Co-authored-by: luvs01 <27862058+luvs01@users.noreply.github.com>. Retain latest source author commits in provenance; no original PR edits/closure.
+
+```diff
+diff --git a/src/oauth/callback-server.ts b/src/oauth/callback-server.ts
+index dc49d5fcd2..2727f8362c 100644
+--- a/src/oauth/callback-server.ts
++++ b/src/oauth/callback-server.ts
+@@ -37,6 +37,27 @@ function errorHtml(message: string): string {
+
+ export type CallbackResult = { code: string; state: string };
+
++/**
++ * Every response this listener sends ends its connection.
++ *
++ * The preferred callback port is FIXED per provider, so a later login listens on the same
++ * number — but a keep-alive socket stays bound to the flow that served it, and stopping that
++ * listener does not close an already-established connection. A client reusing the socket would
++ * hand the NEXT login's callback to the RETIRED flow, which rejects the unknown state as a CSRF
++ * mismatch while the live flow waits for a callback it can no longer receive.
++ *
++ * This is not limited to the callback itself: a browser that fetches `/favicon.ico` after the
++ * success page pools the socket on the 404, which is why the policy belongs to EVERY response
++ * rather than the callback path. Nothing here benefits from reuse — exactly one callback is
++ * expected per flow — so route every response through this helper.
++ */
++function closingResponse(body: string, status: number, contentType = "text/html"): Response {
++  return new Response(body, {
++    status,
++    headers: { "Content-Type": contentType, "Connection": "close" },
++  });
++}
++
+ /**
+  * The redirect URI advertised to providers must stay `localhost` (it is what the OAuth
+  * apps have registered), but Windows commonly resolves `localhost` to `::1` first while
+@@ -177,7 +198,7 @@ export abstract class OAuthCallbackFlow {
+   #handleCallback(req: Request, expectedState: string): Response {
+     const url = new URL(req.url);
+     if (url.pathname !== this.callbackPath) {
+-      return new Response("Not Found", { status: 404 });
++      return closingResponse("Not Found", 404, "text/plain");
+     }
+
+     const code = url.searchParams.get("code");
+@@ -214,10 +235,7 @@ export abstract class OAuthCallbackFlow {
+       });
+     }
+
+-    return new Response(ok ? SUCCESS_HTML : errorHtml(errMessage), {
+-      status: ok ? 200 : consumeFlow ? 500 : 400,
+-      headers: { "Content-Type": "text/html" },
+-    });
++    return closingResponse(ok ? SUCCESS_HTML : errorHtml(errMessage), ok ? 200 : consumeFlow ? 500 : 400);
+   }
+
+   #waitForCallback(expectedState: string): Promise<CallbackResult> {
+diff --git a/structure/providers/xai-grok.md b/structure/providers/xai-grok.md
+index 765b85a763..16d1322412 100644
+--- a/structure/providers/xai-grok.md
++++ b/structure/providers/xai-grok.md
+@@ -15,6 +15,10 @@ Grounded in the open-sourced official client (xai-org/grok-build); unit + eviden
+   `~/.grok/auth.json` (read-only) before any refresh and adopt a newer usable generation with
+   zero IdP calls (`shouldAdoptGrokGeneration`, later-expiresAt authority); an IdP refresh
+   detaches the credential to `source:"oauth"`.
++- **Browser login callback:** Grok's browser login uses the shared `OAuthCallbackFlow` listener
++  on a per-provider FIXED loopback port, so every response it sends closes its connection. A
++  retired flow that kept a pooled socket would capture the NEXT login's callback and reject it
++  as a state mismatch; see `src/oauth/callback-server.ts`.
+ - **Two-lock refresh transaction:** per-provider+account intent lock held across the IdP
+   exchange plus a short global store-write lock + async mutation funnel around every
+   `auth.json` load-merge-persist (`src/oauth/store.ts`); generation-guarded persist
+diff --git a/structure/runtime.md b/structure/runtime.md
+index 3099c13bfd..f31080646d 100644
+--- a/structure/runtime.md
++++ b/structure/runtime.md
+@@ -139,7 +139,7 @@ The server exposes `POST /api/stop` which restores native Codex config, stops an
+ | --- | --- |
+ | `src/providers/registry.ts` | Canonical provider presets for CLI, dashboard, OAuth, key providers, and metadata. |
+ | `src/providers/derive.ts` | Enrichment from provider presets into user config. |
+-| `src/oauth/` | OAuth providers, token storage, refresh, and auth-token resolution. |
++| `src/oauth/` | OAuth providers, token storage, refresh, and auth-token resolution. The login callback listener binds a per-provider FIXED loopback port, so consecutive logins reuse the same number; every response it sends ends its connection (`Connection: close`, including non-callback paths such as a stray `/favicon.ico` 404). Stopping the listener does not close an established socket, so without that a pooled client would deliver the next login's callback to the retired flow, which rejects the unknown state as a CSRF mismatch while the live flow waits. |
+ | `src/adapters/openai-responses.ts` | Native OpenAI/ChatGPT Responses passthrough. |
+ | `src/adapters/openai-chat.ts` | OpenAI-compatible Chat Completions bridge. |
+ | `src/adapters/anthropic.ts` | Anthropic Messages bridge. |
+diff --git a/structure/transports/inventory.md b/structure/transports/inventory.md
+index dc9af564d6..11cb227b01 100644
+--- a/structure/transports/inventory.md
++++ b/structure/transports/inventory.md
+@@ -20,6 +20,7 @@ surface is listed here so a maintainer can find the owner without grepping:
+ | GitHub Copilot | `src/providers/xai-transport.ts` (`resolveProviderTransport`), `src/providers/github-copilot-transport.ts` | `resolveProviderTransport` selects the Copilot transport when the routed provider name is `github-copilot`; the Copilot module then resolves its headers and base URL, and the registry seeds the provider row and model fallback. |
+ | API-key pools | `src/providers/api-key-selection.ts`, `src/providers/key-failover.ts` | A 429 rotates the active key and records a cooldown; `provider.apiKey` keeps mirroring the active entry so routing stays single-key. |
+ | OAuth account failover | `src/oauth/generic-account-failover.ts`, `src/oauth/anthropic-routing.ts` | Reactive pre-output 429 recovery is presence-driven with 2+ eligible accounts. Pool and `oauthAccountFailover` flags govern proactive routing, not the reactive retry: a disabled Anthropic pool recovers through quota ordering rather than its dormant strategy, and a per-provider `enabled` beats the global default in either direction. |
++| OAuth login callback (inbound) | `src/oauth/callback-server.ts` | The only inbound transport this area owns: a short-lived loopback listener on a per-provider FIXED port. Exactly one callback is expected per flow, so EVERY response closes its connection — a retired flow must never keep a pooled socket that would capture the next login's callback. |
+ | Alibaba regions | `src/providers/alibaba-region-backup.ts`, `src/providers/alibaba-region-migration.ts`, `src/providers/alibaba-region-startup.ts` | Region migration backs up before rewriting and is idempotent across restarts. |
+ | Discovery and quota | `src/providers/model-discovery.ts`, `src/providers/quota.ts` | Discovery rejects a response over 4 MiB or past 2,000 raw rows before caching it. |
+
+diff --git a/tests/oauth/oauth-callback-server.test.ts b/tests/oauth/oauth-callback-server.test.ts
+index a327e1df0d..a46a2a04f3 100644
+--- a/tests/oauth/oauth-callback-server.test.ts
++++ b/tests/oauth/oauth-callback-server.test.ts
+@@ -29,6 +29,16 @@ class ManualFallbackFlow extends OAuthCallbackFlow {
+
+ const ctrl: OAuthController = {};
+
++/** Keeps the listener alive across the token exchange so stray requests can reach it. */
++class SlowExchangeFlow extends ManualFallbackFlow {
++  holdExchange?: Promise<void>;
++
++  override async exchangeToken(code: string, state: string, redirectUri: string): Promise<OAuthCredentials> {
++    await this.holdExchange;
++    return super.exchangeToken(code, state, redirectUri);
++  }
++}
++
+ describe("OAuth callback server defaults", () => {
+   test("binds callback listeners to numeric loopback by default", () => {
+     const flow = new TestFlow(ctrl, 54545, "/callback");
+@@ -116,4 +126,103 @@ describe("OAuth callback server defaults", () => {
+       blocker.stop(true);
+     }
+   });
++
++  test("a retired flow cannot serve the next login on the same callback port", async () => {
++    // The preferred callback port is fixed per provider, so consecutive logins listen on the
++    // same number. Stopping a listener does not close a connection that is already open, so a
++    // client that pools the socket would deliver the SECOND login's callback to the FIRST
++    // flow, which rejects the unknown state as a CSRF mismatch while the live flow waits.
++    const port = await freeLoopbackPort();
++    const options = {
++      preferredPort: port,
++      callbackPath: "/callback",
++      callbackHostname: "127.0.0.1",
++      callbackBindHostname: "127.0.0.1",
++    };
++    const deliver = async (state: string): Promise<number> => {
++      const url = new URL(`http://127.0.0.1:${port}/callback`);
++      url.searchParams.set("code", "authorization-code");
++      url.searchParams.set("state", state);
++      const res = await fetch(url);
++      await res.text();
++      return res.status;
++    };
++
++    const first = new ManualFallbackFlow(ctrl, options);
++    const firstLogin = first.login();
++    await waitForState(() => first.generated?.state);
++    const firstState = first.generated!.state;
++    expect(await deliver(firstState)).toBe(200);
++    await firstLogin;
++
++    const second = new ManualFallbackFlow(ctrl, options);
++    const secondLogin = second.login();
++    await waitForState(() => second.generated?.state);
++    const secondState = second.generated!.state;
++    expect(secondState).not.toBe(firstState);
++    // Served by the LIVE flow, so the retired state is now an unknown one.
++    expect(await deliver(firstState)).toBe(400);
++    expect(await deliver(secondState)).toBe(200);
++    await secondLogin;
++    expect(second.exchanged?.state).toBe(secondState);
++  });
++
++  test("a non-callback request cannot pin the socket to the retiring flow", async () => {
++    // A browser that asks for /favicon.ico after the success page would pool the socket on the
++    // 404 while exchangeToken() is still running, which re-pins it to the flow that is about to
++    // retire. The close policy therefore belongs to EVERY response, not just the callback path.
++    const port = await freeLoopbackPort();
++    const options = {
++      preferredPort: port,
++      callbackPath: "/callback",
++      callbackHostname: "127.0.0.1",
++      callbackBindHostname: "127.0.0.1",
++    };
++    const deliver = async (state: string): Promise<number> => {
++      const url = new URL(`http://127.0.0.1:${port}/callback`);
++      url.searchParams.set("code", "authorization-code");
++      url.searchParams.set("state", state);
++      const res = await fetch(url);
++      await res.text();
++      return res.status;
++    };
++
++    // The exchange is held open so the listener is still up for the stray request, which is
++    // exactly the window the reproduction describes.
++    const exchanging = Promise.withResolvers<void>();
++    const first = new SlowExchangeFlow(ctrl, options);
++    first.holdExchange = exchanging.promise;
++    const firstLogin = first.login();
++    await waitForState(() => first.generated?.state);
++    expect(await deliver(first.generated!.state)).toBe(200);
++    const favicon = await fetch(`http://127.0.0.1:${port}/favicon.ico`);
++    await favicon.text();
++    expect(favicon.status).toBe(404);
++    exchanging.resolve();
++    await firstLogin;
++
++    const second = new ManualFallbackFlow(ctrl, options);
++    const secondLogin = second.login();
++    await waitForState(() => second.generated?.state);
++    // Without the close policy on the 404 this is answered by the retired flow and returns 400.
++    expect(await deliver(second.generated!.state)).toBe(200);
++    await secondLogin;
++    expect(second.exchanged?.state).toBe(second.generated!.state);
++  });
+ });
++
++/** A port that is free right now; the flows bind it themselves, so it must not stay held. */
++async function freeLoopbackPort(): Promise<number> {
++  const probe = Bun.serve({ hostname: "127.0.0.1", port: 0, reusePort: false, fetch: () => new Response("probe") });
++  const { port } = probe;
++  probe.stop(true);
++  return port;
++}
++
++async function waitForState(read: () => string | undefined, timeoutMs = 5_000): Promise<void> {
++  const deadline = Date.now() + timeoutMs;
++  while (read() === undefined) {
++    if (Date.now() >= deadline) throw new Error("timed out waiting for the login flow to publish its state");
++    await Bun.sleep(5);
++  }
++}
+
+```
+
+Acceptance: first login succeeds, retired state is rejected by live listener (400), live state succeeds (200); favicon during held token exchange returns 404 without trapping the next flow. Failure/malformed callback paths close their connection too. Regression source is mandatory, local runtime execution NOT RUN. Hosted final-tip CI must cover oauth callback/bind and OrcaRouter provider suites. Security review checks unchanged state/PKCE, loopback destinations, no credential disclosure. Public code already describes the issue; additional security analysis goes to scratch only.
+
+P stale check: whole contributor patch fails only at inventory table context because the API-key row changed. Selected source/test/runtime/xai hunks pass `git apply --check`. During B retain current inventory rows and append the new callback row after OAuth failover manually; do not overwrite current transport contracts.
+
+Callback P revalidation after roadmap D: next direction is independent callback carry. Source hunks still apply; #4280 remains open at the same 1f826d92c head. Replace contributed polling helper with onAuth Promise.withResolvers readiness, AbortController deadline and finally cleanup settling held exchanges and login promises. Keep runtime Connection: close unconditional for both paths; no forced fetch header masks the defect. Shorten helper comment while preserving retirement rationale. Native role unavailable; inherited-model consultation is explicitly authorized. Product tests NOT RUN; source audit then remote CI.
+
+Callback design ALIGNED (Lagrange) and independent A PASS (Leibniz): readiness resolves in onAuth queueMicrotask, login rejection rejects readiness; deadlines armed after handler registration; finally resolves held exchange, aborts flows, clears timers and settles login promises. Add response-only close-header checks alongside behavioral oracles.
diff --git a/devlog/_plan/260912_accounts/011_callback_delivery.md b/devlog/_plan/260912_accounts/011_callback_delivery.md
new file mode 100644
index 0000000000..23fa061b4a
--- /dev/null
+++ b/devlog/_plan/260912_accounts/011_callback_delivery.md
@@ -0,0 +1,9 @@
+# Callback retirement implementation and evidence
+
+Carried #4280 at 1f826d92c7205f31ce174bbd987c04b2b08f7da4 by luvs01. Every callback-listener response uses a closing response helper; state validation, HTML escaping and graceful shutdown stay unchanged. Runtime, xAI and transport inventory ownership docs are updated. Tests retain two fixed-port flow scenarios and add malformed/provider-error response checks; onAuth microtask readiness and per-flow abort/finally cleanup replace polling waits.
+
+Necessity/source search: closingResponse and loopbackBindHostnames in callback-server.ts; no existing response-closing owner found. Reuse existing OAuthCallbackFlow and ManualFallbackFlow. The only new production helper is private and joins two response sites. Local tests/build/typecheck/install: NOT RUN. git diff --check is a whitespace check only. Independent implementation/security read and hosted CI follow publication; no bug-fixed claim until execution evidence exists.
+
+This first delivery includes the accounts roadmap documentation checkpoint; product delta is callback-only. Other features remain unimplemented and their docs describe pending work. Original #4280 stays open for coordinator disposition after integration. No merge is performed here.
+
+Co-authored-by: luvs01 <27862058+luvs01@users.noreply.github.com>
diff --git a/devlog/_plan/260912_accounts/020_eligibility.md b/devlog/_plan/260912_accounts/020_eligibility.md
new file mode 100644
index 0000000000..94719a4f58
--- /dev/null
+++ b/devlog/_plan/260912_accounts/020_eligibility.md
@@ -0,0 +1,19 @@
+# Finish automatic plan policy and visible exclusion reasons
+
+Cycle eligibility; C3 selection policy. Depends only on roadmap, independent dev PR. #4238 already added excludedPlans; do not reimplement its selector. Source: routing.ts:1044-1090 and 1326; explicit fixedAccountId path auth-context.ts:826/915.
+
+MODIFY `src/codex/routing.ts`: export the existing normalized policy predicate (or move the pure plan calculation into `src/codex/plan.ts` and reuse it). Add the predicate to BOTH configured-account fallback guards at preview :2152 and detailed resolve :2391. Before, an all-excluded pool returns its excluded active row; after, ordinary selection returns null/none. Explicit fixed routes retain existing auth, pause, entitlement checks. Native __main__ remains exempt, avoiding physical auth reads on selection-only paths.
+
+```diff
+- && !isCodexAccountPaused(config, active)
++ && !isCodexAccountPaused(config, active)
++ && !isCodexAccountPlanExcluded(config, active)
+```
+
+MODIFY `src/codex/auth-api.ts`: poolAccountDto adds optional `selectionExcludedReason: "plan_excluded"`, derived from the SAME predicate and config, never from credential health; include current plan already in DTO. MODIFY `src/cli/account-api.ts` AccountRow/CodexAccountDto mapping and `src/cli/account.ts` statusText to show `not-auto-selected(plan=<plan>)`. MODIFY `gui/src/components/codex-account-pool-types.ts`, pool-card badge in `codex-account-pool-cards.tsx`, and all locale catalogs: separate localized reason; do not mutate paused/needsReauth and do not disable explicit routing. Unknown plan and empty policy remain eligible; reauth renewal clears the reason dynamically.
+
+Field chain: existing excludedPlans config create/save/load → same normalized predicate → account DTO JSON → CLI/GUI optional union → status and badge. No new config field or minimumPlan ordering. Enforcing tier: runtime automatic selection only; explicit fixed account intentionally bypasses this selection rule, not auth; residual unknown-plan and native-main exemptions documented, no hard account-block claim.
+
+MODIFY existing `tests/codex-integration/codex-pool-plan-exclusion.test.ts`: replace last-account soft fallback test with none/preview none; test normalized plan update and explicit fixed route. Extend account API/CLI and card tests for reason and renewal clearing. Sync ownership docs and providers configuration pages that describe the old soft exception. Retain source attribution of #4238; no recarry of already-landed commits. Local tests/build/typecheck NOT RUN. Hosted CI plus rendered artifact from final tip supplies execution proof.
+
+Exclusion reason derives from the routing config plan, not a display-only freshly observed plan if persistence failed. This preserves truth between selection and explanation.
diff --git a/devlog/_plan/260912_accounts/030_reset.md b/devlog/_plan/260912_accounts/030_reset.md
new file mode 100644
index 0000000000..875a6dccc5
--- /dev/null
+++ b/devlog/_plan/260912_accounts/030_reset.md
@@ -0,0 +1,16 @@
+# Add Codex reset-first through the canonical pool settings API
+
+Cycle reset; C3 scheduling. Independent of quota history and eligibility. Carry #4080 at ecf6b4e48a4c2992c296fada2caf6a8132313eaa, credited to Terry Tan <tmy1995hflc@gmail.com>. Its public diff is a design input, with mandatory canonical-contract adaptation below. Do not enable reset-first for Anthropic or generic OAuth pools.
+
+MODIFY source paths in #4080: `src/codex/routing.ts`, `src/codex/pool-rotation.ts`, `src/codex/auth-api.ts`, `src/types/config.ts`, `src/cli/account-extended.ts`, `src/cli/account.ts`; retain existing priority, eligibility, threshold, and healthy affinity. New Codex strategy sorts earliest FUTURE short/weekly reset after filtering, then usage and stable order. Unknown/elapsed reset is not preferred. Threshold zero disables usage filtering while retaining ordering; exhausted-account behavior remains existing safe fallback.
+
+Additional MODIFY `src/oauth/pool-settings-capability.ts` and `src/server/management/oauth-account-routes.ts`: use a Codex-specific parser that accepts reset-first; canonical PUT /api/pool/settings and GET normalization must preserve it. Generic/Anthropic parsers keep rejecting reset-first. Update `gui/src/account-pool-strategy.ts`, strategy controls/settings, `gui/src/pool-settings.ts` types, locale translations and config docs from #4080 for the canonical route.
+
+```diff
+- strategy: normalizeAccountPoolStrategy(config.accountPoolStrategy)
++ strategy: normalizeCodexAccountPoolStrategy(config.accountPoolStrategy)
+```
+
+Field chain: CLI/GUI strategy creation → canonical PUT parser → config.accountPoolStrategy write → config load + canonical GET parser → pool rotation/preview/failover, CLI and GUI display. Audit every existing strategy comparison/default, not just the union. No schema migration or new dependency. Exact contributor diff remains `.tmp/accounts-20260912/pr4080.diff` during planning; changes are adapted to current callers before B.
+
+Extend regression sources for canonical PUT/GET/save/reload, legacy endpoint, non-Codex rejection, tied/missing/elapsed resets, threshold zero, priorities, affinity and failover. Existing #4080 test cases are retained/adapted. Update all source ownership docs; screenshot of final rendered strategy control is included with PR. Local suites/build/typecheck/install NOT RUN; final head hosted CI supplies proof. #3376 remains partial until history/capacity; monthly/Anthropic/latest-first scope is reported separately.
diff --git a/devlog/_plan/260912_accounts/040_generic_family.md b/devlog/_plan/260912_accounts/040_generic_family.md
new file mode 100644
index 0000000000..24ee77cfc8
--- /dev/null
+++ b/devlog/_plan/260912_accounts/040_generic_family.md
@@ -0,0 +1,16 @@
+# Scope generic quota evidence and cooldowns by model family
+
+Cycle generic-family; C3, foundation for lifecycle. Extend existing generic pool; do not stack Google-specific #2562/#3283. Current `src/oauth/generic-account-failover.ts:200` already activates kernel strategies; quota threshold remains unused. #4299 narrow head 4583f9793295f75d4bf69d0bfb0900a550bc05bd supplies family-ranking input; adapt with Co-authored-by: chilung <b0423031@gmail.com> when reused.
+
+MODIFY `src/oauth/account-quota-rank.ts`: optional requested-model context chooses matching Antigravity Gem/Cla windows only, preserving no-model existing behavior and conservative unknown evidence. MODIFY generic-account-failover.ts health key/eligibility/ranking/fill-first: quota cooldown key is provider+account+known family, auth failures remain global. Thread model context into both kernel fill-first headroom and quota branch. `autoSwitchThreshold` is consumed by quota selection; zero disables proactive usage threshold, not upstream exhaustion. Reactive quorum activation stays unchanged; provider/global flags affect proactive preference only.
+
+```ts
+type GenericQuotaScope = "account" | "gemini" | "claude";
+type GenericSelectionContext = { modelId?: string; sessionKey?: string; now: number };
+```
+
+MODIFY `src/server/responses/core.ts` initial preference and every generic retry site to pass actual routed modelId; snapshot admission remains guarded and uses account-matched routing metadata. No extra Lab import. Field chain: route.modelId creation → in-memory context only → no disk serialization → headroom and health scope consumers. No provider error body's arbitrary string is allowed as a family identifier; family mapping is bounded known model semantics.
+
+Extend existing generic failover and account quota rank tests, plus a real handleResponses regression with opposing Gem/Cla windows. Assert Claude quota cooldown leaves Gemini usable, global auth exclusion blocks both, unknown model remains conservative, threshold zero semantics, kernel fill-first consumes same family. Sync `src/oauth/`, `src/server/` ownership docs and operating config docs. Local runtime suites NOT RUN; hosted final cumulative lifecycle tip verifies the foundation.
+
+Reflection REF-01 accepted. GenericQuotaScope is account|gemini|claude. GenericSelectionContext carries modelId?, sessionKey?, now. Thread it through headroom/exhaustion/ranking/eligibility/fill-first/initial-preference/rotation/Retry-After. Global cooldown blocks every family; known-family cooldown blocks that family; unknown context considers all relevant cooldowns. Clear/reconcile removes every scope. Core anchors: initial 4350; rotation 5542,6480,6853,7587,7998; refresh 5420,7377; admission 4054,4149,4413. Revalidate anchors at each P. Sidecar uses its actual routed model identity; absence uses account-conservative quota scope.
diff --git a/devlog/_plan/260912_accounts/041_generic_lifecycle.md b/devlog/_plan/260912_accounts/041_generic_lifecycle.md
new file mode 100644
index 0000000000..322a2fcaea
--- /dev/null
+++ b/devlog/_plan/260912_accounts/041_generic_lifecycle.md
@@ -0,0 +1,25 @@
+# Bind admitted generic accounts and classify recoverable failures
+
+Cycle lifecycle depends on generic-family. C4 credential/retry. Existing owners: `generic-account-failover.ts`, `oauth/store.ts`, `server/responses/core.ts:4054/4149/5537`, `oauth/anthropic-routing.ts:759` provides a commit-after-resolution precedent.
+
+MODIFY generic-account-failover.ts: bounded process-local conversation affinity keyed by provider/session identity, with explicit idle TTL and entry cap; no conversation id means no affinity. Look up only live non-reauth accounts, release on expiry/removal/credential-generation change or classified failure, bind admitted account after guarded snapshot application rather than proposal. Extend note-success/selection context to carry actual account generation. Preserve explicit account selectors and manual active selection semantics; never persist conversation bodies.
+
+MODIFY existing generic recovery branches in core.ts: retain one same-request retry budget and existing no-output replay boundary. Handle only post-refresh account authentication rejection and provider-classified quota/account 403; ordinary permission/region/policy 403 stays terminal. Classifier uses existing provider error/code owners, not arbitrary text heuristics. Auth failure marks only rejected credential generation unhealthy, quota failure records family cooldown. Retry snapshot token/project/routing metadata must all describe the chosen account.
+
+```ts
+// The exact evidence-discriminated GenericOAuthFailure union is specified below.
+```
+
+No stored broad rotateOn flag is introduced until its every consumer is grounded; defaults express only classified safe recovery. Field chain: adapter response classifier → internal failure object → existing recovery dispatch (not persisted credentials) → health/affinity invalidation and request attempt recovery marker. Add a bounded explicit recovery-kind union only if required, update log normalizer/GUI label/serialization together.
+
+Tests: multi-turn affinity holds; removal/reauth/expiry releases; proposed stale credential never binds; post-refresh 401 rotates one account; quota-classified 403 rotates; unrelated 403 does not; no rotation after downstream output; budget exhaustion terminates; initial and continuation paths match. New test files join both layout registries. Credential threat model and draft details stay in `.tmp/`; public unit contains safe design only. All source ownership docs updated. Local tests NOT RUN; hosted final cumulative tip plus independent security review required.
+
+Reflection REF-01 overrides the earlier broad failure type and family-affinity key. Affinity is provider+session, not family: a model change retains account if eligible for that family, otherwise releases it. Cap 2048 entries, idle TTL 30 minutes, prune on write and deletion/generation change. Context now is passed from one request clock. The only classified failure union is:
+```ts
+type GenericOAuthFailure =
+ | {kind:"terminal"}
+ | {kind:"auth"; status:401; evidence:"post-refresh-401"; generation:string}
+ | {kind:"auth"; status:403; evidence:"provider-account-credential"; generation:string}
+ | {kind:"quota"; status:403|429; scope:"account"|"gemini"|"claude"; retryAfter?:string};
+```
+First 401 uses existing refresh. Refresh transport error never marks unhealthy. Provider-account 403 requires existing closed code classification; when absent it is terminal. One request-wide recovery budget and unconditional client-output committed marker prohibits new dispatch after any output, including continuation and sidecar. Preserve sidecar quota-only callback unless its existing error contract can carry authenticated post-refresh evidence; record terminal auth limitation rather than invent evidence. Snapshot generation type is revalidated against OAuthAccessSnapshot before implementation.
diff --git a/devlog/_plan/260912_accounts/042_generic_health.md b/devlog/_plan/260912_accounts/042_generic_health.md
new file mode 100644
index 0000000000..464e6ea17e
--- /dev/null
+++ b/devlog/_plan/260912_accounts/042_generic_health.md
@@ -0,0 +1,13 @@
+# Show the existing pool's selection and health state
+
+Cycle generic-health depends on lifecycle. Existing pseudonymous account attribution at `src/providers/label.ts:41`, usage log serialization at `src/usage/log.ts:554`, summaries at `src/usage/summary.ts:1237` are reused, not recreated.
+
+MODIFY existing OAuth health DTO/projector and `src/server/management/oauth-account-routes.ts` to expose bounded selection reason and health/cooldown scope alongside per-account quota. MODIFY `gui/src/hooks/useProviderAccountPools.ts` typed account projection, shared current/all-account card renderer and locale catalogs for reason. CLI account status uses same closed reason. Aggregate pool counts by healthy/cooling/reauth and known/unknown quota; do not sum unlike family/window percentages into fictitious capacity.
+
+```ts
+type GenericSelectionReason = "affinity" | "manual" | "quota" | "round-robin" | "fill-first" | "auth-failover" | "quota-failover";
+```
+
+Creation: admitted generic selector; serialization: authenticated account DTO and required per-attempt usage history; deserialization: typed optional client fields; consumers: status/account card/aggregate counts. No raw user/account/credential identifiers added to logs. Tests cover missing legacy fields, successful recovery clearing error, removed accounts, family-specific cooldown display and stale response merge. Source/structure/user docs align. Local suites/build NOT RUN; hosted final cumulative tip and rendered account card required.
+
+Reflection REF-02 accepted: request-history reason is REQUIRED. Add optional accountSelectionReason/accountQuotaScope to PersistedUsageAttempt in src/usage/log.ts and normalize/serialize closed unions. Stamp after admission per attempt in src/server/request-log.ts and core, preserving prior attempts. Update request-history API/client detail renderer and all localized labels. Legacy rows omit safely. Regression source covers persistence/reload, multi-account retries, and no overwrite of earlier reason.
diff --git a/devlog/_plan/260912_accounts/045_warmup.md b/devlog/_plan/260912_accounts/045_warmup.md
new file mode 100644
index 0000000000..bd8d304f47
--- /dev/null
+++ b/devlog/_plan/260912_accounts/045_warmup.md
@@ -0,0 +1,21 @@
+# Schedule one zero-usage account activation durably
+
+Cycle warmup independent of generic lifecycle. Existing `src/codex/quota-auto-refresh.ts` persists reset-boundary activation in codexQuotaAutoRefresh (#3588); preserve it. `src/quota/reset-seen-store.ts` owns reset-observer baselines and deduplication only. `src/codex/warmup.ts` remains invocation owner. Stable reset-credit operation IDs already exist and need no replacement.
+
+Extend the existing activation scheduler/store with an explicit one-shot target timestamp for a selected zero-usage account, using codexQuotaAutoRefresh as specified below. Creation must be authenticated CLI/API with account identity, dueAt and stable operation handle; persist pending/running/completed state before dispatch. The exact schema and scheduler boundary are specified below. No live account warmup is executed in this task.
+
+Before: scheduler acts only on observed reset boundaries. After: a persisted one-shot request can activate a confirmed zero-usage eligible account at dueAt once, survives restart, and is cancelled/invalidated on account deletion or credential replacement. Never spend reset credits or infer user consent from login presence. Integration tests use injected clock/transport; assert duplicate submissions, restart, removal, failure/cancel, non-zero usage, and one dispatch at due time. All local suites NOT RUN. API/CLI contract and scheduler source owners updated; exact due-time semantics remain subject to source-grounded P revalidation.
+
+## Concrete scheduler contract
+
+Use `src/codex/quota-auto-refresh.ts:272` minute sweep and its existing `warmAccount` owner. MODIFY `src/types/config.ts:786` and strict `src/config.ts:931` entry schema with optional `oneShot: { operationId: string; dueAt: number; credentialGeneration: number; status: "pending" | "claimed" | "completed" | "uncertain" | "cancelled" | "failed" }`. This slice supports stored pool accounts only; native-main requires its separate ownership flow and is excluded. dueAt is finite milliseconds, future and within 30 days; operationId validated UUID. No new timer/store/service. Config persistence is the current scheduler authority, so claim synchronously with mutatePersistedConfig before dispatch; failure to persist causes no warmup. A claimed row after restart becomes uncertain and is not automatically retried. Completed/failed/cancelled state stays as one bounded row until explicit replacement; same operationId retries return that state.
+
+NEW dedicated strict handler `src/codex/warmup-schedule-api.ts` for PUT/GET/DELETE `/api/codex-auth/warmup-schedule` (account id request/query required), registered next to existing account routes. PUT validates current stored generation, non-paused/non-reauth/non-validation-pending pool membership and a fresh measured zero usage snapshot before writing. GET returns only operationId/dueAt/status; DELETE changes pending to cancelled and rejects claimed. CLI `ocx account warmup <account> --at <ISO> --operation-id <UUID>` is dispatched through existing `src/cli/account.ts` and `src/cli/account-auth.ts`; capability/help maps updated.
+
+At each due sweep, refresh stale quota first, then require all measured gating windows zero with no exhausted/unknown primary reading; recheck membership, current credential generation, plan eligibility and spending intent immediately before claim. Nonzero/mismatched/deleted accounts settle failed/cancelled without dispatch. One-shot does not enable recurring fiveHour/weekly booleans. At most one upstream attempt per operation: dispatch outcome settles completed/failed; crash after claim becomes uncertain for explicit operator reconciliation, never exactly-once success claimed. Recovery DTO/copy explains that claimed is not verified success. This avoids the impossible guarantee of atomically committing local config and remote spending.
+
+Field chain: strict API/CLI input→mutatePersistedConfig→strict config load→existing minute sweep→status read. New status values update every schema/consumer/default switch; deletion reconciliation removes account-owned schedule. Tests register both layout maps and cover API idempotence, nonzero/unknown quota, stale generation, restart pending versus claimed, failed persistence, cancellation and exactly one attempted dispatch with injected clock.
+
+Reflection REF-03: activation persistence is codexQuotaAutoRefresh, not reset-seen-store (observer only). Extend existing config-routes authenticated settings handling for schedule fields where possible; dedicated schedule handler delegates same validated mutation owner. Final oneShot status vocabulary is pending|claimed|completed|uncertain|cancelled|failed. Claimed on hydrate becomes uncertain; never automatic resend. Failed completion persistence retries the marker only, not upstream work. Concurrent recurring/one-shot due work shares one invocation under same eligible generation and uses same completion result. Tests add crash-after-claim/send, failed completion write, simultaneous due and cancellation during async metadata. This final vocabulary supersedes the earlier shorter type.
+
+A3 accepted: scheduled one-shot uses an explicit single-attempt option `allowModelFallback?: boolean` on CodexWarmupOptions in src/codex/warmup.ts. warmCodexAccount defaults remain unchanged; when false, propagate the first result and never enter FALLBACK_MODELS. Existing warmAccount passes false for a claimed one-shot (including shared recurring work); ordinary manual/recurring defaults retain existing bounded fallback. Test physical fetch call count on 400/404 and partial completion, not only warmAccount invocation count.
diff --git a/devlog/_plan/260912_accounts/050_history.md b/devlog/_plan/260912_accounts/050_history.md
new file mode 100644
index 0000000000..fab9e603be
--- /dev/null
+++ b/devlog/_plan/260912_accounts/050_history.md
@@ -0,0 +1,23 @@
+# Retain bounded raw quota observations
+
+Cycle history; C3 persistence. Independent of reset-first strategy. Source: `src/codex/quota.ts:265` commits merged snapshots, `:678` persists latest-only, `:735` clears; `src/codex/quota-types.ts:1` defines quota windows. New history attaches only after writer-generation and native-main identity guards. No new dependency or optional subsystem import on the core path.
+
+MODIFY `src/codex/quota.ts`: extend version-1 quota cache with optional bounded per-account history; store fresh raw observation fields (not carried windows) alongside updatedAt, and preserve explicit window reset identity. Credits-only writes do not append samples. Hydrate only validated bounded numeric rows, ignore malformed input, and deep-copy returned arrays. Bound both per-account samples (200) and retained age (30 days). Clear/reconcile removes matching history; unknown legacy files yield empty history. A stale main writer cannot append; native identity change clears old main observations before accepting new ones.
+
+Before:
+```ts
+type QuotaDiskFile = { version: 1; quotas: Record<string, StoredAccountQuota>; mainPolicyQuota?: MainPolicyQuota };
+```
+After:
+```ts
+type QuotaDiskFile = { version: 1; quotas: Record<string, StoredAccountQuota>; mainPolicyQuota?: MainPolicyQuota; history?: Record<string, StoredAccountQuota[]> };
+export function getAccountQuotaHistory(accountId: string): StoredAccountQuota[];
+```
+
+MODIFY `src/codex/auth-api.ts` account quota DTO to expose requested bounded history through a protected read route, preserving existing DTO compatibility. MODIFY CLI account quota read path to support history display/JSON with existing management transport. No secret/claim/tag is recorded; account key is the same local cache key, never an upstream bearer. Add tests in the existing quota cache test owner (or register a new domain test in both layout maps), plus protected API/CLI contract cases. Sync all `src/codex/` ownership docs using relevant statement or a cross-link; configuration docs explain retention and that snapshots alone do not establish token capacity.
+
+Field chain: creation is guarded quota commit; serialization is existing atomic quota-cache writer; deserialization is bounded validated hydrate; consumers are copied history getter, authenticated API/CLI, then capacity in the next cycle. Acceptance: old cache compatibility; 201 observations retain 200; credits-only and stale generations append none; different reset windows stay distinguishable; main identity change and removal discard old rows; corrupt/unbounded disk input is ignored/bounded. Local runtime checks NOT RUN; hosted quota/API/CLI regression suite at final history/capacity tip.
+
+Reflection REF-04: fixed aggregate bounds: 64 account identities, 4096 rows, 2 MiB serialized history payload and 4 MiB whole cache read bound. During append/hydrate evict oldest observed rows, tie-break account key; prune accounts absent from authoritative roster. Never include dynamic raw account identities in logs. History retains actual per-window provenance (response-header or WHAM where available), reset boundary and window family; partial inherited values do not count. Overlarge/malformed cache read fails to empty history without blocking newest quota. Tests include many-account overflow, byte overflow, deterministic ties and remove/restart.
+
+A1 accepted: native main history is deliberately NOT hydrated from disk in this slice. It can be sampled in-process only after identity observation and cleared on identity change; persistence omits __main__. Pool history envelopes bind stable configured account identity and stored credential generation, pruning mismatches on hydrate. This avoids attributing offline identity replacements to an old main label. Acceptance explicitly covers main replacement while stopped and account-id reuse. Main cross-restart history remains a documented limitation; bounded durable history is provided for stored pool accounts.
diff --git a/devlog/_plan/260912_accounts/060_capacity.md b/devlog/_plan/260912_accounts/060_capacity.md
new file mode 100644
index 0000000000..931e0b6646
--- /dev/null
+++ b/devlog/_plan/260912_accounts/060_capacity.md
@@ -0,0 +1,18 @@
+# Estimate observed effective capacity without claiming an upstream limit
+
+Cycle capacity depends on history. Source: `src/usage/log.ts` already persists accountLogLabel, timestamp, reported/estimated usage and per-attempt attribution; `src/codex/account-label.ts` owns safe labels. Use those existing records instead of storing credentials or duplicating request attribution.
+
+NEW `src/codex/quota-capacity.ts`: a pure estimator receives copied raw history and account-attributed reported usage observations. For each short/weekly/monthly window, pair adjacent fresh percentage observations only when reset identity matches, time increases and percentage delta is positive. Sum reported token usage in that interval, count per-attempt records once, exclude estimated/local/unattributed usage and reset/refund crossings. Estimate tokens per full window as observedTokens * 100 / percentageDelta; aggregate defensible intervals with median and report sampleCount plus observed-token lower-bound caveat. No valid interval returns null, never zero or a fabricated capacity. Bounded scan is invoked on management request, never routing; estimation is informational and does not overrule live quota.
+
+```ts
+export type CodexCapacityEstimate = {
+  window: "short" | "weekly" | "monthly";
+  estimatedTokens: number;
+  sampleCount: number;
+  confidence: "observed-lower-bound";
+};
+```
+
+MODIFY history read API/CLI projection to attach per-window estimates with sample count and caveat; expose an existing account-card detail surface only if it can be honestly rendered and verified. Field chain: pure estimator creation; API JSON serialization; existing typed CLI/client deserialization; explicit informational display consumers. No persisted estimate schema needed. Tests feed independently hand-calculated intervals, 0% delta, reset rollover, missing timestamps/identity, cross-account records, retries, estimated usage, and extreme numeric input. Sync quota/usage ownership docs and user configuration guidance. Full closure of #3376 requires both history and meaningful capacity; reset-first alone stays partial. Local suites NOT RUN; hosted final cumulative tip is the verifier.
+
+A2 accepted: use readUsageSnapshotForManagement; if truncatedPrefixBytes>0, entriesTruncated, entriesDropped>0, missing revision, or invalid timing then return insufficient-evidence with no estimate. Treat each request as interval [timestamp, timestamp+durationMs] (request-log.ts:1039/1072); include only requests wholly contained in a quota-observation interval. Boundary-spanning requests contribute nothing. For included requests count reported physical attempts matching the exact pool label once; do not count both request total and attempts. Without attempts accept request-level reported usage only with matching label and no recovery ambiguity. Native main is excluded from token capacity because its historical label cannot establish identity after replacement. Current pool logLabel must be unique; legacy fallback labels/id reuse require insufficient evidence unless continuity is proven by history generation. Same-reset positive deltas only. Hand-worked boundary-spanning, truncation, missing identity and retry rows are mandatory regression fixtures.
diff --git a/devlog/_plan/260912_accounts/070_tun.md b/devlog/_plan/260912_accounts/070_tun.md
new file mode 100644
index 0000000000..d37cd09632
--- /dev/null
+++ b/devlog/_plan/260912_accounts/070_tun.md
@@ -0,0 +1,23 @@
+# Preserve canonical transport and classify failed quota reads
+
+Cycle tun; C3 account diagnostic, independent dev branch. #3799 and #3872 are ancestors of baseline; no re-carry. Source: `src/providers/quota.ts:2795`, quota cache :1570/:2093/:2162; `src/server/management/oauth-account-routes.ts:325`; shared account view `ProviderAccountQuota.tsx:8`.
+
+MODIFY `src/providers/quota-types.ts` dependency-free contract:
+```ts
+export const QUOTA_FAILURE_CODES = ["account_unavailable", "access_denied", "rate_limited", "upstream_error", "redirect_blocked", "destination_blocked", "dns_failed", "timeout", "transport_error", "response_unusable"] as const;
+export type QuotaFailureCode = typeof QUOTA_FAILURE_CODES[number];
+export function parseQuotaFailureCode(value: unknown): QuotaFailureCode | undefined {
+  return QUOTA_FAILURE_CODES.find(code => code === value);
+}
+// AccountQuotaFields gains quotaFailure?: QuotaFailureCode.
+```
+
+MODIFY `src/providers/quota.ts`: private classified Antigravity probe returns available quota+source or unavailable failure+legacy null/throw disposition. Public fetchAntigravityUsageQuota retains existing null/rejection behavior. Summary redirect/401/403 terminates without fallback; any other failure tries existing models fallback; final attempt determines category, successful fallback clears failure. Classify ProviderOutboundPolicyError→destination_blocked; DestinationDnsResolutionError→dns_failed; PinnedHttpError timeout codes→timeout, output_byte_limit→response_unusable; DOMException TimeoutError→timeout; remaining errors→transport_error. Never use message regexes. JSON/body failures stay response_unusable since readQuotaJson cannot distinguish timeout from malformed data.
+
+Before: cache failure stores `{ts, quota: lastGood, unavailable: true}`. After: adds only closed `quotaFailure`, no error object/message/body/URL. Credential/project preparation failures are account_unavailable, not reauth verdicts. Cache generation/inflight/TTL guards remain. Success constructs fresh entry without failure. Persist only existing quota projection; diagnostic codes remain transient. Extend account result and API projection only when unavailable; stale identity/config projection omits category.
+
+MODIFY GUI `components/provider-workspace/types.ts`, `hooks/useProviderAccountPools.ts`: parse incoming code; enriched success/pending clears it, roster-only refresh preserves it only for same id/mode, late merge explicitly copies it, local API failure clears old upstream diagnosis. `ProviderAuthPanel.tsx` forwards to `ProviderAccountQuota.tsx` for all accounts; current account whole-row pass-through stays intact. Add localized pws.quotaFailure keys to all locale files. CLI AccountRow/raw DTO/projector and quotaText show safe category, preserving generic fallback for unknown values.
+
+Field chain: private probe→transient cache→account results→authenticated API JSON→enum-normalized client/CLI→current/all-account quota text. Ranking/health/history do not consume it. Tests: each enum trigger, summary failure/fallback success, final-attempt precedence, stale bars, recovery, cross-account isolation, stale-config, late response, unknown wire code, and secret-free projection. Existing provider account quota fixtures supply transport injection; new files require both layout entries. Fix inventory's stale IPv6 proxy-only sentence and update every touched area owner. Local suites/build NOT RUN; hosted backend/GUI checks and rendered final-tip artifact. Authenticated TUN observation remains unmet until an authorized operator supplies exact SHA, proxy/TUN mode and sanitized successful refresh; no network/account changes here.
+
+Reflection TUN-R01/R02 accepted. HTTP 300–399→redirect_blocked, 401/403→access_denied, 429→rate_limited, other non-2xx→upstream_error; success with unusable quota→response_unusable. Keep providerRedirectError cancellation and discard its message. Neither status establishes plan or reauth. fetchAntigravityQuota may reuse the private probe preserving null/rejection and success source; ProviderQuota/ProviderQuotaReport gain no diagnostic field, report-only views remain generic. getCachedProviderAccountQuota returns last-good quota only.
diff --git a/devlog/_plan/260912_accounts/080_reauth_api.md b/devlog/_plan/260912_accounts/080_reauth_api.md
new file mode 100644
index 0000000000..10370f304f
--- /dev/null
+++ b/devlog/_plan/260912_accounts/080_reauth_api.md
@@ -0,0 +1,29 @@
+# Reauthenticate the existing native main identity with device code
+
+Cycle reauth-api; C4, independent dev branch. Preserve /api/codex-auth/login rejection of __main__. Allow existing native-main credentials in every runtime role, with no codex binary/keyring requirement. Same-identity reauth only; account switching remains the native profile workflow. Main device service does not call startLoginFlow(chatgpt), whose completion persists into the OAuth store.
+
+MODIFY `src/oauth/chatgpt-device.ts`: factor the private grant exchange to retain raw validated token payload for a new native-only result. Existing loginChatGPTDevice still projects OAuthCredentials and returns no id_token. New loginChatGPTNativeDevice returns `{credential: OAuthCredentials, idToken: string}` only in process; reject missing access/refresh/id token or mismatched token account identity. Device callback remains human URL/code, opaque device_auth_id private.
+
+MODIFY `src/codex/main-account.ts`: new beginNativeMainReauth captures existing MainAuthJsonCredential snapshot into a closure without exposing it to callers; returned commit accepts complete native device tokens. At commit acquire existing withNativeMainExclusiveClaim after authorization, verify startup/recovery and in-process admission fence, assert original path/hash/inode before atomic rename, require same chatgpt account identity. Write access_token, refresh_token, id_token, account_id together, preserving allowed root metadata. Check cancellation/current-flow before entering commit and before rename. Advance mutation epoch and reconcile same-account runtime/quota/reauth state explicitly. Never retain the old identity token beside new credentials. No claim held during human polling.
+
+NEW `src/codex/main-device-reauth.ts`: one process-owned active flow, opaque UUID, AbortController and bounded terminal retention; injectable login/commit dependencies for tests. Start/status/cancel return only flowId, status, verificationUrl, deviceCode and closed safe failure code. Superseded/cancelled completion may not publish. Terminal data clears URL/code when no longer useful. No tokens/emails/raw account IDs in DTO/log/error.
+
+NEW `src/codex/main-device-reauth-api.ts`: dedicated handler for POST/GET/DELETE `/api/codex-auth/main/reauth-device`, exact opaque flow query for status/cancel, strict request keys and safe 400/404/409 errors. Register at existing management registry/auth handler boundary (read latest dispatch before B); existing management auth/origin/session controls remain authoritative. No CLI direct account file write.
+
+MODIFY `src/cli/account-main.ts`: `reauth --device [--no-wait]`, `reauth status --flow <id>`, `reauth cancel --flow <id>` via same management API; reject extra args before start. Register capability/help and regenerate skill surface using source-only tooling if needed. Blocking wait bounded by service flow expiry; --no-wait returns handle/code and follow-up commands.
+
+Field chain: device token creation→native private commit only, never API serialization; flow DTO created by service→management JSON→CLI/GUI typed parsing→human code/status. Tests: same-account success without codex/keyring, wrong identity, missing token fields, cancelled late result, concurrent file replace/refresh/profile switch, pending recovery, atomic write failure, same-account quarantine clearing, no pool-row mutation, secret-free all routes, unauthorized endpoints. Security draft stays scratch; implementation and regression diff may be published. Sync all src/codex/src/oauth/src/cli/src/server ownership docs and public headless recovery instructions. Local suites/build/typecheck/install NOT RUN; hosted final API/UI tip and independent security review required.
+
+Reflection native publication contract: pin NativeProfileContext once. Use a short owner/shared operation for preparation; capture original bytes and dev/ino from the SAME opened descriptor using an additive snapshot variant of native-profile-store.ts readBounded, preserving no-follow/regular-file/size bounds and wrapper compatibility. Closure retains this original snapshot throughout login. Explicitly assertNativeMainOwner at preparation and commit; withNativeMainOwnerOperation tracks work but does not replace this assertion. Acquire exclusive claim after human authorization, then recheck recovery, flow, cancellation and ownership before rename. Missing owner/claim fails safely, no NativeProfileManager/keyring enrollment. Tests include same-byte replacement, capture-time replacement, in-place edits, deletion/nonregular/symlink, cancellation waiting for claim, missing owner and unsupported claim.
+
+```ts
+type MainDeviceReauthStatus =
+ | {flowId: string; status: "pending"; verificationUrl: string; deviceCode: string}
+ | {flowId: string; status: "committing"}
+ | {flowId: string; status: "succeeded"; credentialUpdated: true}
+ | {flowId: string; status: "cancelled"}
+ | {flowId: string; status: "failed"; credentialUpdated?: true; code: "identity_mismatch" | "credential_changed" | "native_main_unavailable" | "device_authorization_failed" | "publication_failed" | "reconciliation_failed"};
+```
+Cancellation after publication returns succeeded, never cancelled. Post-publication reconciliation failure reports credentialUpdated=true/reconciliation_failed, no rollback claim or automatic retry. Tokens/snapshots stay private. Start waits for human-code publication or terminal result so pending always has URL/code. One active flow rejects overlapping start (409), terminal retention 5 minutes, grant deadline 15 minutes inherited from device owner.
+
+Reflection residual accepted: reconciliation_failed is a distinct DTO union member requiring credentialUpdated:true. Cancellation after publication preserves either succeeded or reconciliation_failed, never overwrites reconciliation failure and never reports cancelled.
diff --git a/devlog/_plan/260912_accounts/090_reauth_ui.md b/devlog/_plan/260912_accounts/090_reauth_ui.md
new file mode 100644
index 0000000000..9e32ba6c1b
--- /dev/null
+++ b/devlog/_plan/260912_accounts/090_reauth_ui.md
@@ -0,0 +1,9 @@
+# Put native-main device reauth on the main card
+
+Cycle reauth-ui depends on reauth-api. C4 auth UI. Existing main-card uses only expired-token text at `gui/src/components/codex-account-pool-main-card.tsx:184`. Preserve pool Add/Re-login and native profile picker.
+
+NEW `gui/src/components/use-main-device-reauth.ts`: dedicated hook with start/poll/cancel methods using native-only namespace, flowId ownership and abort/unmount cleanup. Normalize closed status/error payloads; never accept arbitrary verification URLs (only known device verification destination from backend contract), no token/account-id fields. Poll only matching active flow and stop on terminal status; late responses from replaced flow ignored.
+
+MODIFY main-card component: button Re-login with device code; after start show known verification URL, human code/copy and polite pending status, cancel action; success refreshes main account state. Keep layout consistent with current card. Do not reuse AddCodexAccountModal or reauthAccountId=__main__. Add exact locale keys for all shipped languages, update prop owners/types and backend error copy. Terminal failure is actionable and safe; do not automatically retry login or switch identity.
+
+Field chain: dedicated API DTO→hook validated state→main-card only; no persistence of device code in browser storage. Existing parent refresh callback re-fetches main status on completion. Regression source verifies correct route, code display, cancel ownership, stale poll, success refresh, no pool Add invocation, keyboard and error states. Hosted rendered screenshots required for PR; obtain built artifacts from final hosted CI instead of local product build. Sync GUI owners and headless dashboard docs. Local tests/build NOT RUN. API→UI ordinary manual chain, merge reserved to coordinator.
diff --git a/devlog/_plan/260912_accounts/100_final.md b/devlog/_plan/260912_accounts/100_final.md
new file mode 100644
index 0000000000..709dc240d7
--- /dev/null
+++ b/devlog/_plan/260912_accounts/100_final.md
@@ -0,0 +1,7 @@
+# Verify final branch tips and hand off integration evidence
+
+Cycle final consumes every delivered PR. No product change unless a concrete hosted CI/reviewer finding justifies a new repair cycle. Refresh PR head/base/native membership, CI run head SHA, all jobs and outstanding review threads. GitHub-hosted final tips are the user's execution verifier; intermediate runs may exist but are not claimed as tested by this task. Do not cancel workflows or modify protection.
+
+MODIFY this unit's numbered evidence/closure record and task-local handoff: one row per original issue/PR with LIVE/PARTIAL/SUPERSEDED/NOOP and exact remaining acceptance; one row per new PR with URL/base/head SHA/commits/coauthor/manual-chain order; final hosted run IDs/URLs/conclusions and unresolved security/review/field acceptance. Local suites/typecheck/build/install NOT RUN. No merge or original issue closure.
+
+Conditional repair: download exact failing job log, identify cause, amend owning phase plan, implement smallest correction in a fresh PABCD cycle, push --no-verify and verify new final head. Source-only checks are labeled text checks, not suite evidence. After unchanged final tip's checks pass, stop retesting and collect final handoff. Do not mark goal complete while required implementation is absent. Field acceptance has separate evidence status and cannot be replaced by mocks.
diff --git a/devlog/_plan/260912_cache_lane/000_plan.md b/devlog/_plan/260912_cache_lane/000_plan.md
new file mode 100644
index 0000000000..ac31af2b2d
--- /dev/null
+++ b/devlog/_plan/260912_cache_lane/000_plan.md
@@ -0,0 +1,23 @@
+# Cache lane roadmap
+
+Three independent fixes address optional helper admission, final OpenCode Go conversation affinity, and explicitly enabled Claude instruction stabilization. Hermes cache observations are investigated separately: missing inbound identity is not proof of proxy loss, and a shared prefix is not a conversation.
+
+Satisfy-spec HOTL, triggered by the authorized cache lane assignment. Scope: PRs #4118/#4050/#4052 and issue #3433. No local tests of any size, build/typecheck/install, service changes, merges, closures, releases, workflow or permission changes. Commits and --no-verify pushes plus ordinary PR creation are authorized. Existing tool/account scope only; no user-set time/token/agent cap. Main implements; inherited-model subagents review. Native architect selection is unavailable; supported independent design review records that limitation.
+
+Verification: git diff --check for textual integrity; independent source review; GitHub hosted Cross-platform CI at each independent final PR tip. Local product checks are NOT RUN. Source/applicability checks do not prove runtime behavior. Stop after concrete dispositions, final hosted evidence and durable handoff; field evidence or review/access gaps remain explicit, never a false fix. Tool gate denial is reported without bypass. Two failed independent reviewer contexts return work to main; implementation remains main-owned.
+
+Existing layout: src/server (wire bridges), src/claude (translator), src/providers (Go transport), tests/{responses,providers,claude-integration,codex-integration}, structure (contracts), docs-site (user guidance). Reuse these owners; no new framework or runtime abstraction.
+
+Work phases, each a full P-A-B-C-D cycle:
+- roadmap: docs only; lock all following plans.
+- claim: 010, independent dev PR for #4118.
+- affinity: 020, independent dev PR for #4050; prerequisite request-lane allocator is already on dev.
+- prefix: 030, independent dev PR for #4052 with an actual default-off configuration boundary.
+- hermes: 040, independent contract evidence for #3433, no invented identity.
+- verify: 050, inspect hosted results, repair confirmed scoped failures in added cycles, hand off exact heads.
+
+The implementation order is a work ledger, not a false PR dependency. No native stack requested. Each independent PR is its own final tip. A repair that depends on a delivered implementation may be a child layer.
+
+Source inventory and raw latest GitHub evidence stay in .tmp/cache-handoff/. Public source PRs are the provenance; measurements are author-reported and are not reproduced here. Unpublished security notes stay in scratch. Source ownership updates accompany each actual patch.
+
+Design disposition: accept CACHE-D01 through D05. D04 uses the existing Claude configuration argument as its single control; no separate conflicting translator option. D05 covers underscore session_id and hyphenated session/thread pair separately. Native architect role not selected; inherited supported subagent performed actual design review.
diff --git a/devlog/_plan/260912_cache_lane/010_claim.md b/devlog/_plan/260912_cache_lane/010_claim.md
new file mode 100644
index 0000000000..afb97b03b1
--- /dev/null
+++ b/devlog/_plan/260912_cache_lane/010_claim.md
@@ -0,0 +1,28 @@
+# Claim deferral
+
+Prerequisite: roadmap; origin/dev baseline. Independent PR. Carry source #4118 at fc8c03833e9ffd0f2bfd30f5ef7de19425c87645, preserving author trailers.
+
+- MODIFY `docs-site/src/content/docs/fr/reference/proxy-formats.md`
+- MODIFY `docs-site/src/content/docs/ja/reference/proxy-formats.md`
+- MODIFY `docs-site/src/content/docs/ko/reference/proxy-formats.md`
+- MODIFY `docs-site/src/content/docs/reference/proxy-formats.md`
+- MODIFY `docs-site/src/content/docs/ru/reference/proxy-formats.md`
+- MODIFY `docs-site/src/content/docs/tr/reference/proxy-formats.md`
+- MODIFY `docs-site/src/content/docs/zh-cn/reference/proxy-formats.md`
+- MODIFY `docs-site/src/content/docs/zh-tw/reference/proxy-formats.md`
+- MODIFY `src/server/chat-completions.ts`
+- MODIFY `src/server/responses/core.ts`
+- MODIFY `src/vision/plan.ts`
+- MODIFY `src/web-search/index.ts`
+- MODIFY `structure/providers/openai-tiers.md`
+- MODIFY `tests/codex-integration/bearer-admission-routed-provider.test.ts`
+- MODIFY `tests/vision/vision-cache.test.ts`
+- MODIFY `tests/web-search/web-search.test.ts`
+
+Before: caller-auth noncanonical Chat eagerly claims stored main; helper admission does not share all terminal/routed/search exclusions. After: only non-caller-auth keeps early enrichment; carry `allowStoredOpenAiSidecarAuth` privately, then claim before reading main only when a canonical Direct helper candidate is actually needed. Snapshot stays separate from primary/retry credentials. Share routed-vision eligibility and tool-choice exclusions. Preserve loopback hostname/listener fields.
+
+Activation: held keyless Cursor request without helper leaves main request count zero and profile switch succeeds; Direct helper carries main only to helper wire; Pool/exact account and excluded tool choices retain behavior. Auth review required.
+
+Exact executable delta is the public diff at https://github.com/lidge-jun/opencodex/pull/4118.diff captured locally in .tmp/cache-handoff/pr-4118.diff; git apply --check exited 0 on baseline. Read and adapt source context before application. No source deletion. Add concise current-contract references to all mapped source ownership docs, with canonical details in structure/data-planes/inbound-compat.md and structure/providers/openai-tiers.md (claim) or structure/transports/responses.md (affinity).
+
+C: git diff --check plus independent review; local tests NOT RUN. Runtime acceptance deferred to final hosted tip CI. D records implementation and pending remote evidence, not test success.
diff --git a/devlog/_plan/260912_cache_lane/020_affinity.md b/devlog/_plan/260912_cache_lane/020_affinity.md
new file mode 100644
index 0000000000..8ccf8fc363
--- /dev/null
+++ b/devlog/_plan/260912_cache_lane/020_affinity.md
@@ -0,0 +1,16 @@
+# Final Go affinity
+
+Prerequisite: roadmap; origin/dev baseline. Independent PR. Carry source #4050 at e5c2411f7b35c6265aacce19f66f13eace544579, preserving author trailers.
+
+- MODIFY `docs-site/src/content/docs/guides/providers.md`
+- MODIFY `src/server/claude-messages.ts`
+- MODIFY `src/server/responses/core.ts`
+- MODIFY `tests/providers/opencode-go-session-header.test.ts`
+
+Before: preliminary Claude route injects Go identity into replay headers. After: derive validated lane with explicit session > Go header > valid Claude metadata > original request allocation, carry `claudeGoAffinity` in HandleResponsesOptions through combo recursion and consume only at final Go normalization. Never synthesize shared system hash identity or leak Go-only headers to non-Go.
+
+Activation: existing two-wire/random/failover matrix gains metadata, explicit-header precedence, malformed/shared identity and independent sessionless controls; operator override wins. No public option or serialization: private in-memory options, recursion spreads options, final transport consumes.
+
+Exact executable delta is the public diff at https://github.com/lidge-jun/opencodex/pull/4050.diff captured locally in .tmp/cache-handoff/pr-4050.diff; git apply --check exited 0 on baseline. Read and adapt source context before application. No source deletion. Add concise current-contract references to all mapped source ownership docs, with canonical details in structure/data-planes/inbound-compat.md and structure/providers/openai-tiers.md (claim) or structure/transports/responses.md (affinity).
+
+C: git diff --check plus independent review; local tests NOT RUN. Runtime acceptance deferred to final hosted tip CI. D records implementation and pending remote evidence, not test success.
diff --git a/devlog/_plan/260912_cache_lane/025_affinity_native.md b/devlog/_plan/260912_cache_lane/025_affinity_native.md
new file mode 100644
index 0000000000..0d22be757a
--- /dev/null
+++ b/devlog/_plan/260912_cache_lane/025_affinity_native.md
@@ -0,0 +1,17 @@
+# Final native affinity after preliminary Go route
+
+Previous D: prefix implemented; confirmed P2 on #4340 requires correction before integration. Source https://github.com/lidge-jun/opencodex/pull/4340#discussion_r3995130580. Class C3 transport identity; same authorized runtime/no-local-suites/no-merge scope. This extends the existing affinity PR, not a new independent feature.
+
+MODIFY src/server/claude-messages.ts: remove preliminary `if (nativeRoute && !opencodeGoRoute)` session_id synthesis. Retain validated metadata UUID privately as new HandleResponsesOptions.claudeNativeSessionId, alongside claudeGoAffinity. Do not derive from system fallback. Explicit session_id is forwarded as before and wins.
+
+MODIFY src/server/responses/core.ts: add optional `claudeNativeSessionId?: string` to internal options. Create a private `withClaudeNativeSession(headers, provider, sessionId)` helper that returns headers unchanged unless canonical OpenAI, private value present, and no explicit session_id/session-id/thread-id header. Then clone Headers and set only the cloned session_id. Apply to both finalAuth.headers and finalAuth.callerAuthHeaders after final auth resolution; alternate-account retries already consume callerAuthHeaders. Reapply to selectedForwardHeaders after a native credential refresh, whose replay result rebuilds from req. Never mutate req.headers. Policy/combo replay sees original headers and carries only the private option. Explicit underscore, hyphenated session and thread-only identity all prevent metadata synthesis. No public serialization: creation Claude handler -> recursive option spreads -> attempt-local auth/header copies -> canonical adapter.
+
+A audit corrections: reject request-header mutation because policy fallback reuses the same request. Reject caller JWT fixture because Claude drops caller auth. Use isolated stored main under an actual admitted turn; no ambient credentials.
+
+MODIFY tests/providers/opencode-go-session-header.test.ts: real handler random/failover Go preflight -> canonical ChatGPT fixture, valid metadata yields expected UUID, explicit native header wins, no metadata/shared-system cannot synthesize. Mock outbound fetch; isolate OPENCODEX_HOME and CODEX_HOME, store synthetic main JWT/account and use tryAdmitTurn lease with real handler logIds so existing claimed-main enrichment is reached. Add canonical failure then noncanonical policy fallback control with original request.headers unchanged; existing runPolicyFallbackHops fixture may be used to inspect header-copy boundary. Retain final non-Go no-header controls. Hosted CI only; local product checks NOT RUN. Assert actual session_id and prompt_cache_key at outbound boundary, not source text.
+
+MODIFY structure/data-planes/inbound-compat.md final affinity contract to describe private native lane at final canonical destination; mapped links already exist. Preserve source authors. C source audit + diff check, then exact final-tip hosted run tracked in verification cycle. D records missed earlier review scenario and repair head.
+
+Test placement amendment: NEW tests/claude-integration/claude-native-affinity.test.ts and both layout mappings instead of enlarging the existing 600-line Go suite. Same real-handler matrix plus policy wrapper with real core and controlled trace.
+
+C review correction: normalizeLogConversationId hashes its input, so native projection retains raw validated UUID separately; only metadataGoLane uses normalized hash. Preserve fixed historical UUID oracle, no cache-identity migration.
diff --git a/devlog/_plan/260912_cache_lane/026_affinity_adapt.md b/devlog/_plan/260912_cache_lane/026_affinity_adapt.md
new file mode 100644
index 0000000000..ad0eb164a8
--- /dev/null
+++ b/devlog/_plan/260912_cache_lane/026_affinity_adapt.md
@@ -0,0 +1,7 @@
+# Repaired affinity current-dev adaptation
+
+Previous D: prefix adaptation completed. Live #4340 now CONFLICTING with current dev. Class C2 same owned-branch adaptation, no local suites/build/typecheck/install, no merge. Rebase own three commits after30d5016a onto5042a376. Preserve exact original affinity runtime patch and native-repair delta at37a4e6b65, all credits. No changes to other lane branches.
+
+MODIFY conflict resolutions in13 mapped structure docs: union complete new-base helper contracts with original Go affinity links/section. Runtime.md also preserves newer continuation paragraph. src/server/responses/core.ts and layout files auto-merge, independently compare patch additions/deletions to old range. Later native-repair append may conflict at inbound-compat tail; preserve both current-base/Go/native paragraphs exactly. Add this026 checkpoint only.
+
+C compares old30d5016a..37a4e6b65 to new5042a376..newhead, exact runtime/tests range-diff and doc-union source audit. Push no-verify with exact old-head force lease, then new-tip hosted CI; parent owns merge.
diff --git a/devlog/_plan/260912_cache_lane/027_affinity_slot.md b/devlog/_plan/260912_cache_lane/027_affinity_slot.md
new file mode 100644
index 0000000000..c5f76acecf
--- /dev/null
+++ b/devlog/_plan/260912_cache_lane/027_affinity_slot.md
@@ -0,0 +1,3 @@
+# Serial affinity integration slot
+
+Parent pinned dev10c73569e9141f61c363b5fb61963d5c27e174d9 after4342 and reserved affinity-first integration. Previous D Hermes contract complete, live acceptance open. Rebase only own four commits after5042a376 onto parent-pinned10c73569; old headf58cb87b1c. Same026 audited append-union mechanism and no local suite/build/typecheck/install/merge. Keep all current-base source/docs and preserve own authored runtime/test bytes, credits and025/026 records. Conflict resolution scope is mapped structure docs; stop to audit unexpected runtime conflicts. Range-diff confirms source/tests unchanged; independent reviewer checks exact resulting doc union and head. Lease push pinned to oldf58cb, parent merges next. Prefix stays untouched until parent gives next base.
diff --git a/devlog/_plan/260912_cache_lane/030_prefix.md b/devlog/_plan/260912_cache_lane/030_prefix.md
new file mode 100644
index 0000000000..fead938ce8
--- /dev/null
+++ b/devlog/_plan/260912_cache_lane/030_prefix.md
@@ -0,0 +1,13 @@
+# Explicit Claude prefix stabilization
+
+Prerequisite roadmap; independent dev PR. Reimplement #4052 at 43def4039ba60039df9a2a91fb6352b91ba74d70; preserve Warexpor and Cursor Agent credit. Do not copy binary paper or unverified measurements.
+
+NEW src/claude/inbound-cache-stabilize.ts: adopt source helper's complete trailing exact total_tokens/two TaskCreate matchers and fenced-range parser, including unclosed fence through EOF. Source full text is in .tmp/cache-handoff/pr-4052.diff. MODIFY src/claude/inbound.ts: read `cc?.stabilizePromptCache === true` from the existing Claude config parameter, defaulting stabilization off, relocate only when true, append latest dynamic notice as user input, use stabilized instructions for opted-in Desktop cache key; preserve original systemParts hashing otherwise.
+
+MODIFY src/types/config.ts OcxClaudeCodeConfig: add `stabilizePromptCache?: boolean` with default false and role-change warning. Serialization/deserialization: existing config JSON save/load retains the boolean; no new wire option; malformed non-true values do not activate. KEEP src/server/claude-messages.ts existing three-argument translation call, which already passes config.claudeCode. Never use unconditional true or infer opt-in from metadata, endpoint or text. Configuration is operator-owned and opt-in applies to translated Messages traffic; native passthrough stays unchanged.
+
+NEW tests/claude-integration/claude-inbound-cache-stabilize.test.ts: adopt translator/helper controls; replace source-phrase assertion with real handler outbound capture proving default/unset/false retain exact suffix and original key, true relocates, fences preserve content, both TaskCreate shapes peel, metadata session key stays stable. MODIFY scripts/test-layout/layout.json and tests/fixtures/test-layout-expected.json to register new file. Add save/load and malformed-value control where existing config fixture permits.
+
+MODIFY docs-site/src/content/docs/guides/claude-code.md and applicable translated pages: document default-off claudeCode.stabilizePromptCache, changed message role/key scope and no hit-rate guarantee. MODIFY structure/data-planes/inbound-compat.md/config.md and other mapped source-owner docs with canonical contract references. No GUI control, new dependency, automatic user config edit or cache-key-to-session synthesis.
+
+C: textual diff/source review only locally; all product tests NOT RUN. Hosted tests must observe actual outbound instructions/input/key, not phrase presence. Independent reviewer must confirm that earlier #4052 HTTP activation blocker is resolved. D publishes exact implementation with remote evidence pending until verification phase.
diff --git a/devlog/_plan/260912_cache_lane/035_prefix_adapt.md b/devlog/_plan/260912_cache_lane/035_prefix_adapt.md
new file mode 100644
index 0000000000..e48750d0d8
--- /dev/null
+++ b/devlog/_plan/260912_cache_lane/035_prefix_adapt.md
@@ -0,0 +1,7 @@
+# Prefix current-dev adaptation
+
+Previous D: reverse native affinity correction reviewed. Parent requested current-dev integration of own prefix branch #4347. Class C2 adaptation; all existing no-local-suites/no-merge restrictions apply. Safe rebase own prefix commit df5853600a onto fetched origin/dev, dropping no product change. Existing roadmap commit already integrated via #4338. Record old/new immutable refs. No other branch/worktree edits.
+
+MODIFY only conflict resolutions in structure/clients/claude-desktop.md, structure/data-planes/inbound-compat.md, structure/runtime.md: preserve latest dev appended helper contract AND prefix opt-in section/link. Runtime prefix delta remains byte-identical. Test layout maps auto-merge retaining both sides' entries. No new implementation.
+
+Independent design/audit: confirm union of append-only docs is correct; compare old base..old tip to new base..new tip by file and range-diff, disclose every changed patch. Existing independent source review at df585 remains valid only for unchanged authored bytes, and conflict interdiff needs a separate inherited reviewer. C text diff check and new exact head hosted CI tracking; no local product tests. Push --force-with-lease tied to old prefix head and --no-verify; parent owns merge.
diff --git a/devlog/_plan/260912_cache_lane/036_prefix_linear.md b/devlog/_plan/260912_cache_lane/036_prefix_linear.md
new file mode 100644
index 0000000000..43bf8c3dfe
--- /dev/null
+++ b/devlog/_plan/260912_cache_lane/036_prefix_linear.md
@@ -0,0 +1,13 @@
+# Linear canonical suffix parsing
+
+Previous D: affinity integrated by parent; prefix serial base81f0c78d7a2bf56e759511e89f450c7d49e0a42e. New public reviews on4347 discussion_r3995155701/P1 and3995155709/P2 require code repair, not only adaptation. C3 bounded parser performance/correctness. Same no-local-suites/build/typecheck/install/no-merge scope; hosted CI is runtime verifier.
+
+First rebase own prefix commits after5042a376 onto pinned81f0c78d. Union three mapped structure conflicts preserving base affinity/helper paragraphs and prefix opt-in contract; original runtime delta unchanged before repair. Preserve Warexpor/Cursor credit.
+
+MODIFY src/claude/inbound-cache-stabilize.ts: replace repeated whole-rest regex scans and slices with one forward fence-range scan plus backward line cursor. Each backward iteration strips trailing horizontal/line whitespace, isolates one complete single line via lastIndexOf newline, accepts only exact total_tokens with digits + one ASCII space + tokens left or either full exact TaskCreate paragraph, and checks monotonically decreasing fence-range cursor. On recognized line move end cursor before separator newlines, retain only latest total/nudge. Slice original instructions once at final end; no match returns original bytes. Fence opener/closer behavior retained. No whole shrinking-string rescan or per-footer copy. No multiline/tab/formfeed inside canonical tag.
+
+MODIFY tests/claude-integration/claude-inbound-cache-stabilize.test.ts: add controls for newline/tab/formfeed between digits and tokens left, exact single-space positive, CRLF outer separators, many consecutive footer sequence (20k) retains exact prefix/latest footer. No tight wall-clock benchmark; normal hosted test timeout plus source complexity review validates bounded work. Preserve existing fence/default-off/HTTP/header/config tests.
+
+Update structure/data-planes/inbound-compat.md to state single-line canonical notices and linear scan. Exact old runtime-delta comparison binds inherited source review, new parser receives independent A and implementation source audit. GitHub hosted finaltip CI after --no-verify lease push. Parent owns merge and review-thread resolution. Safe public final handoff will be exported to tracked devlog at verification completion; scratch raw evidence retained locally only.
+
+Design dispositions LINEAR01-04 accepted. Keep committed `end` unchanged until notice acceptance. A speculative `lineEnd` skips only complete LF/CRLF sequences; candidate horizontal padding trims only ASCII space/tab by indices. Do not cross whitespace-only lines, consume lone CR or trim unmatched prefix. After matching, commit end before immediately preceding LF/CRLF runs; failed candidate returns prior committed prefix unchanged. Compare exact nudge strings and anchored digits + literal single space. Fence index decreases only. Add preserved two-space prefix, malformed-before-valid, whitespace-only separator, loneCR and many closed fences+footers controls.
diff --git a/devlog/_plan/260912_cache_lane/037_prefix_slot.md b/devlog/_plan/260912_cache_lane/037_prefix_slot.md
new file mode 100644
index 0000000000..0d97df1bfc
--- /dev/null
+++ b/devlog/_plan/260912_cache_lane/037_prefix_slot.md
@@ -0,0 +1,9 @@
+# Final prefix slot and durable evidence
+
+Parent pinned dev81f6cd5915ca59f784a584d8cd739adff55c9bd0 after Cline4371, holding other structure merges. Previous D: linear canonical parser repair e1d262acee freshly source-audited PASS0, no local product execution. Class C2 adaptation/docs, no local suites/build/typecheck/install/no merge.
+
+Rebase own three commits after81f0c78d onto81f6cd5915, preserving exact repair/source/test bytes and all parent-base source/docs. Conflict union only in mapped docs; unexpected runtime conflicts need independent review. Compare oldbase81f0..e1d262 against newbase81f6..newhead; source/test patches identical. Lease push remains pinned to remote e1c92f10c3, which was intentionally kept during repair.
+
+MODIFY050_verify.md: .tmp is scratch, not sole durable evidence. NEW060_handoff.md safe tracked index includes original dispositions, branches/PRs, known source-audit and CI references, remaining3433 live acceptance, local suites NOT RUN, cycle list and parent-only integration. Private paths/raw evidence stay in scratch. Export current exact SHA/CI/source-review data to4347 PR body on publication, then update only PR body with terminal results; this preserves final source head without a self-referential new commit. Keep parent integration annotations when updating PR body. Final verification must inspect the exported body before closing goal.
+
+Independent conflict audit binds prior fresh linear-parser PASS to final head; no old pre-P1/P2 PASS stands in for repair. Parent decides review-thread resolution and merge.
diff --git a/devlog/_plan/260912_cache_lane/040_hermes.md b/devlog/_plan/260912_cache_lane/040_hermes.md
new file mode 100644
index 0000000000..de79dc1d7e
--- /dev/null
+++ b/devlog/_plan/260912_cache_lane/040_hermes.md
@@ -0,0 +1,11 @@
+# Hermes identity boundary
+
+Prerequisite roadmap; independent path from Claude changes. Latest issue #3433 comment 5556427205 and controlled sample 5551855276 establish no measured inbound identity, not a dropped value. Preserve issue OPEN disposition.
+
+MODIFY tests/responses/chat-completions-endpoint.test.ts or a registered adjacent contract file: use the existing real Chat handler + mocked Responses upstream. Send synthetic session A on two growth turns and session B on a fresh turn; cross body prompt_cache_key present/absent with session_id present/absent. Assert captured outbound session_id and body key are exactly caller supplied; absent remains absent; shared key is not converted into session_id. Use fixture identity distinct from raw personal data, and compare at actual adapter fetch boundary. Existing src/chat/inbound.ts copies prompt_cache_key; Chat FORWARD_HEADERS and openai-responses adapter forward session_id. No runtime mutation unless this controlled contract reveals a specific defect.
+
+MODIFY canonical inbound contract docs to distinguish stable client conversation identity, request-scoped lane and prompt prefix. Durable scratch evidence names public comment URLs, actual test command coverage and limitations. Real Hermes same-conversation/fresh-session identifier and outbound capture from its running client are unavailable unless provided by existing public evidence; synthetic regression proves transport contract only. Do not claim actual client identity was observed, cache hits improved or #3433 solved.
+
+C hosted final tip executes the contract; local suite NOT RUN. D records exactly what is proven and remaining controlled live-client comparison.
+
+Execution refinement: NEW tests/responses/chat-conversation-affinity.test.ts and register it in both layout maps. Invoke actual Chat handler with synthetic caller JWT against canonical ChatGPT Responses config in isolated homes. Mock only outbound fetch, record Headers/body. Two header shapes (underscore session_id, hyphen session-id/thread-id), key present/absent, A/A/B growing messages; explicit request-id differs per turn. Absent identity controls prove shared key never becomes a session. This fixture establishes OCX preservation, not actual Hermes emission. No runtime patch unless evidence finds loss.
diff --git a/devlog/_plan/260912_cache_lane/041_hermes_ci_refresh.md b/devlog/_plan/260912_cache_lane/041_hermes_ci_refresh.md
new file mode 100644
index 0000000000..5c7f1cb3d9
--- /dev/null
+++ b/devlog/_plan/260912_cache_lane/041_hermes_ci_refresh.md
@@ -0,0 +1,11 @@
+# Hermes hosted-CI refresh after shared fixture repair
+
+Resume preserves the same worktree and session. The host goal is blocked and persisted phase remains C; no goal/FSM reset, reactivation or completion is claimed. This file records the authorized remaining work, not a new completed cycle.
+
+The original Hermes head `b254efc8385ce2a9dc34b9a5ac7d2a449605d75d` failed gates on the Combo active-reactivation fixture, while four Linux and two macOS product shards succeeded. Shared repair #4390 is now integrated as `20861aebf56c6f8ec2b0d8d04d1d0b54441650bb` and its exact hosted CI `34688482827` succeeds. Affinity/prefix old runs failed restore/Cline fixtures subsequently repaired by that same PR. Old failed runs remain failed.
+
+Rebase the one owned Hermes test-only commit from `e4ee8c54` onto current `origin/dev` at `392e182a00` (record full SHA in handoff). Read-only merge-tree reports no conflict. Preserve the 99-line runtime-boundary test and both mappings; no Combo, Cline, restore or provider source edits. Compare old/new authored source deltas and obtain an inherited-model independent source audit. Append terminal evidence to `060_handoff.md`, preserving real Hermes acceptance as open. Push only existing Hermes branch with `--no-verify` and exact old-head lease; no new task/worktree or recreation of merged evidence PR #4377. Bind new final hosted CI to new Hermes SHA. Parent owns integration and chooses any source collision slot.
+
+Local suites/focused/GUI/build/typecheck/install remain NOT RUN. The successful shared integration CI proves its own cumulative source tree, not the old failed PR heads. A new Hermes tip must be independently verified remotely before a passing delivery claim.
+
+Parent integration-slot update: final pinned base is `c311f9bf7f5003af29fa8e7ebc2f2b5db20267f6`, including the subsequently integrated pnpm and Devin fixture corrections. Rebase the two owned commits from `392e182a` without runtime changes. Original 99-line test and mappings must remain byte-identical; source review is renewed for final head. Prior run `34693156321` at `524afd8d80` is superseded evidence only, never final-tip proof. Parent is holding the Hermes slot. Persisted phase C and blocked host goal stay unchanged.
diff --git a/devlog/_plan/260912_cache_lane/050_verify.md b/devlog/_plan/260912_cache_lane/050_verify.md
new file mode 100644
index 0000000000..c72c571585
--- /dev/null
+++ b/devlog/_plan/260912_cache_lane/050_verify.md
@@ -0,0 +1,11 @@
+# Hosted verification and delivery
+
+Prerequisites: independent implementation PRs. Scratch .tmp/cache-handoff/050_handoff.md records actual worktree, branches/PR URLs/full head SHA, source dispositions/credits, cycle receipts, remaining acceptance and reviews. Capture gh pr view/checks and gh run view JSON at each final independent tip; ordinary manual children only for real correction dependencies. No native membership mutation.
+
+No product source changes planned here. If CI exposes a scoped defect, append a numbered repair plan and full PABCD cycle before implementation, then verify new exact head. Hosted workflow definition determines jobs actually executed; skipped/cancelled runs are never passes. No automatic workflow cancellation or protection edit. Local tests/build/typecheck/install remain NOT RUN. Only source/diff checks may be wrapped in cxc receipt and must retain their true label.
+
+C: final head matches hosted run headSha; successful required jobs and skipped jobs recorded individually. D: finish handoff with source review gaps and Hermes field residual, no merge/issue closure. Parent decides integration.
+
+Durable delivery: 060_handoff.md is the tracked safe index. Before any scratch cleanup, export exact final PR/head/CI and source-review evidence into the #4347 PR body, preserving parent annotations, and read it back. Terminal CI updates change that body only, so the verified source head remains stable. Private paths and raw security analysis never enter the public index or PR. Scratch is not the sole retained handoff.
+
+Execution amendment: final evidence updates are committed on `codex/260912-60plus-cache-evidence` in the same managed worktree. This branch contains the tracked delivery artifact, with no new product logic. Product verification remains bound to the four delivered source heads, and the evidence branch's documentation checks are reported separately. Source-delta gating is not bypassed with a manufactured code change.
diff --git a/devlog/_plan/260912_cache_lane/060_handoff.md b/devlog/_plan/260912_cache_lane/060_handoff.md
new file mode 100644
index 0000000000..d6522bec9f
--- /dev/null
+++ b/devlog/_plan/260912_cache_lane/060_handoff.md
@@ -0,0 +1,40 @@
+# Cache lane handoff index
+
+The cache lane contains independent dev PRs, with no native stack or artificial dependency chain. Main implementation used managed worktree slot `7e43`; the coordination task owns integration and original-PR closures. This index preserves source dispositions. Exact final-head CI and source-review snapshots are exported to the [prefix PR description](https://github.com/lidge-jun/opencodex/pull/4347) and read back at delivery; private execution paths and raw scratch evidence are excluded.
+
+| Source | Delivered PR / branch | Outcome and remaining evidence |
+| --- | --- | --- |
+| #4118 | [#4338](https://github.com/lidge-jun/opencodex/pull/4338), `codex/260912-60plus-cache-claim` | Claim deferral adopted. Parent integrated as `75d3e5c78f9ac7fc7125ee27294a962456bf32bb` ; the source PR is closed/unmerged, and the closer is not established. Exact carried head `d27db6dd56c481572728bc99043e2c528f11e1bc`: [hosted CI 34673563105](https://github.com/lidge-jun/opencodex/actions/runs/34673563105) SUCCESS, 19 jobs successful / 2 skipped. |
+| #4050 | [#4340](https://github.com/lidge-jun/opencodex/pull/4340), `codex/260912-60plus-cache-affinity` | Go affinity adopted and reverse Go-to-ChatGPT native identity repaired. Parent integrated as `81f0c78d7a2bf56e759511e89f450c7d49e0a42e`. Final source head `d354924f0af38a48f5768fca0cd09c5145bdb4bd`, fresh repair/conflict audit PASS, blocker 0. [Hosted CI 34674962749](https://github.com/lidge-jun/opencodex/actions/runs/34674962749) pending at this checkpoint. |
+| #4052 | [#4347](https://github.com/lidge-jun/opencodex/pull/4347), `codex/260912-60plus-cache-prefix` | Reimplemented behind literal-true operator configuration; ordinary callers preserve roles and keys. Fresh public P1/P2 findings superseded the first helper approval. The repaired parser uses decreasing line/fence cursors and exact single-space grammar; fresh algorithm audit PASS at `e1d262acee27d55388cccdb96430669e944fbd90`. Final repaired source head `4f6cd1ad3f0215f9cbfd5be53a55b5b6f7cd90f0` is integrated by the parent as `489af939bc68b665bfb2c3226a34267098838ab8`. The parent resolved both public findings after reading the repair. [Hosted CI 34675829597](https://github.com/lidge-jun/opencodex/actions/runs/34675829597) remains pending at this checkpoint. Final terminal evidence is exported in the PR body. |
+| #3433 | [#4365](https://github.com/lidge-jun/opencodex/pull/4365), `codex/260912-60plus-cache-hermes` | Transport contract tests only, no runtime synthesis. Exact source head `b254efc8385ce2a9dc34b9a5ac7d2a449605d75d`, independent source audit PASS, blocker 0. [Hosted CI 34674763850](https://github.com/lidge-jun/opencodex/actions/runs/34674763850) pending at this checkpoint. Live issue acceptance below remains open. |
+
+## Hermes acceptance still open
+
+The [latest controlled field-presence observation](https://github.com/lidge-jun/opencodex/issues/3433#issuecomment-5551855276) omitted measured identity fields. The [maintainer follow-up](https://github.com/lidge-jun/opencodex/issues/3433#issuecomment-5556427205) requests a real client-assigned identity stable within a conversation and distinct for a fresh conversation, then comparison at the outbound boundary. Synthetic A/A/B fixtures verify the OCX Direct transport contract when executed; they do not prove actual Hermes emission, Pool cohort stability or improved cache hits. #3433 is not solved by the Claude PRs. #3719 thinking replay is separate.
+
+## Review and attribution
+
+Carry commits preserve luvs01 credit for #4118; David Wang plus original GPT-6 Astra/Claude Fable trailers for #4050; Warexpor and Cursor Agent for #4052. No code from other authors is relabeled as sole authorship.
+
+The first affinity source review missed reverse native routing; the repair was independently reviewed before parent integration. The first prefix helper review missed quadratic scanning and broad inner whitespace; it was superseded by a fresh algorithm review after correction. A green original-PR run or plan approval never substitutes for final implementation review. Outstanding GitHub objections and final-tip status are re-read before the coordinating maintainer's decision.
+
+## Execution record
+
+Each work phase used its own persisted P-A-B-C-D cycle: roadmap, claim, affinity, prefix, native-affinity repair, prefix adaptation, affinity adaptation, Hermes contract, serial affinity slot, linear prefix repair, final prefix slot, then hosted-evidence verification. Source and conflict reviews used inherited-model read-only subagents; no native architect role was claimed.
+
+Local tests of every size, build, typecheck and install were **NOT RUN** by explicit instruction. Local receipts contain text/applicability checks only. Product execution belongs to the linked GitHub-hosted runs; skipped Windows full shards and macOS control are not passing executions. Pushes used `--no-verify`, with exact old-head leases for owned branch rebases. This task did not merge, release, publish packages, restart services or change user runtime settings.
+
+## Final evidence-cycle record
+
+The final evidence B phase produces this tracked update as its documentation artifact. An earlier C transition was rejected by SOURCE-DELTA-01 because only scratch metadata and the PR body had changed; that rejected transition did not advance the FSM. The evidence branch now records the actual delivered source heads, parent integrations and unproven closure attribution. It changes no runtime code. Hosted terminal results must still be read before this cycle closes; an evidence document is not a product-test pass.
+
+## Resumed terminal-CI reconciliation
+
+The original final-tip results are now terminal: affinity run `34674962749` FAILED (native restore/injection fixtures); prefix run `34675829597` FAILED (the same restore family plus Cline registry/CLI/localization/icon/test-layout expectations); Hermes run `34674763850` FAILED (Combo active-reactivation GUI fixture). Their passing cache assertions do not make those runs green. Claim run `34673563105` remains SUCCESS and was not rerun.
+
+Shared fixture repair #4390 is merged at `20861aebf56c6f8ec2b0d8d04d1d0b54441650bb`, containing the delivered affinity and repaired prefix heads by verified Git ancestry. Its [hosted CI 34688482827](https://github.com/lidge-jun/opencodex/actions/runs/34688482827) succeeded: 19 jobs successful, 2 skipped. This is new cumulative integration evidence, not a relabeling of the old failed results. Cache runtime sources were not rewritten to fix another lane's failure.
+
+The remaining open Hermes PR #4365 is refreshed onto `392e182a004d61b38c7cf652642e63b9a11d9a65` without conflicts, preserving its test-only delta. Its new final head and hosted outcome are exported to that PR description and the scratch handoff after source audit and publication. Merged evidence PR #4377 is left intact. The host goal is blocked; persisted phase C is preserved and neither is claimed completed. Local product suites/build/typecheck/install remain NOT RUN.
+
+Final Hermes slot: the coordinator pinned `c311f9bf7f5003af29fa8e7ebc2f2b5db20267f6` after the pnpm/Devin fixture corrections. The test-only PR is rebased onto that fixed base without conflicts or runtime edits. Its exact final-head source review and hosted run replace the earlier `524afd8d80` candidate evidence in the PR description. The previous failed runs remain historical failures, and actual Hermes client-field acceptance remains open.
diff --git a/devlog/_plan/260912_campaign_ci_fixtures/000_plan.md b/devlog/_plan/260912_campaign_ci_fixtures/000_plan.md
new file mode 100644
index 0000000000..c3d4ba1884
--- /dev/null
+++ b/devlog/_plan/260912_campaign_ci_fixtures/000_plan.md
@@ -0,0 +1,12 @@
+# Campaign integration fixture repairs
+
+Hosted CI exposed incomplete Cline registration follow-through and restore fixtures that no longer exercise the documented atomic refusal contract. This change repairs those contracts without changing credential or restore behavior.
+
+- Trigger/evidence: Cross-platform CI run 34676570087, head 954b1da7804110e440acc9d244e70f32f2aa9aae. Linux, macOS and dashboard gate failures are retained as the failing baseline evidence; no local reproduction is claimed.
+- Cline: correct the lightweight CLI count to fifteen, preserve exact registry equality, recognize only the Cline product-name keys as intentional English, document reuse of its existing mark, and align client/writer test seeds with their committed domain.
+- Restore: assert unsuccessful all-skipped results and unchanged artifacts after refusal; retain exact pre-operation config/profile/journal snapshots when damaged defaults prevent restoration. Canonicalize temporary homes and target the production profile path so macOS fault injection and manifest lookup actually reach the intended boundary. Assert a matching injected read and default manifest visibility.
+- Non-goals: no runtime restore/auth changes, test skips, weaker error/preservation assertions, new dependencies, local tests/build/typecheck/install, release or deployment.
+- Verification: git diff --check for text; independent source review of Cline and restore slices; final-head hosted CI must execute the unchanged failure paths and pass before completion. Local product execution remains NOT RUN.
+- Stop: the original named failures pass at the published final head and no new blocking finding remains. An unrelated CI failure is investigated separately, not waived here.
+
+The shared baseline also includes the independently reviewed Combo reactivation correction from #4385. It explicitly runs the actual activation callback and preserves the cached quota evidence, dirty draft and Save-state assertions. This known scheduling defect must not remain in the baseline supplied to other campaign PRs. The #4385 source commit is preserved by merge; close that duplicate delivery only after this combined baseline lands.
diff --git a/devlog/_plan/260912_catalog_lane_readiness/000_plan.md b/devlog/_plan/260912_catalog_lane_readiness/000_plan.md
new file mode 100644
index 0000000000..f961b79e73
--- /dev/null
+++ b/devlog/_plan/260912_catalog_lane_readiness/000_plan.md
@@ -0,0 +1,11 @@
+# Catalog chain readiness
+
+Review the existing catalog chain without duplicating its implementation. The lane produces a precise integration handoff; an additional product PR exists only if a concrete defect or necessary regression gap remains.
+
+Loop: satisfy-spec, triggered by the catalog lane delegation. Class C3 review; security changes would promote their slice to C4. Goal: readiness for #4325 -> #4328 -> #4331. Non-goals: merging, original branch writes, issue closure, release, services and configuration. Local suites of every size are NOT RUN, including wrappers; large local install/build/typecheck are also excluded. Only task-owned files and scoped commits/push --no-verify/PR creation are authorized. Existing GitHub credentials only; no user token/time/agent-count bound.
+
+Verifier: live gh PR/review/run JSON and Git ancestry/source inspection observe exact catalog tips; product suites execute only on hosted CI. Text checks observe these documents, never establish product test success. Stop: durable exact-head evidence/disposition plus honest remaining acceptance. Outcomes: DONE for completed readiness scope, NOOP for existing sufficient implementation, NEEDS_HUMAN for unresolved integration decisions, BLOCKED only for demonstrated unavailable prerequisites. Memory artifact: this unit and ignored .tmp/catalog-review/HANDOFF.md. Escalation: original-task write collision or necessary authority beyond scope goes to parent; two failed distinct reviewer calls are reclaimed with independent-review gap recorded.
+
+Dependency order: roadmap (010), scoped review/coverage (020), final hosted CI and GUI evidence (030). No native stacks. Preserve public author commits. Source of truth: structure/gui-and-management-api.md, changed only if a product contract changes. No new fields, enums, enforcement or interfaces planned. Native architect role is not exposed; supported inherited-model design review and reflection provide consultation per explicit user direction, without claiming native role selection. User explicitly instructs independent work to continue when tools are unavailable.
+
+Parent scope correction: existing owner is merging its own chain; this lane reconciles read-only, with own follow-up only for a concrete newly verified defect. Supported inherited-model independent design review replaces the unavailable native-role transport per explicit user direction, without claiming native architect selection.
diff --git a/devlog/_plan/260912_catalog_lane_readiness/010_roadmap.md b/devlog/_plan/260912_catalog_lane_readiness/010_roadmap.md
new file mode 100644
index 0000000000..51958d8370
--- /dev/null
+++ b/devlog/_plan/260912_catalog_lane_readiness/010_roadmap.md
@@ -0,0 +1,2 @@
+# Roadmap documentation cycle
+NEW 000_plan.md and decade documents 010/020/030 in this unit; before: absent; after: outcome, authority, exact read targets and acceptance. NEW .tmp/catalog-review/HANDOFF.md: identity, current PR states and evidence pointers. No product delta. Check: read all four documents and git diff --check; confirm every phase has real outputs and user restrictions. D locks this roadmap and directs the next cycle to review exact tip source.
diff --git a/devlog/_plan/260912_catalog_lane_readiness/011_design_reflection.md b/devlog/_plan/260912_catalog_lane_readiness/011_design_reflection.md
new file mode 100644
index 0000000000..51fe050002
--- /dev/null
+++ b/devlog/_plan/260912_catalog_lane_readiness/011_design_reflection.md
@@ -0,0 +1,2 @@
+# Design review dispositions
+Inherited-model read-only reviewer Hilbert supplied CAT-DEC-01..06. Main accepts evidence ownership (01), exact-head provenance (02), no-suite restrictions (05). Amended collision boundary (03) to require a concrete new defect plus owner/head refresh and parent coordination. Amended consultation (04) to distinguish supported independent design reflection from unavailable native architect role. Amended integration authority (06) to preserve separately authorized original-owner merges and parent-only follow-up integration. Reflection recheck requested after amendments.
diff --git a/devlog/_plan/260912_catalog_lane_readiness/020_review.md b/devlog/_plan/260912_catalog_lane_readiness/020_review.md
new file mode 100644
index 0000000000..38c3be5e77
--- /dev/null
+++ b/devlog/_plan/260912_catalog_lane_readiness/020_review.md
@@ -0,0 +1,4 @@
+# Scoped review and coverage cycle
+Depends on roadmap. READ exact #4331 head gui/src/components/AddProviderModal.tsx, provider-catalog/ProviderCatalog.tsx, CatalogAccountRow.tsx, ProviderNoteModal.tsx, provider-presets.ts, gui/tests/provider-catalog-search.test.tsx and tests/gui/provider-workspace-data.test.ts. READ #4328 diff and live review threads. NEW .tmp/catalog-review/020_review.md: file:line findings, dispositions, remaining acceptance and attribution. Before: no independent lane review; after: a checked result against the pinned SHA.
+
+Potential MODIFY gui/tests/provider-catalog-search.test.tsx only for a concrete defect absent from the existing owner work, after refreshing owner/head evidence and parent coordination. A coverage gap alone is not authority to duplicate the owner delivery. Activate Escape with a nonempty query then empty query; expect query clear before modal close. Activate ArrowDown from search with a disabled first account control and later enabled controls; expect the first enabled result to receive focus. Also inspect no-actionable-result behavior and note-popup -> query -> dialog Escape ordering. If required, append a precise repair work-phase at P and use a separate task-owned child branch of the refreshed final tip; never edit the original branch. Reuse existing tests and source docs, no speculative abstraction. No test execution locally. Check: independent source review, diff --check and GitHub-hosted CI for any new code. If no patch is justified, record NOOP explicitly.
diff --git a/devlog/_plan/260912_catalog_lane_readiness/022_keyboard_repair.md b/devlog/_plan/260912_catalog_lane_readiness/022_keyboard_repair.md
new file mode 100644
index 0000000000..ff3a9ebcf1
--- /dev/null
+++ b/devlog/_plan/260912_catalog_lane_readiness/022_keyboard_repair.md
@@ -0,0 +1,13 @@
+# Keyboard repair plan
+
+Previous D locked the docs-only roadmap; source reconciliation now establishes one new defect. The original owner merged #4331 at 9a37813593514c2d90b1ebac129c4541fd2a9af4; its reviewed source tip a154645d76e98af199fd79aff8c8d393afaf30ab passed hosted CI 34672274572. This task rebased only its own unpushed roadmap commit onto that dev tip. Parent was notified of the new distinct defect; original task scope readback shows only tab overflow, description disclosure and popup focus repairs.
+
+Class C1 behavioral patch plus existing-test coverage; no new abstraction, type, field, token, endpoint, UI copy or dependency. Do-nothing would retain a broken keyboard path; configuration cannot change the selector; reuse the existing handler and test mount. Product diff is confined to the existing selector.
+
+MODIFY gui/src/components/provider-catalog/ProviderCatalog.tsx:207: before querySelector("button, a[href]"); after querySelector("button:not(:disabled), a[href]"). CSS :disabled also excludes a disabled fieldset descendant, while preserving actionable anchors.
+
+MODIFY gui/tests/provider-catalog-search.test.tsx: append behavior tests using current mount/type/search helpers. Busy openai Codex row (logged out, onAccountLogin supplied), query nvidia: disabled account button is first in DOM, ArrowDown must focus NVIDIA preset and prevent default. Same busy account with unmatched query and no other actionable row: focus stays on search and default remains untouched. Empty results: same no-op. A normal preset-only query checks normal first-result focus. All tests dispatch a bubbling/cancelable KeyboardEvent from the focused input inside act. No sleep helper or exported test-only production function.
+
+MODIFY structure/gui-and-management-api.md Add provider row: ArrowDown focuses first enabled result action; no available action leaves input focus unchanged. MODIFY docs-site/src/content/docs/guides/web-dashboard.md Add provider row with the same keyboard behavior, translated pages must not contradict (they currently say nothing about this shortcut).
+
+Verification: git diff --check for patch formatting ONLY, independent source audit, GitHub-hosted Cross-platform CI at the exact published head. No local test/build/typecheck/install. Read hosted preview artifact from that run if GUI evidence requires it; serve artifact in scratch without product build, no live proxy mutation. No original branch/PR mutation, merge or auto-merge. Existing author commits stay in ancestry. Follow-up ordinary PR targets dev because original chain is now merged.
diff --git a/devlog/_plan/260912_catalog_lane_readiness/030_evidence.md b/devlog/_plan/260912_catalog_lane_readiness/030_evidence.md
new file mode 100644
index 0000000000..763f2c5965
--- /dev/null
+++ b/devlog/_plan/260912_catalog_lane_readiness/030_evidence.md
@@ -0,0 +1,6 @@
+# Final evidence and handoff cycle
+Depends on reviewed source/repair disposition. READ live gh pr view for #4325/#4328/#4331 and any follow-up, GraphQL reviewThreads, gh run view for exact head, workflow triggers and Git ancestry. READ screenshots carried by the source PR using local git blobs; observe them with image viewer, distinguish screenshot commit from final source head. NEW .tmp/catalog-review/030_evidence.md with CI run IDs/URLs, job outcomes, missing/skipped distinctions, GUI provenance and outstanding reviews. MODIFY .tmp/catalog-review/HANDOFF.md from preliminary to complete: worktree/branch, own phase/cycle evidence, all original PR dispositions, final chain/head SHAs, authors, remaining acceptance and local tests NOT RUN. No product change. Check: exact SHA equality between PR and CI plus fresh PR state; do not claim intermediate tips passed. This lane never merges or retargets. Reconcile the original-chain delivery by its separately authorized existing owner; parent controls additional follow-up integration.
+
+Inspect exact-tip hosted dashboard preview artifact if available; compare narrow-width tabs and popup focus against historical screenshots. If preview cannot be exercised within authorized no-build/no-install scope, leave final-tip dynamic GUI acceptance explicitly unmet, not inferred from old PNGs.
+
+Record observation timestamp, base SHA, workflow event/run attempt and merge commit. Head/base movement triggers reconciliation refresh.
diff --git a/devlog/_plan/260912_cline_client/000_plan.md b/devlog/_plan/260912_cline_client/000_plan.md
new file mode 100644
index 0000000000..db1e08735d
--- /dev/null
+++ b/devlog/_plan/260912_cline_client/000_plan.md
@@ -0,0 +1,24 @@
+# Cline integration roadmap
+
+Cline users need a reversible connection and routed model list. This unit connects the current Cline CLI storage contract through the existing integration operations and dashboard. Cline stores connection settings and the model catalog separately, so one operation must snapshot and restore both files.
+
+Loop: satisfy-spec, HOTL; trigger: #4214 and delegated lane=cline. Scope: config exporters, integration writer/reader/journal projection, existing CLI/catalog/dashboard registries, translated copy, source fixtures. Non-goals: legacy extension storage migration, Cline process control, user configuration changes during development, merges/releases, new dependencies. All local product suites, builds/typecheck/install are NOT RUN by instruction; regression execution belongs to final-tip GitHub hosted CI. Text checks and independent source audits are allowed. No user token/time/agent caps; existing tool/account scope only.
+
+Outcome: DONE requires source-backed contracts, actual implementation, separate PABCD cycles, independent reviews, final cumulative head CI, PR and durable handoff. Unavailable tools or genuine external blockers are recorded without claiming completion. Main implements; inherited read-only subagents review. Native architect role selection is unavailable; the explicit parent instruction authorizes supported spawn for actual design and reflection reviews. No role installation or settings changes.
+
+Sources: [001_contract.md](001_contract.md). Repository owners: src/clients/config-export.ts, src/integrations/{registry,state,writer,journal,store,config-io}. Existing config builder, exact fragment ownership, atomic file writes and journal are reused. No-op/manual-only configuration cannot meet sync/undo; a separate standalone configuration engine is unnecessary.
+
+| Cycle | Deliverable | Dependency | Design |
+| --- | --- | --- | --- |
+| roadmap | Audited docs only | none | This roadmap and all decade docs |
+| contract | Pure Cline documents, paths, paired journal adapter and regression fixtures | roadmap | 010_contract.md |
+| surfaces | Catalog refresh, CLI help and existing dashboard exposure | contract | 020_surfaces.md |
+| verification | Independent audit, fixes, PR publication and final-tip hosted CI | surfaces | 030_verification.md |
+
+PR decision: one cohesive Cline PR unless the audited paired-file foundation is independently useful and large enough to split. Ordinary manual chain only if split; no native stacks. Intermediate commits may be pushed without waiting on CI. Parent owns merge.
+
+Verification: git diff --check (text only), source review, final-head Cross-platform CI (tests/typecheck/GUI build/lint). Source tests use temporary home/store; no real Cline data. Fixture cases: missing/partial install; malformed, non-regular or foreign edited files; wrong version; foreign provider preserved; owned model removal/port change; second-file failure; bookkeeping failure; interrupted transaction and drift; exact two-file restore including absence. A Cline restart is required after externally written catalogs. Live client process behavior is source-backed, not a claimed local canary.
+
+Public source docs update structure/clients/integrations.md plus CLI/UI owning docs for changed surfaces; public user workflow resides in docs-site. Unreleased security analysis stays under .tmp/cline. Durable handoff: .tmp/cline/handoff.md.
+
+Design reflection: ALIGNED D09/D10. R02 accepted: no unattended Cline refresh; explicit sync only with stopped-client precondition. R03 accepted: journal presence never blesses a mixed pair or inconsistent ownership. Verify both intended bytes and final record before clearing a committed marker.
diff --git a/devlog/_plan/260912_cline_client/001_contract.md b/devlog/_plan/260912_cline_client/001_contract.md
new file mode 100644
index 0000000000..bbd9cd3c0d
--- /dev/null
+++ b/devlog/_plan/260912_cline_client/001_contract.md
@@ -0,0 +1,14 @@
+# Cline source contract
+
+Upstream revision: cline/cline cfe9cadab99617d5013bf89f07b079d105057791, read 2026-09-12. Scope is the current CLI/shared SDK provider store. Legacy VS Code globalState/secrets storage is not the same contract and is not detected as compatible.
+
+- sdk/packages/shared/src/storage/paths.ts:152-185,424-430 resolves CLINE_PROVIDER_SETTINGS_PATH; otherwise CLINE_DATA_DIR/settings/providers.json; otherwise CLINE_DIR/data/settings/providers.json; otherwise ~/.cline/data/settings/providers.json. Relative overrides are rejected by OpenCodex because its cwd is not Cline's cwd.
+- sdk/packages/core/src/types/provider-settings.ts:33-68 defines version=1, optional lastUsedProvider, modes={}, providers[id]={settings,updatedAt,tokenSource}. settings.provider is the provider ID; protocol openai-responses, client openai, baseUrl, apiKey and model are accepted.
+- sdk/packages/core/src/services/llms/provider-settings.ts:155-199,224-315 maps protocol openai-responses to the OpenAI handler while retaining the custom provider ID and namespaced model.
+- sdk/packages/core/src/services/providers/local-provider-registry.ts:48-121 defines sibling models.json: version=1, providers[id]={provider:{name,baseUrl,protocol,client,defaultModelId},models:{id:{name,contextWindow,modalities,supportsVision}}}.
+- The same file:689-716 caches model-file loading per process. Restart Cline after external updates; do not claim a running picker is live-synchronized.
+
+CLINE-D09 accepted: settings.modelCatalog.url is not an OpenAI /v1/models endpoint. Its loader expects models.dev data, and picker paths do not forward that setting. A single providers.json does not meet full catalog acceptance.
+CLINE-D10 accepted: write providers.json plus sibling models.json as one recoverable journal operation. Each rename is atomic; a filesystem has no atomic rename across both files. Stop Cline before apply/refresh/restore and restart after. Interrupted writes require durable recovery and foreign edits must refuse recovery.
+
+All paths above are pinned under https://github.com/cline/cline/blob/cfe9cadab99617d5013bf89f07b079d105057791/ . No upstream implementation is copied; schema-shaped fixtures use synthetic data. No original carry PR or author credit applies. #3833 is a Command Code reference, not a dependency.
diff --git a/devlog/_plan/260912_cline_client/009_roadmap_result.md b/devlog/_plan/260912_cline_client/009_roadmap_result.md
new file mode 100644
index 0000000000..d5fe20dcb0
--- /dev/null
+++ b/devlog/_plan/260912_cline_client/009_roadmap_result.md
@@ -0,0 +1,5 @@
+# Roadmap cycle result
+
+Docs-only roadmap locked after inherited source/design review and independent A audit. Accepted D09/D10, excluded unattended refresh, strengthened journaled recovery recognition, and added target collision refusal. Existing CLI syntax is --client cline / restore --op; no positional alias is invented.
+
+Source audit confirms two files are needed. No product files changed in this cycle. git diff --check is the permitted document whitespace check; local product tests are NOT RUN. Next cycle executes 010_contract.md; downstream implementation and hosted proof remain open. The one-file modelCatalog URL hypothesis did not survive upstream inspection.
diff --git a/devlog/_plan/260912_cline_client/010_contract.md b/devlog/_plan/260912_cline_client/010_contract.md
new file mode 100644
index 0000000000..d822cd1881
--- /dev/null
+++ b/devlog/_plan/260912_cline_client/010_contract.md
@@ -0,0 +1,26 @@
+# Contract and paired-file operations
+
+Depends on roadmap. C4 care for reversible config mutation; no local execution. Use existing journal and ownership, not a second ownership database.
+
+NEW src/clients/config-export/cline.ts: typed pure buildClineClientConfig, summarizeCline and buildClineContribution. Build {settings:{version:1,modes:{},providers:{opencodex:{settings:{provider:'opencodex',protocol:'openai-responses',client:'openai',apiKey:LOOPBACK_API_KEY_PLACEHOLDER,baseUrl},updatedAt:stable schema timestamp,tokenSource:'manual'}}},catalog:{version:1,providers:{opencodex:{provider:{name:'OpenCodex',baseUrl,protocol:'openai-responses',client:'openai'},models}}}}. Namespaced routed IDs are model-map keys. Preserve authoritative context and modality metadata; omit invented costs/output limits. Do not manage lastUsedProvider: users select OpenCodex explicitly (cline --provider opencodex --model provider/model), preserving their default. Empty catalog exports no invented default/model. Managed paths are settings.providers.opencodex and catalog.providers.opencodex; schema envelope defaults are initialized only when absent and retained on disable.
+
+MODIFY src/clients/config-export/contracts.ts: append cline to ExportClientId. Creation: EXPORT_CLIENTS; serialization: builder/JSON download; deserialization: isExportClientId and journal isIntegrationClientId; consumers: integration registries, CLI export, management route and browser lists in 020.
+MODIFY src/clients/config-export.ts: import/register cline builder and append EXPORT_CLIENTS.cline; export path helpers using existing absoluteClientPath. destination is providers.json; filename cline-config-bundle.json; format json; hint explains two document members and restart, no standalone direct-file claim; loopbackOnly true.
+MODIFY src/integrations/registry.ts: append cline paths, detect settings directory, sibling lock .lock. Resolve explicit provider-file override first and derive catalog from dirname; no user discovery scanning.
+
+NEW src/integrations/cline-document.ts: private codec between two raw file strings (snapshot bundle) and logical settings/catalog objects (managed fragments). Reads preserve exact raw bytes and file absence. Parsing invokes existing safe strict JSON parser for each member; reject invalid/non-object schema and unsupported version. Rendering initializes missing version=1/modes={} and serializes both native files, then canonicalizes the raw-string snapshot envelope. Never serialize journal-only metadata into Cline files.
+NEW src/integrations/cline-io.ts: adapt the existing IntegrationIO only for cline and the resolved primary path. Secondary path is dirname(primary)/models.json; no caller-provided arbitrary secondary path. Reject primary path named models.json (case-insensitive), and refuse symlink/non-regular members so two logical members cannot alias one target. Read/stat inspect both members; write uses existing atomic writer for each, compensates on any failure. Snapshot remains the existing journal's one bundle snapshot. Persist a private pending transaction before first rename, including original/result bundle and prior ownership; clear only after journal append. Recover an interrupted operation only on an explicit mutation, only if every current file is exactly original or intended result; if its opId is already journaled, recognize completion only when BOTH intended bytes and final ownership match; otherwise retain unsafe pending state. Foreign edits or invalid pending data refuse and retain recovery evidence. Read-only status never performs recovery. Report partial compensation failure truthfully.
+MODIFY src/integrations/config-io.ts: optional begin/finish transaction hooks on IntegrationIO; existing clients unaffected.
+MODIFY src/integrations/writer.ts: resolve Cline adapter after path resolution, invoke begin hook before commit; use client codec at parse/render boundaries; finish after journal or successful compensation; preserve existing state/refusal logic. Restore reads the same bundle and journal. Coordinated mutation locks encompass recovery and commit.
+MODIFY src/integrations/state.ts: same adapter/codec for classification; pending state unsafe; no mutation on read. Journal API's matchesOperationResult projection reads through the adapter so restore eligibility describes both files.
+MODIFY structure/clients/integrations.md: state two-file ownership and transaction/restart/rollback contract.
+
+NEW tests/clients/cline-client.test.ts: source-shaped generation, env precedence, no secrets, model removal/metadata, initialized install and missing install. NEW tests/clients/cline-writer.test.ts: temporary home and store with real writer, both-file exact restore, absent member restore, invalid JSON/schema, occupied provider refusal/explicit overwrite, foreign edits, second-file and journal failures, crash recovery and foreign-edit refusal. Register both paths in scripts/test-layout/layout.json and tests/fixtures/test-layout-expected.json. Extend existing exact client-list assertions without deleting checks.
+
+Activation evidence is final-tip hosted tests. Locally only diff/text audit; code unverified until hosted result. Pending marker is an early recovery mechanism, not cross-process exclusion against Cline: Cline does not share OpenCodex's lock. User-visible contract requires it stopped; filesystem rename cannot prevent a non-cooperating writer. No claim of simultaneous two-file visibility.
+
+A synthesis: accepted target collision guard and regression; post-journal marker cleanup is best-effort and must not cause compensation. Normal Cline settings saves update updatedAt/model, so declare only settings.providers.opencodex.updatedAt and settings.providers.opencodex.settings.model as refreshable; preserve selected model while still in desired catalog, remove it if no longer routed. All connection/auth metadata remains protected.
+
+Contract P resumes previous D: "Docs-only roadmap complete; next contract cycle" (009). No product source changed since source inspection. Implementation uses existing JSON format plus client-specific parse/render dispatch, avoiding a new public ConfigFormat enum. Export is a human-readable {settings,catalog} document bundle; internal journal envelope stores each raw file string for exact restore. This distinction is explicitly documented and tested. Path helper implementation additionally rejects case-insensitive models.json collision. No product command is executed locally.
+
+Implementation delta: cline builder/paths, private raw pair codec, paired IO and pending journal hooks are implemented; normal model/timestamp writes use the existing narrow refreshable-path mechanism. Existing lifecycle tests now read Cline's logical pair through the production adapter instead of treating its primary file as the whole document. Source checks only so far; hosted suite remains in verification cycle. New tests cover file absence, unsafe version/nonregular member, explicit conflict overwrite, model retirement, foreign edits, write/bookkeeping failure and pending recovery.
diff --git a/devlog/_plan/260912_cline_client/019_contract_result.md b/devlog/_plan/260912_cline_client/019_contract_result.md
new file mode 100644
index 0000000000..77d93bddca
--- /dev/null
+++ b/devlog/_plan/260912_cline_client/019_contract_result.md
@@ -0,0 +1,5 @@
+# Contract implementation checkpoint
+
+The Cline builder, path resolver, raw-byte pair projection, pending recovery and existing writer/journal integration are implemented. Regression source covers normal lifecycle, native schema refusal, two-file compensation and recoverable interruption. Independent implementation review is in flight and is a required input to the final verification cycle.
+
+Local product tests, typecheck, builds and installation: NOT RUN by explicit user instruction. This checkpoint asserts code/source completion only; runtime correctness remains unverified until final cumulative hosted CI. git diff --check is the permitted text check. Next cycle wires existing CLI/dashboard surfaces and explicit catalog sync. No PR or merge yet.
diff --git a/devlog/_plan/260912_cline_client/020_surfaces.md b/devlog/_plan/260912_cline_client/020_surfaces.md
new file mode 100644
index 0000000000..6114503acf
--- /dev/null
+++ b/devlog/_plan/260912_cline_client/020_surfaces.md
@@ -0,0 +1,14 @@
+# Existing CLI, catalog and dashboard surfaces
+
+Depends on contract; re-read source after 010 before B. Extend existing entry maps, no new endpoint/component architecture.
+
+Keep Cline out of unattended catalog-refresh default ids because the client must be stopped. MODIFY explicit sync lists src/cli/dispatch.ts and src/server/management/config-routes.ts: append cline. Keep lazy owned-only refresh and foreign-edit refusal; regression in tests/clients/cline-writer.test.ts verifies unowned untouched, owned refresh changes both files, model removal and endpoint changes.
+MODIFY src/cli/registry.ts export usage/summary: append cline/Cline. Existing integration verbs remain --client cline and restore --op ID; documentation must not invent positional arguments. Update focused CLI export/list expectations and existing sync source fixtures.
+
+MODIFY gui/src/pages/integrations/integration-api.ts client tuple, integration-tabs.ts TABS/FILE_CLIENTS, gui/src/app-routing.ts hash list, overview-clients.ts label map, FileIntegrationPage.tsx semantics/label maps, gui/src/components/apikeys-workspace/client-config-clients.ts CLIENTS/labels/marks, gui/src/components/integration-marks.ts exhaustive map: append cline. Reuse existing page and consequence/rollback dialogs. Reuse the existing gui/public/provider-icons/cline-color.svg already used by provider-icons.ts; no new brand asset.
+MODIFY all gui/src/i18n locale modules: append integrations.tab.cline, integrations.semantics.cline, api.clientConfig.clientCline. Copy states: current Cline CLI provider store; both files; stop before mutations, restart after; Undo restores both originals; default provider remains user-controlled. Parent handoff records these exact shared-file touches.
+MODIFY docs-site/src/content/docs/guides/integrations.md: documented installation contract, env precedence, --client verbs, conflict opt-in, --op restore/drift, two-file export format and running-client limitation. Update structure/runtime.md and structure GUI/CLI ownership docs where applicable with factual links to canonical integration contract.
+
+Verification: existing GUI client-list/route/i18n assertions extended for cline. No local GUI tests/build. Final hosted GUI build/lint/tests; obtain hosted screenshot artifact where available and inspect it. If unavailable report missing visual evidence rather than fabricate screenshot. No real user server configuration is used for capture.
+
+Surfaces P resumes 019: "next cycle wires existing CLI/dashboard surfaces and explicit catalog sync." Source lists still end in omo; append Cline only. Existing cline-color.svg is reused. Public guide path verified as guides/integrations.md. Independent core audit corrections remain mandatory in the final verification cycle; these list/copy changes do not depend on its implementation details.
diff --git a/devlog/_plan/260912_cline_client/029_surfaces_result.md b/devlog/_plan/260912_cline_client/029_surfaces_result.md
new file mode 100644
index 0000000000..eecf696e87
--- /dev/null
+++ b/devlog/_plan/260912_cline_client/029_surfaces_result.md
@@ -0,0 +1,5 @@
+# Surface wiring checkpoint
+
+Cline CLI appears in existing integration, export, route and mark registries. Nine dashboard locales explain the paired-file stop/restart and Undo contract. English and existing translated integration guides identify the current CLI schema. Explicit sync includes previously owned Cline files; unattended catalog refresh excludes Cline.
+
+The existing committed Cline color mark is reused. No layout or new UI component was introduced. Local GUI tests/build/typecheck and product suites are NOT RUN. git diff --check is text-only evidence. Runtime and rendered verification remain on the final cumulative hosted tip; core recovery review corrections remain mandatory in the next cycle. Next direction: inspect the two concrete recovery findings, repair with regression source, then publish and track CI.
diff --git a/devlog/_plan/260912_cline_client/030_verification.md b/devlog/_plan/260912_cline_client/030_verification.md
new file mode 100644
index 0000000000..30abc74225
--- /dev/null
+++ b/devlog/_plan/260912_cline_client/030_verification.md
@@ -0,0 +1,13 @@
+# Independent audit and final hosted tip
+
+Depends on surfaces. Audit all acceptance rows against final source and tests; use a fresh inherited read-only subagent (no local tests/build/install, no user data or writes). Fold correct findings into code and docs in this cycle; add further cycles if a new implementation unit is needed. Security analysis stays in .tmp/cline.
+
+MODIFY only files implicated by concrete findings. git diff --check is whitespace evidence, never test evidence. Commit scoped source and docs; git push --no-verify origin HEAD. Create ordinary PR with base dev (or actual parent branch if audited split), filling Summary/Verification/Checklist and linking #4214 without claiming unresolved acceptance. No original PR exists; no carried author identity invented.
+
+Read current head/base/reviews and CI workflow event/ref. Track final cumulative SHA through hosted Cross-platform CI; record run URL/ID, actual head and check results. Do not cancel runs or modify workflow/protection. Fix attributable final failures and repeat at the resulting head. No suite can be hidden in a receipt helper; receipt can capture permitted source checks or read-only GitHub CI verification, labeled accurately.
+
+MODIFY .tmp/cline/handoff.md immediately after each deliverable: worktree/branch, PABCD cycle/phase, PR URL/full head SHA/order, issue disposition, remaining acceptance, attribution, hosted run evidence, NOT RUN local checks and unresolved reviewer findings. Final completion requires all recorded criteria; CI pending is not success. Parent performs all merges and decides issue closure.
+
+Verification P resumes 029's next direction. Concrete private audit repair plan is .tmp/cline/repair-plan.md; final source proof must include strict recovery metadata and history reads. Two accepted independent findings are being corrected before publication. This cycle retains all original CI, source, rollback and handoff criteria.
+
+Source review also found the shared export dialog described every download as a single native file. The Cline branch now uses localized two-document merge instructions and download announcement, and suppresses the irrelevant missing-key hint. Other clients retain their existing copy. A rendered component regression in client-config-panel.test.tsx covers this conditional branch on hosted CI. This is a correctness fix to the existing export surface, not a new export mechanism.
diff --git a/devlog/_plan/260912_cline_client/039_gui_evidence.md b/devlog/_plan/260912_cline_client/039_gui_evidence.md
new file mode 100644
index 0000000000..a31987f7aa
--- /dev/null
+++ b/devlog/_plan/260912_cline_client/039_gui_evidence.md
@@ -0,0 +1,25 @@
+# Cline component render evidence
+
+Source commit: 75a8ec8f78718f25343344506e8a5536ca0245a4. GUI tree: bd02a7729603ac669acf47988b065bd8d04dd617.
+
+The actual FileIntegrationPage and ClientConfigDialog components were rendered in Chrome at
+1280 × 773 CSS pixels, DPR 2, with the repository stylesheet, LanguageProvider and committed
+Cline mark. The surrounding header labels the view synthetic. Fetch was replaced with fixed
+fictional status/history; no real Cline configuration or running OpenCodex API was accessed.
+
+The source-only preview entry was bundled with Bun in 20 ms using existing React 19.2.8,
+without install, typecheck or product build scripts. This is manual component render evidence,
+not a test-suite pass, live client canary, or full dashboard build. Local suites remain NOT RUN.
+
+Observed: Cline label/mark, applied status, localized two-file stop/restart explanation, primary
+path and Undo history rendered without clipping. Export dialog shows the settings/catalog bundle.
+
+![Cline integration with synthetic state](evidence/cline-integration.png)
+
+The export dialog was scrolled to its instructions. Observed both destination file names, the
+journaled integration recommendation and stop/restart explanation; the single-file merge hint
+and missing-admission-key hint are absent for Cline.
+
+![Cline two-file export instructions](evidence/cline-export.png)
+
+Export capture refreshed after removing the irrelevant Set-the-key heading. GUI tree: a070b75cabe1974e59d407c595709d1ffb3c4a58. Same synthetic harness; entry bundling took 19 ms. No local test execution.
diff --git a/devlog/_plan/260912_cline_client/evidence/cline-export.png b/devlog/_plan/260912_cline_client/evidence/cline-export.png
new file mode 100644
index 0000000000..24ab32d0e9
Binary files /dev/null and b/devlog/_plan/260912_cline_client/evidence/cline-export.png differ
diff --git a/devlog/_plan/260912_cline_client/evidence/cline-integration.png b/devlog/_plan/260912_cline_client/evidence/cline-integration.png
new file mode 100644
index 0000000000..eba8e8252e
Binary files /dev/null and b/devlog/_plan/260912_cline_client/evidence/cline-integration.png differ
diff --git a/devlog/_plan/260912_codex_gpt54_retirement/000_plan.md b/devlog/_plan/260912_codex_gpt54_retirement/000_plan.md
new file mode 100644
index 0000000000..2f9e01b486
--- /dev/null
+++ b/devlog/_plan/260912_codex_gpt54_retirement/000_plan.md
@@ -0,0 +1,108 @@
+# gpt-5.4 / gpt-5.4-mini retirement on the Codex login surface
+
+## Objective
+
+OpenAI retired `gpt-5.4` and `gpt-5.4-mini`. Remove them from the Codex (ChatGPT
+OAuth) login surface of this proxy: the native catalog, everything that projects it
+(`/v1/models`, the dashboard picker, the desktop projection, Claude discovery), and
+every opencodex-owned default that still dispatches one of the two slugs.
+
+The replacement floor is `gpt-5.6-luna` — it is now the cheapest native model on the
+ChatGPT login lane, so every helper/sidecar/warmup default lands there. The login
+provider's own `defaultModel` moves there too: `gpt-5.6-sol` was considered because it
+is priority 1 in the pinned snapshot and `gpt-5.4` held a general-purpose role, but the
+owner chose luna so a default that nobody asked for stays the cheapest live model
+(owner decision, 2026-09-12).
+
+## Constraints and scope boundary
+
+In scope: `src/codex/**`, `src/oauth/**`, `src/vision/**`, the Codex-login parts of
+`src/server/**`, `src/cli/**`, `src/types/**`, `src/lib/shadow-call.ts`, `gui/`,
+`docs/` (the maintainer-facing pages, not only `docs-site/`), `docs-site/` (all locales),
+`structure/`, `scripts/release-notes.ts`, and `tests/`.
+
+Out of scope, deliberately:
+
+- Third-party vendor rosters that publish their own snapshots — `github-copilot`
+  (`src/providers/registry.ts`), `cursor` (`src/adapters/cursor/*`), `codebuddy`,
+  `opencode`, `command-code`, and `scripts/model-metadata.source.json`. This follows
+  the `deepseek-v4-pro` precedent (`e86ab5bd8d`): a first-party retirement notice does
+  not end a vendor's deployment, and deleting their row would strip a live route's
+  context window and effort ladder while the model keeps arriving from `/models`.
+- Historical pricing in `src/usage/expected-prices.ts` and its tests. Past usage rows
+  still have to cost correctly after the model stops being routable.
+- Slugs that only look related: `gpt-5.4-nano`, `gpt-5.4-pro`, `gpt-5.4-high`,
+  `openai/gpt-5.4-mini` (OpenRouter metadata). None are part of this retirement.
+
+No push, PR, merge, release, or deploy. Local commits only.
+
+## Evidence gathered at P
+
+Three read-only `xai/grok-4.6` verifier subagents swept the tree in parallel. Their
+combined inventory: 146 files, 592 `gpt-5.4*` hits, of which the Codex-login-owned
+set is the one this unit changes.
+
+Structural findings that shape the phase order:
+
+1. `NATIVE_OPENAI_MODELS` (`src/codex/catalog/native-models.ts:156`) is the single
+   membership list. `SUPPORTED_NATIVE_OPENAI_SLUGS`, `nativeModelRows`,
+   `nativeOpenAiSlugs`, `accountBoundNativeOpenAiSlugsBySelector`,
+   `filterSupportedNativeSlugs`, `model-routes.ts` `supportedNative`, and
+   `CANONICAL_NATIVE_CATALOG_CONTENT_POLICY.nativeBackfillSlugs` all derive from it.
+   Removing the two slugs there propagates to every projection without further edits.
+2. Persisted BARE rows clean themselves up. Once the slugs leave the list,
+   `isUnsupportedOpenAiNativeSlug` returns true for `gpt-5.4` and `gpt-5.4-mini` and the
+   canonical merge runs `unsupportedNativeEntries: "drop"` (`sync.ts:847`, filter at
+   `1068-1070`), so a user's on-disk catalog loses them on the next sync.
+   Account-namespaced rows are a different path: that predicate returns false for any slug
+   containing `/` (`metadata.ts:113`), so `team/gpt-5.4` is not dropped by it. Those rows
+   stop being *generated* because `accountBoundNativeOpenAiSlugsBySelector` and
+   `availableAccountNativeSlugs` both seed from `NATIVE_OPENAI_MODELS`. wp2 must prove what
+   happens to an already-persisted `selector/gpt-5.4` row with a focused test rather than
+   assuming it disappears.
+3. `UPSTREAM_NATIVE_ENTRIES` never contained either slug — `upstreamNativeEntryForSlug`
+   admits only `gpt-5.6-*` and self-described natives — so deleting the two pinned rows
+   in `src/codex/data/upstream-models.json` changes capability fallbacks only, not the
+   sync-replacement authority. `gpt-5.2` and `codex-auto-review` stay pinned, which is
+   why `SELF_DESCRIBED_NATIVE_OPENAI_MODELS` must remain an explicit allowlist.
+4. The defaults are independent of the catalog list and fail separately. Warmup
+   (`src/codex/warmup.ts:30`), the token guardian (`src/oauth/token-guardian.ts:55`),
+   and the vision describer (`src/vision/plan.ts:14`) all still dispatch
+   `gpt-5.4-mini` and would 404 after retirement regardless of catalog membership.
+5. The startup sidecar migration (`src/server/index.ts:686`) rewrites a *stored*
+   `gpt-5.4-mini` to `gpt-5.6-luna`, but an unset vision model never equals that
+   string, so it falls through to `DEFAULT_VISION_MODEL` and still calls the retired
+   model. That gap is the reason wp3 exists as its own cycle.
+6. `DEFAULT_SHADOW_SOURCE_MODELS` is already `["gpt-5.6-luna"]`. `gpt-5.4-mini` there
+   is an *inbound* prefix for Codex 0.144.x helper calls, not a dispatch target, so it
+   stays documented as a restore option and is not treated as a retired default.
+
+## Work-phase map
+
+| Phase | Unit doc | Outcome | Depends on |
+|---|---|---|---|
+| wp1 | this document | Roadmap locked, scope boundary recorded | — |
+| wp2 | `010_catalog_removal.md` | The two slugs leave the native catalog and its pinned metadata | wp1 |
+| wp3 | `020_defaults_repoint.md` | Every opencodex-owned default moves to a live slug | wp1 |
+| wp4 | `030_surfaces_and_gate.md` | GUI, docs locales, structure docs, full gate, closing record | wp2, wp3 |
+
+wp2 and wp3 touch disjoint files and could run in either order; wp2 runs first because
+its membership decision is what the wp3 tests assert against.
+
+## Risks
+
+- **Over-removal.** Deleting a vendor roster row would break a live Copilot or Cursor
+  route. Mitigation: the scope boundary above, plus a final `rg` sweep that expects
+  vendor hits to remain.
+- **Under-removal.** A default left on `gpt-5.4-mini` turns into a silent 404 on every
+  warmup or image description. Mitigation: wp3 enumerates each default site explicitly.
+- **Test churn masking a real break.** ~278 test hits are in scope. Mitigation: each
+  test edit is classified as membership (must change), floor (must repoint), or
+  historical (must not change), and the full suite is the closing gate.
+
+## Acceptance
+
+DONE requires: no retired slug in a Codex-login-owned surface, every default on a live
+slug, `bun run typecheck` clean, the focused domain suites green, the full
+`bun run test` green, `bun run structure:check` green, and this unit carrying a closing
+record with quoted evidence.
diff --git a/devlog/_plan/260912_codex_gpt54_retirement/010_catalog_removal.md b/devlog/_plan/260912_codex_gpt54_retirement/010_catalog_removal.md
new file mode 100644
index 0000000000..2e479cadc5
--- /dev/null
+++ b/devlog/_plan/260912_codex_gpt54_retirement/010_catalog_removal.md
@@ -0,0 +1,125 @@
+# wp2 — Remove the retired slugs from the Codex-login native catalog
+
+Membership only. No default moves here; that is wp3.
+
+## MODIFY src/codex/catalog/native-models.ts
+
+`NATIVE_OPENAI_MODELS` line 156. Before:
+
+```ts
+  "gpt-5.5", "gpt-5.4", "gpt-5.4-mini", "gpt-5.3-codex-spark",
+```
+
+After:
+
+```ts
+  "gpt-5.5", "gpt-5.3-codex-spark",
+```
+
+Two comments name the removed slugs as examples and must stop doing so, because after
+this change they would describe a list that no longer holds them:
+
+- line 75, in the `SELF_DESCRIBED_NATIVE_OPENAI_MODELS` doc comment: the sentence "the
+  pin also holds `gpt-5.5`, `gpt-5.4` and `gpt-5.4-mini`" stays true of the snapshot, but
+  the retired slugs are no longer admission candidates at all. Rewrite it around the pins
+  that remain reachable — `gpt-5.5`, `gpt-5.2`, `codex-auto-review` — so the reason the
+  allowlist is explicit rather than structural survives the retirement.
+- line 175, in `NATIVE_MAIN_DRAIN_SENTINEL_MODELS`: drop `gpt-5.4` and
+  `gpt-5.4-mini` from the "would have widened the sentinel to" enumeration, leaving
+  `gpt-5.5` and `gpt-5.3-codex-spark`. The set itself is unchanged — neither slug
+  was ever a member.
+
+## MODIFY src/codex/catalog/metadata.ts
+
+Line 165, `NATIVE_OPENAI_CONTEXT_OVERRIDES`: DELETE
+`"gpt-5.4": { contextWindow: 1_000_000, maxContextWindow: 1_000_000 },`. This was the
+only 1M native; `gpt-5.4-mini` has no entry and took its window from the pin.
+
+Line 123, the operating-cap comment: the sentence "and gpt-5.4 runs 272,000 against
+1,000,000" describes a row that is going away. Rewrite it to cite only the GPT-5.6
+slugs it already discusses.
+
+Line 540, the `upstreamNativeEntryForSlug` allowlist comment: "would also admit
+gpt-5.5/gpt-5.4/gpt-5.4-mini" becomes "would also admit gpt-5.5/gpt-5.2/codex-auto-review".
+The behaviour is unchanged; the example set follows the pins that can still be reached.
+
+## KEEP src/codex/data/upstream-models.json (audit reversal)
+
+The plan originally called for deleting the two pinned objects (`"slug": "gpt-5.4"` at
+line 460, `"slug": "gpt-5.4-mini"` at line 565). The A phase reversed that.
+
+This file is a snapshot of upstream's bundled catalog, and `metadata.ts:580` states the
+contract: "The pinned JSON is left byte-identical to upstream; only the projection fills
+in." The snapshot already carries `gpt-5.2` and `codex-auto-review`, neither of which is
+in `NATIVE_OPENAI_MODELS`, so a pinned row has never been an exposure decision.
+
+Nothing re-exposes a retired slug from the snapshot alone. `PINNED_NATIVE_CAPABILITY_ENTRIES`
+and `UPSTREAM_NATIVE_ENTRIES` are both built by iterating `NATIVE_OPENAI_MODELS`, so once
+the slugs leave that list their pinned rows are never looked up. The one consumer that
+reads raw snapshot rows, `GATED_MODEL_CLIENT_VERSION_FLOOR` in
+`src/codex/model-entitlements.ts:135`, filters on `ACCOUNT_GATED_NATIVE_OPENAI_MODELS`
+(Daybreak only) and never sees them.
+
+Deleting ~205 lines of upstream-owned JSON would change no behaviour while breaking the
+file's fidelity to its source and churning `reserve-catalog-lifecycle.test.ts` and
+`codex-model-entitlements.test.ts`, which read it directly. Membership is the lever.
+
+## MODIFY src/codex/catalog/parsing.ts, src/codex/catalog/effort.ts, src/codex/catalog/sync.ts
+
+Comment-only. Each names `gpt-5.4` or `gpt-5.4-mini` as the illustrative "older native"
+(`parsing.ts:521` preserved-row cap, `effort.ts:62` xhigh clamp, `sync.ts:263` mock
+max/ultra). Replace the examples with `gpt-5.5` / `gpt-5.3-codex-spark`. No predicate
+changes: the clamp keys on "is not a gpt-5.6 native", so a request that still names a
+retired slug is still clamped correctly.
+
+## Tests
+
+Membership assertions that must drop the slugs:
+
+- `tests/codex-integration/codex-catalog.test.ts` — `filterSupportedNativeSlugs`
+  expectation at 6954 and the visibility inputs at 6943-6944; delete the "native gpt-5.4
+  uses its 1M context window override" test at 3459-3466 with the override itself.
+  The "preserved gpt-5.4-mini rows get the openai cap" test at 3640-3678 cannot simply be
+  kept: it feeds a preserved row through `mergeCatalogEntriesForSync`, and after membership
+  removal that row is a droppable unsupported native. Run it first — if it drops, repoint
+  the fixture onto a surviving non-overridden native so the #1430 cap regression keeps its
+  coverage. Line 3686 (`nativeOpenAiContextWindow("gpt-5.4", 272_000)`) names a retired
+  slug in a test about the generic cap, so repoint it too.
+  KEEP 3817 (negative: the slugs must not leak into `UPSTREAM_NATIVE_ENTRIES` — still true
+  and now trivially so), KEEP the Nova1 routed alias fixtures at 1175-1205 and the cursor
+  rows at 4340-4893.
+- `codex-catalog-sync-hardening.test.ts` 118-140, 275-281, 373-376 — repoint the native
+  fixtures onto `gpt-5.5` / `gpt-5.6-luna`; 729-765 likewise.
+- `codex-catalog-golden.test.ts` 41 and the `"gpt-5.4@9"` golden projection at 76.
+- `codex-catalog-model-picker-order.test.ts` 153-167.
+- `codex-catalog-restore.test.ts` — the hide/priority/window fixtures listed in the
+  audit; the 1M expectation at 398 goes with the override.
+- `native-model-toggle.test.ts` 71-72 and 299. KEEP 79 (`cursor/gpt-5.4` proves vendor
+  slugs are ignored by native visibility) and 234-243 (preserved compact-limit map).
+- `model-visibility-management-api.test.ts` 376-436 — a removed slug is no longer a
+  valid native visibility target, so these move to a surviving native.
+- `codex-convergence-account-selectors.test.ts`, `codex-auth-context.test.ts`,
+  `codex-metadata-integrity.test.ts`, `codex-v2-gate.test.ts`, `effort-policy.test.ts`
+  281-315 — these use the slug as a live native request id; repoint to `gpt-5.5`.
+  `effort-policy.test.ts` 435-439 keeps testing the clamp, on a surviving old native.
+- `tests/claude-integration/` — `claude-models-discovery.test.ts` expected roster,
+  `claude-model-info.test.ts` (its "only authoritative 1M native" claim dies with the
+  override), `claude-context-windows.test.ts` 24-29, `claude-inbound.test.ts`.
+- `tests/clients/desktop-3p.test.ts` 215-221 — same 1M native subject.
+
+Do not touch: `tests/usage/**`, `tests/providers/**` vendor suites,
+`tests/fixtures/commandcode-models.json`, `tests/responses/responses-shadow-intercept.test.ts`,
+`tests/routing/subagent-*` (operator rosters and a negative sentinel assertion).
+
+Four more in-scope files the first sweep left unclassified:
+`tests/codex-integration/codex-app-server-processes.test.ts:491-500` KEEP (the
+`codex --config model=...` fixture exercises a command-line detector; any token works),
+`tests/codex-integration/slug-codec.test.ts:106` KEEP (codec round-trip pair, not
+membership), `tests/responses/empty-completion-guard.test.ts:467` KEEP (string formatting),
+`tests/vision/vision-eligibility.test.ts:225` REPOINT to `gpt-5.6-luna` — unlike the
+OpenRouter rows at 22-26 this one is the native eligibility subject and belongs to wp3.
+
+## Proof for this phase
+
+`bun test tests/codex-integration tests/claude-integration tests/clients` green, plus
+`bun run typecheck`.
diff --git a/devlog/_plan/260912_codex_gpt54_retirement/020_defaults_repoint.md b/devlog/_plan/260912_codex_gpt54_retirement/020_defaults_repoint.md
new file mode 100644
index 0000000000..06943334e0
--- /dev/null
+++ b/devlog/_plan/260912_codex_gpt54_retirement/020_defaults_repoint.md
@@ -0,0 +1,112 @@
+# wp3 — Move every opencodex-owned default off the retired slugs
+
+Every lane goes to `gpt-5.6-luna`, including the login provider default (owner
+decision, 2026-09-12). Each site below dispatches a real request today and would 404
+after retirement.
+
+## MODIFY src/oauth/index.ts
+
+Line 331, the `chatgpt` OAuth definition: `defaultModel: "gpt-5.4"` becomes
+`defaultModel: "gpt-5.6-luna"`.
+
+Be accurate about what this constant does, because the first draft of this plan was not:
+`upsertOAuthProvider` returns at `src/oauth/index.ts:1476` for `chatgpt`, so the value is
+never persisted onto a provider row, and `src/cli/models.ts:139`, `src/cli/provider.ts`
+and `src/server/fast-row.ts:133` all read `config.providers[*].defaultModel` rather than
+this constant. It is the ChatGPT login definition's declared default, not a live 404
+dispatch path. It still moves: leaving a retired slug as the login surface's stated
+default is wrong on its own terms, and any future consumer would inherit it.
+
+## MODIFY src/oauth/token-guardian.ts
+
+Line 55, `DEFAULTS.codexWarmupModel`: `"gpt-5.4-mini"` becomes `"gpt-5.6-luna"`.
+Line 87 reads a stored override first, so a user who explicitly set
+`tokenGuardian.codexWarmupModel: "gpt-5.4-mini"` keeps calling the retired model.
+Extend the existing startup migration (below) to rewrite that stored value too.
+
+## MODIFY src/codex/warmup.ts
+
+Line 30: `const DEFAULT_MODEL = "gpt-5.4-mini"` becomes `"gpt-5.6-luna"`.
+Line 31: `FALLBACK_MODELS = ["gpt-5.5", "gpt-5.6-luna"]` becomes `["gpt-5.5"]` — luna
+is now the primary, and the loop already skips a fallback equal to the primary, so
+leaving it would be dead weight that reads as a second chance.
+
+## MODIFY src/vision/plan.ts
+
+Line 14: `const DEFAULT_VISION_MODEL = "gpt-5.4-mini"` becomes `"gpt-5.6-luna"`.
+Lines 71 and 87 consume it and need no edit. This is the one that the startup sidecar
+migration cannot reach: an unset `visionSidecar.model` never equals the old string, so
+today an untouched install still describes images with a retired model.
+
+After this, `src/vision/eligibility.ts:51` and `src/vision/backends.ts:51` — both
+already `gpt-5.6-luna` — agree with the runtime instead of contradicting it.
+
+## MODIFY src/server/management/config-routes.ts
+
+Lines 823-824, the vision effort-table normalization: both `"gpt-5.4-mini"` literals
+become `"gpt-5.6-luna"`. Lines 724 and 963 are already luna and stay.
+
+## MODIFY src/cli/config-command.ts
+
+Line 148: `const model = vision.model || "gpt-5.4-mini"` becomes `"gpt-5.6-luna"`, and
+the line 147 comment that names the old bounded default follows it.
+
+## MODIFY src/server/index.ts
+
+KEEP the sidecar migration block at 686-701 — it is the only thing that rewrites a
+stored `gpt-5.4-mini` for existing users, and its destination is already luna. Two
+changes:
+
+1. Extend it to `config.tokenGuardian?.codexWarmupModel === "gpt-5.4-mini"`, which is
+   currently not migrated and is a live dispatch path.
+2. Correct the comment: it claims "explicit user choices are preserved", but the check
+   is exact equality, so an explicitly chosen `gpt-5.4-mini` is rewritten too. After
+   retirement that is the right behaviour; the comment should say so rather than
+   describe a guarantee the code does not make.
+
+The `SIDECAR_MIGRATION_CUTOFF` date gate stays as-is.
+
+## MODIFY src/types/config.ts, src/types/tools.ts, src/types/request.ts
+
+Doc comments only, but they are the published contract:
+
+- `config.ts:1125` — "Default gpt-5.4-mini" for `codexWarmupModel` becomes luna.
+- `config.ts:604` and `:614` — the shadow-intercept comments claim both slugs are
+  defaults while the code ships luna only. Correct them to state the default is
+  `gpt-5.6-luna` and `gpt-5.4-mini` is an opt-in `sourceModels` value for 0.144.x
+  clients.
+- `tools.ts:16` and `request.ts:103` — the synthetic web_search comments still name a
+  "gpt-5.4-mini sidecar"; `src/web-search/index.ts:23` has been luna for a while.
+
+## KEEP src/lib/shadow-call.ts
+
+`DEFAULT_SHADOW_SOURCE_MODELS` stays `["gpt-5.6-luna"]` and the 0.144.x note stays.
+This list is what the proxy *intercepts*, not what it sends: a 0.144.x client emitting
+`gpt-5.4-mini` helper calls is exactly who benefits from an intercept, and an operator
+can restore the prefix through `sourceModels`. Adding it back to the default would
+change intercept behaviour for every install, which is a separate decision from
+retiring the model.
+
+## Tests
+
+- `tests/codex-integration/warmup.test.ts` 97-141, `codex-warmup.test.ts` 38/55,
+  `token-guardian.test.ts` 253, `codex-quota-auto-refresh-main-admission.test.ts` 290 —
+  the warmup chain becomes `gpt-5.6-luna` then `gpt-5.5`.
+- `tests/vision/**` — `sidecar-abort.test.ts` (21 fixtures), `vision-reasoning-contract.test.ts`
+  (14, retune to luna's ladder), `sidecar-settings-vision-filter.test.ts` 137/189,
+  `sidecar-settings-vision-controls.test.ts` 89, `vision-anthropic.test.ts` 419.
+  KEEP `vision-eligibility.test.ts` 22-26 (OpenRouter `openai/gpt-5.4-mini` metadata).
+- `tests/web-search/web-search.test.ts` — 26 settings fixtures move to luna.
+- `tests/server/server-combo-failover-e2e.test.ts` — 10 live-forward model ids.
+- A new regression for the widened migration: a stored
+  `tokenGuardian.codexWarmupModel: "gpt-5.4-mini"` is rewritten to luna at startup.
+- `tests/vision/vision-eligibility.test.ts:225` — the native eligibility subject moves to
+  luna; 22-26 stay (OpenRouter `openai/gpt-5.4-mini` metadata).
+- KEEP `tests/server/config.test.ts` 98 and `server-startup-reconcile-resilience.test.ts` 57
+  (legacy roster inputs), `tests/server/api-debug.test.ts` (log-parser fixture),
+  `tests/responses/**` (shadow restore hatch), `tests/usage/**` (historical pricing).
+
+## Proof for this phase
+
+`bun test tests/vision tests/web-search tests/server tests/codex-integration` green,
+plus `bun run typecheck`.
diff --git a/devlog/_plan/260912_codex_gpt54_retirement/030_surfaces_and_gate.md b/devlog/_plan/260912_codex_gpt54_retirement/030_surfaces_and_gate.md
new file mode 100644
index 0000000000..e3c6615fb2
--- /dev/null
+++ b/devlog/_plan/260912_codex_gpt54_retirement/030_surfaces_and_gate.md
@@ -0,0 +1,96 @@
+# wp4 — GUI, docs, structure docs, and the closing gate
+
+## MODIFY gui/src
+
+- `gui/src/pages/dashboard-overview-sections.tsx:447` — `sidecar?.vision.model ?? "gpt-5.4-mini"`
+  becomes `?? "gpt-5.6-luna"`, matching the runtime default from wp3. Left alone, the
+  dashboard would display a retired model for an unset vision config.
+- `gui/src/pages/api-keys-panels.tsx:322,330` — the copy-paste curl samples name
+  `gpt-5.4`; move them to `gpt-5.6-luna` so a user pasting the sample gets a live model.
+- KEEP `gui/src/pages/shadow-call-source.ts:5` — 0.144.x history, already luna in code.
+
+## MODIFY gui/tests
+
+Vision floor: `vision-sidecar-dashboard.test.tsx` 39/107/307/311/372/377,
+`vision-reasoning-contract.test.ts` 15/19 → luna.
+Native examples: `api-access-models.test.ts`, `apikeys-actions.test.tsx`,
+`apikeys-model-test-wire.test.tsx`, `apikeys-models-states.test.tsx`,
+`client-config-panel.test.tsx`, `subagents-fallback.test.tsx` → a surviving native.
+KEEP `models-native-group-controls.test.ts` (custom, non-native row id) and
+`shadow-call-source.test.ts` (explicit override rendering).
+
+## MODIFY docs-site (English first, then the seven locales)
+
+Each family below changes in `docs/` and in `fr`, `ja`, `ko`, `ru`, `tr`, `zh-cn`,
+`zh-tw`. The English page is the source; a locale must not disagree with it.
+
+- `guides/codex-app-models.md` — drop `gpt-5.4` and `gpt-5.4-mini` from the native
+  fallback set. zh-tw `guides/sub-agent-surface.md:218` additionally carries an effort
+  row for the retired natives that English does not have; delete that row.
+- `getting-started/quickstart.md` — the advertised five native picker models still end
+  in `gpt-5.4-mini`, while `DEFAULT_SUBAGENT_MODELS` is already Astra/sol/terra/luna/5.5.
+  Make the docs match the shipped default.
+- `guides/codex-integration.md` — the account-verification warmup sentence becomes
+  "defaults to `gpt-5.6-luna`, retries with `gpt-5.5`".
+- `reference/configuration/providers.md` — `codexWarmupModel` default cell → luna.
+- `reference/configuration/server.md` — the vision `model?` default cell → luna. KEEP
+  the "legacy explicit `gpt-5.4-mini` migrates on start" sentence; that is still true.
+- `guides/sidecars.md` — the code fallback → luna; keep the migration sentence.
+- `reference/configuration/agents.md` and `guides/sub-agent-surface.md` — the
+  `subagentModelFallback` examples name a retired model; move to luna.
+- `docs-site/src/components/Landing.astro` 89/320 — the marketing line advertises a
+  "gpt-5.4-mini sidecar" in every translated string; update all of them together.
+- KEEP the Copilot mixed-wire lists in `guides/providers.md` and
+  `reference/configuration/providers.md`; those describe a vendor roster this unit does
+  not touch. KEEP the shadow-intercept restore notes, but fix zh-tw
+  `reference/cli/providers-accounts.md:283`, which states the default is both slugs
+  while English says luna only.
+- `guides/codex-integration.md` explicit-account example `work/gpt-5.4` → `work/gpt-5.5`,
+  so no page advertises a retired slug even as an illustration.
+
+## MODIFY docs/ (maintainer-facing, separate from docs-site)
+
+- `docs/shadow-call-intercept.md:14-17` — says the default source-prefix set is
+  `gpt-5.4-mini` and `gpt-5.6-luna`. `DEFAULT_SHADOW_SOURCE_MODELS` is luna-only, so this
+  page is already wrong today. State luna as the default and `gpt-5.4-mini` as the 0.144.x
+  restore value, matching the correction in `src/types/config.ts` from wp3.
+- `docs/codex-app-model-catalog.md:111` — uses `gpt-5.5`/`gpt-5.4` as the example of
+  snapshot entries that are staler than the installed catalog. Replace the retired half of
+  the example.
+
+## MODIFY structure/
+
+- `structure/ops/service-and-sidecars.md:52` — vision default cell → `gpt-5.6-luna`.
+- `structure/gui-and-management-api.md:129` — the shadow `sourceModels` sentence says
+  the default is `gpt-5.4-mini` + `gpt-5.6-luna`; the code ships luna only. Correct the
+  default and keep mini as the documented restore value.
+
+## MODIFY scripts/release-notes.ts
+
+Line 1137 — `process.env.OPENAI_MODEL ?? "gpt-5.4"` becomes `?? "gpt-5.6-luna"`. The
+tool is maintainer-facing but would fail against a retired model.
+KEEP `scripts/model-metadata.source.json` entirely: 129 hits across vendor snapshots
+plus openai/openai-codex pricing rows, none of which are the Codex-login catalog.
+
+## Closing gate
+
+1. `bun run typecheck`
+2. `bun run test` (full suite, PR-ready gate)
+3. `bun run lint:gui` and the GUI tests
+4. `bun run structure:check`
+5. Final `rg "gpt-5\\.4"` sweep, read against an explicit allowlist rather than an
+   expectation of zero hits. Survivors that are CORRECT and must remain:
+   vendor rosters (`src/providers/registry.ts` Copilot, `src/adapters/cursor/*`,
+   `src/providers/codebuddy-models.ts`, `scripts/model-metadata.source.json`,
+   `tests/providers/**`, `tests/fixtures/commandcode-models.json`, the Copilot/mixed-wire
+   docs pages); historical pricing (`src/usage/expected-prices.ts`, `tests/usage/**`,
+   `docs-site/src/data/frontier-benchmarks.json` benchmark rows);
+   generated metadata (`src/generated/model-metadata.ts`); different slugs
+   (`-nano`, `-pro`, `-high`, `openai/gpt-5.4-mini`, `cursor/gpt-5.4`); the shadow-intercept
+   restore hatch (`src/lib/shadow-call.ts`, `tests/responses/**`, the sourceModels docs);
+   negative and fixture assertions (`tests/routing/subagent-*`, `tests/server/api-debug.test.ts`,
+   `tests/server/config.test.ts`, `server-startup-reconcile-resilience.test.ts`,
+   `codex-app-server-processes.test.ts`, `slug-codec.test.ts`, `empty-completion-guard.test.ts`,
+   `codex-catalog.test.ts:3817`); and this devlog unit. A hit outside that list is a defect.
+
+Receipts go to `.tmp/`, and `040_done.md` records the outcome with quoted evidence.
diff --git a/devlog/_plan/260912_codex_gpt54_retirement/040_done.md b/devlog/_plan/260912_codex_gpt54_retirement/040_done.md
new file mode 100644
index 0000000000..1c2d396f43
--- /dev/null
+++ b/devlog/_plan/260912_codex_gpt54_retirement/040_done.md
@@ -0,0 +1,92 @@
+# Closing record
+
+## Outcome
+
+DONE. `gpt-5.4` and `gpt-5.4-mini` no longer exist on the Codex (ChatGPT OAuth) login
+surface, and every default that used to dispatch one of them now uses `gpt-5.6-luna`.
+Delivered as PR #4327 against `dev`, final head `32bd5417cb`, CI green.
+
+Commits: `a8b26e1342` (this roadmap), `5d664b1a6b` (the retirement),
+`fa1fe32890` (a combo-alias fixture CI caught), `fe01c0f605` (the resurrection guard a
+review caught), `32bd5417cb` (the migration extracted and tested).
+
+## What changed against the plan
+
+Two reversals, both from audit rather than from build convenience.
+
+The pinned rows in `src/codex/data/upstream-models.json` stayed. The plan called for
+deleting them; the A phase found the file is upstream's snapshot by contract
+(`metadata.ts:580`) and already carries rows this runtime does not expose (`gpt-5.2`,
+`codex-auto-review`). Both maps built from it iterate `NATIVE_OPENAI_MODELS`, so the
+rows are unreachable once membership is gone. Deleting ~205 lines would have changed
+no behaviour.
+
+The maintainer-facing `docs/` tree was missing from the original scope entirely. The
+independent reviewer caught it: `docs/shadow-call-intercept.md` still claimed the
+default intercept set was both slugs when the code had been luna-only for a while, and
+`docs/codex-app-model-catalog.md` used `gpt-5.4` as a staleness example.
+
+## What CI caught that reading did not
+
+Two defects survived the audit and the six parallel test workers, and were found only
+by pushing:
+
+1. `tests/codex-integration/codex-catalog.test.ts` had a native-alias combo fixture
+   targeting `codex/gpt-5.4-mini`. Once membership was gone that alias had no native
+   capabilities to inherit. `gpt-5.5` carries an identical pinned shape (272k window,
+   `low..xhigh`, default `medium`, text and image), so every asserted value held after
+   repointing.
+2. `enforce-target` fails on any `gui/` path change without screenshot evidence. There
+   is no visual change here, so it was waived through the repository's documented
+   maintainer-comment mechanism with a note stating exactly what the `gui/src` diff is.
+
+## What the final review caught that CI did not
+
+CI was green and the change was still wrong in one place. An independent reviewer read
+the pushed diff and found that removing the slugs from `NATIVE_OPENAI_MODELS` does not
+keep them out: an account-bound observation deliberately admits any native that is NOT
+in `SUPPORTED_NATIVE_OPENAI_SLUGS`, which is how a genuinely new upstream model reaches
+one entitled account early. A retired slug fails that same test, so a stale
+`selector/gpt-5.4` row persisted in a user's catalog or models cache would have been
+re-observed as an unknown native and synthesized straight back into the picker, one sync
+after the removal took it out.
+
+`RETIRED_NATIVE_OPENAI_MODELS` is the distinction the code was missing: unknown-and-new
+is admitted, known-and-dead is refused. The guard sits in `observedAccountBoundNativeSlug`
+because every observation path funnels through it.
+
+This is the residual wp2 recorded as needing proof rather than assumption, and it is the
+reason that residual was worth writing down: no test covered it, so no test failed.
+
+The same review noted the widened startup migration had no test at all. It is now
+`src/codex/retired-model-migration.ts`, shaped like the existing
+`runClaudeAuthModeMigration`, with tests for the three stored slugs, sibling-key
+survival, idempotence, and leaving any other model alone.
+
+## Verification and its limits
+
+The owner instructed mid-loop that the local suite must not be run on this machine; a
+baseline run confirmed why, reporting ~279 failures unrelated to this change. So
+`bun run typecheck`, `bun run test`, `bun run structure:check` and the dashboard lint
+are **NOT RUN locally**, and the evidence is repository CI against the final head.
+`bun run privacy:scan` and `tests/ci-workflows/repo-hygiene.test.ts` were run before
+that instruction arrived, on the devlog commit, and both passed.
+
+What this does not prove: nothing here exercised a live ChatGPT account. That the
+retired slugs now 404 upstream is the premise of the task, not something this unit
+verified.
+
+## What did not improve, and what would falsify this
+
+The `desktop-3p` 1M-native regression lost its positive control. `gpt-5.4` was the only
+native with a 1M window, so the test that proved a provider cap can take `supports1m`
+away now only proves no native ever gets it. If a 1M native returns, that test should
+regain a positive case rather than stay an absence check.
+
+The account-namespaced question turned out to be the real defect rather than a caveat,
+and it is now fixed and tested. What remains unproven is the disk side: a persisted
+`selector/gpt-5.4` row is no longer re-admitted as evidence, but
+`isUnsupportedOpenAiNativeSlug` still returns false for any slug containing `/`, so the
+stale row itself is not actively deleted from a user's catalog file. It stops being
+regenerated and stops being observed; whether it lingers in a file until the next full
+rewrite was not measured against a real installation.
diff --git a/devlog/_plan/260912_combo_carry/000_plan.md b/devlog/_plan/260912_combo_carry/000_plan.md
new file mode 100644
index 0000000000..80e1cd6d07
--- /dev/null
+++ b/devlog/_plan/260912_combo_carry/000_plan.md
@@ -0,0 +1,15 @@
+# Combo quota carry roadmap
+
+Carry #4090 followed by the editor delta of #4105 so routing uses explicit inference evidence for the current credential and Combo editing only blocks on fresh confirmed exhaustion. Preserve luvs01 contribution and latest omitted-projection correction.
+
+Satisfy-spec HOTL requested by the parent coordinator. Scope: runtime quota publication/cache/selection; management projection; Combo editor; existing regression tests; translated guides and structure owners. No merge, original closure, release, service or config changes. No local suites of any size, build, typecheck or install. Existing GitHub account/tool scope only; no user-set token/time/agent bound. Main owns implementation, read-only agents audit.
+
+Order: roadmap docs-only cycle -> runtime carry -> editor carry -> final cumulative hosted verification. Source commits and executable diffs are in 010 and 020. Current original heads: #4090 c061316722cddf716c830fdc60bd74d237c78af5; #4105 50296f181eb41b582c3f7c04f80335ab7f78bab3. Skip #4105 prerequisite 6292b3c; carry af2ceb8 and 50296f1 above the latest #4090.
+
+Verification: git diff --check (text only), source inspection, existing .github/workflows/ci.yml workflow_dispatch at final tip with full lane if supported. Local product validation NOT RUN by explicit user instruction. Conditional acceptance: pool/OAuth/changed credential/static auth/display-only -> no provider veto; explicit same-credential exhausted inference -> veto; stale/malformed/missing projection -> editor remains enabled; fresh exhausted every target -> Save/Create disabled; expiry/visibility/refresh -> re-evaluate.
+
+DONE means PR chain, final head and hosted run evidence, matching GUI capture and explicit security review are durable in .tmp/combo-handoff/HANDOFF.md. Unresolved external gates are reported with evidence, never weakened into success. Parent owns merge and original disposition. Main reclaims failed audit transport but records the independence gap. Architect-specific role is unavailable in exposed schema; no installation or fabricated role is attempted.
+
+Private review working notes stay in .tmp; public roadmap only cites already-public source changes. SoT: current structure runtime and GUI/management owners replace retired structure/04_transports-and-sidecars.md. Every mapped owner is reviewed for applicability and gets a scoped pointer where necessary.
+
+Roadmap audit: independent inherited-model reviewer Linnaeus returned VERDICT: PASS, zero blockers. Carry boundaries verified; use genuinely bound evidence for changed-key regression because test-only seeding bypasses binding comparison. Dispatch runner labels must be recorded truthfully. Supported independent design consultation is in flight under the user's clarified instruction; native architect role is not claimed.
diff --git a/devlog/_plan/260912_combo_carry/010_runtime.md b/devlog/_plan/260912_combo_carry/010_runtime.md
new file mode 100644
index 0000000000..c8778af957
--- /dev/null
+++ b/devlog/_plan/260912_combo_carry/010_runtime.md
@@ -0,0 +1,884 @@
+# runtime carry
+
+MODIFY exactly the paths in this public source diff. Apply each original commit in order with attribution. Resolve retired structure document into current runtime.md and gui-and-management-api.md; never restore the retired file. Earlier phase dependency: roadmap.
+
+Before/after source contract (review against current dev at P; source diff is the executable carry input):
+
+```diff
+diff --git a/docs-site/src/content/docs/fr/guides/combos.md b/docs-site/src/content/docs/fr/guides/combos.md
+index 9785135d53..9434a1e98a 100644
+--- a/docs-site/src/content/docs/fr/guides/combos.md
++++ b/docs-site/src/content/docs/fr/guides/combos.md
+@@ -190,6 +190,8 @@ indique la réinitialisation de fenêtre à venir la plus proche (cinq heures, h
+ Le fournisseur dont le quota se renouvelle en premier est ainsi sollicité. Les cibles dépourvues de données de quota
+ récentes et les égalités conservent l’ordre de configuration. `weight` et `stickyLimit` n’affectent pas cette stratégie.
+
++Ce classement et l’exclusion des fournisseurs avant l’envoi exigent des limites récentes d’inférence de modèles applicables dans leur ensemble à l’unique clé API actuelle. Les résumés OAuth ou du compte courant, les routes transmettant les identifiants de l’appelant, les configurations à plusieurs clés et les instantanés dont les identifiants ou la destination ont changé servent uniquement à l’affichage pour cette décision préalable. Il en va de même lorsque les en-têtes `Authorization`, `x-api-key` ou `x-goog-api-key` remplacent les identifiants ; les fenêtres réservées à la recherche ou à MCP sont exclues. Si aucune cible admissible n’a de réinitialisation applicable, l’ordre de configuration prévaut. La sélection des comptes et les nouvelles tentatives appliquent toujours leurs limites habituelles.
++
+ ## Que se passe-t-il lorsqu'une cible échoue
+
+ Les échecs d’un combo se répartissent entre ceux qui entraînent un **basculement** et les échecs **terminaux**.
+diff --git a/docs-site/src/content/docs/guides/combos.md b/docs-site/src/content/docs/guides/combos.md
+index db94da045f..c7d076d9b7 100644
+--- a/docs-site/src/content/docs/guides/combos.md
++++ b/docs-site/src/content/docs/guides/combos.md
+@@ -202,6 +202,8 @@ shows the soonest upcoming window reset (five-hour, weekly, monthly, or custom).
+ provider that refreshes first. Targets without fresh quota data, and ties, keep configuration
+ order. Weights and `stickyLimit` do not affect this strategy.
+
++This ranking and provider exclusion before dispatch require fresh model-inference limits that apply to the current single API key as a whole. OAuth/current-account summaries, caller-forward routes, multiple keys, and snapshots with changed credentials or destinations are display-only for this early decision. The same applies when `Authorization`, `x-api-key`, or `x-goog-api-key` headers override credentials; search-only and MCP-only windows are excluded. If no eligible target has an applicable reset, configuration order wins. Account selection and retries still enforce their normal limits.
++
+ ## What happens when a target fails
+
+ Combo failures are divided into **hop** failures and **terminal** failures.
+diff --git a/docs-site/src/content/docs/ja/guides/combos.md b/docs-site/src/content/docs/ja/guides/combos.md
+index 655dae2232..f6eca53214 100644
+--- a/docs-site/src/content/docs/ja/guides/combos.md
++++ b/docs-site/src/content/docs/ja/guides/combos.md
+@@ -113,6 +113,8 @@ ocx combo set balanced \
+
+ `reset-window` は、キャッシュされたプロバイダーのクォータスナップショットで、次回のウィンドウリセット（5 時間、週次、月次、またはカスタム）が最も早い適格なターゲットへ、各リクエストをルーティングします。これにより、最初にクォータが補充されるプロバイダーを先に使用します。新しいクォータデータがないターゲットと、リセット時刻が同じターゲットでは、構成順序が維持されます。`weight` と `stickyLimit` はこの戦略に影響しません。
+
++この順位付けと送信前のプロバイダー除外には、現在の単一 API キー全体に適用される最新のモデル推論制限が必要です。OAuth／現在のアカウントの概要、呼び出し元の認証情報を転送するルート、複数キー、認証情報や送信先が変わったスナップショットは、この事前判断では表示専用です。`Authorization`、`x-api-key`、`x-goog-api-key` ヘッダーで認証情報を上書きする場合も同様で、検索専用および MCP 専用ウィンドウは対象外です。適用可能なリセット情報を持つ適格な対象がなければ、設定順序を使用します。アカウント選択と再試行には引き続き通常の制限が適用されます。
++
+ ## ターゲットが失敗すると何が起こるか
+
+ コンボ障害は、**ホップ** 障害と **ターミナル** 障害に分類されます。
+diff --git a/docs-site/src/content/docs/ko/guides/combos.md b/docs-site/src/content/docs/ko/guides/combos.md
+index 633feb838b..71e557f25c 100644
+--- a/docs-site/src/content/docs/ko/guides/combos.md
++++ b/docs-site/src/content/docs/ko/guides/combos.md
+@@ -119,6 +119,8 @@ ocx combo set balanced \
+
+ `reset-window`는 캐시된 공급자 할당량 스냅샷에서 가장 가까운 다음 기간 재설정(5시간, 주간, 월간 또는 사용자 지정)이 표시되는 적합한 대상으로 각 요청을 라우팅합니다. 이렇게 하면 가장 먼저 새로 충전되는 공급자를 사용합니다. 최신 할당량 데이터가 없는 대상과 동률인 대상은 설정 순서를 유지합니다. `weight`와 `stickyLimit`은 이 전략에 영향을 주지 않습니다.
+
++이 순위 결정과 전송 전 공급자 제외에는 현재 단일 API 키의 전체 모델 추론에 적용되는 최신 한도 정보가 필요합니다. OAuth·현재 계정 요약, 호출자 인증을 전달하는 경로, 여러 키, 인증 정보나 목적지가 달라진 스냅샷은 이 사전 판단에서 표시 용도로만 사용합니다. `Authorization`, `x-api-key`, `x-goog-api-key` 헤더로 인증을 덮어쓰는 경우도 같으며, 검색 전용·MCP 전용 기간은 제외합니다. 적격 대상 중 적용 가능한 초기화 정보가 없으면 설정 순서를 따릅니다. 실제 계정 선택과 재시도에는 기존 제한이 계속 적용됩니다.
++
+ ## 대상 실패 시 동작
+
+ 콤보 실패는 **홉** 실패와 **종결** 실패로 나뉩니다.
+diff --git a/docs-site/src/content/docs/ru/guides/combos.md b/docs-site/src/content/docs/ru/guides/combos.md
+index 3d4820e521..868416ae5b 100644
+--- a/docs-site/src/content/docs/ru/guides/combos.md
++++ b/docs-site/src/content/docs/ru/guides/combos.md
+@@ -150,6 +150,8 @@ ocx combo set balanced \
+ данных о квоте, а также цели с одинаковым временем сброса сохраняют порядок конфигурации. Значения
+ `weight` и `stickyLimit` не влияют на эту стратегию.
+
++Для этого ранжирования и исключения провайдеров до отправки нужны свежие лимиты инференса моделей, применимые к единственному текущему API-ключу в целом. Сводки OAuth и текущего аккаунта, маршруты с передачей учётных данных вызывающей стороны, несколько ключей и снимки с изменившимися учётными данными или адресом назначения служат только для отображения при этом предварительном решении. То же относится к переопределению учётных данных заголовками `Authorization`, `x-api-key` или `x-goog-api-key`; окна только для поиска или MCP исключаются. Если ни у одной допустимой цели нет подходящего времени сброса, используется порядок конфигурации. При выборе аккаунта и повторных попытках по-прежнему действуют обычные ограничения.
++
+ ## Что происходит, когда цель сбоит
+
+ Сбои в combo делятся на **hop**-сбои и **terminal**-сбои.
+diff --git a/docs-site/src/content/docs/tr/guides/combos.md b/docs-site/src/content/docs/tr/guides/combos.md
+index 8b67170068..520c157e83 100644
+--- a/docs-site/src/content/docs/tr/guides/combos.md
++++ b/docs-site/src/content/docs/tr/guides/combos.md
+@@ -218,6 +218,8 @@ kullanılır. Güncel kota verisi bulunmayan hedeflerde ve eşitliklerde
+ yapılandırma sırası korunur. `weight` değerleri ve `stickyLimit` bu stratejiyi
+ etkilemez.
+
++Bu sıralama ve gönderim öncesi sağlayıcı elemesi, mevcut tek API anahtarının model çıkarımı kullanımının tamamına uygulanan güncel sınırlara dayanır. OAuth veya geçerli hesap özetleri, çağıranın kimlik bilgilerini ileten rotalar, birden fazla anahtar ve kimlik bilgileri ya da hedefi değişmiş anlık görüntüler, bu ön kararda yalnızca görüntüleme amaçlıdır. `Authorization`, `x-api-key` veya `x-goog-api-key` başlıkları kimlik bilgilerini geçersiz kıldığında da aynı kural uygulanır; yalnızca arama veya MCP için olan pencereler hariç tutulur. Uygun hedeflerin hiçbirinde geçerli sıfırlama bilgisi yoksa yapılandırma sırası kullanılır. Hesap seçimi ve yeniden denemelerde normal sınırlar uygulanmaya devam eder.
++
+ ## Bir hedef başarısız olduğunda ne olur?
+
+ Kombo hataları **atlama (hop)** hataları ve **uç (terminal)** hatalar olarak
+diff --git a/docs-site/src/content/docs/zh-cn/guides/combos.md b/docs-site/src/content/docs/zh-cn/guides/combos.md
+index fea189deb3..d84efca472 100644
+--- a/docs-site/src/content/docs/zh-cn/guides/combos.md
++++ b/docs-site/src/content/docs/zh-cn/guides/combos.md
+@@ -139,6 +139,8 @@ ocx combo set balanced \
+
+ `reset-window` 会将每个请求路由到合格目标中，其缓存的提供商额度快照显示下一个窗口最早重置者（五小时、每周、每月或自定义窗口）。这样会优先消耗最先刷新额度的提供商。没有最新额度数据的目标以及并列目标会保持配置顺序。`weight` 和 `stickyLimit` 不影响此策略。
+
++此排序和发送前的提供商排除，需要适用于当前单个 API 密钥全部模型推理的最新限额信息。OAuth／当前账户摘要、转发调用方凭据的路由、多密钥以及凭据或目标地址已改变的快照，在这项提前判断中仅供显示。通过 `Authorization`、`x-api-key` 或 `x-goog-api-key` 请求头覆盖凭据时也适用相同规则；仅用于搜索或 MCP 的窗口不参与判断。如果所有符合条件的目标都没有适用的重置时间，则按配置顺序选择。实际账户选择和重试仍执行正常限制。
++
+ ## 目标失败时会发生什么
+
+ combo 失败分为 **跳转** 失败和 **终止** 失败。
+diff --git a/docs-site/src/content/docs/zh-tw/guides/combos.md b/docs-site/src/content/docs/zh-tw/guides/combos.md
+index bb8ef901f9..d82b399e6f 100644
+--- a/docs-site/src/content/docs/zh-tw/guides/combos.md
++++ b/docs-site/src/content/docs/zh-tw/guides/combos.md
+@@ -154,6 +154,8 @@ ocx combo set balanced \
+
+ `reset-window` 將每個請求路由至快取供應商配額快照顯示下一個時段最早重設的合格目標（五小時、每週、每月或自訂）。這會優先使用最早重新取得額度的供應商。沒有最新配額資料的目標，以及發生平手時，皆維持設定順序。`weight` 與 `stickyLimit` 不影響此策略。
+
++此排序與傳送前的供應商排除，需要適用於目前單一 API 金鑰全部模型推論的最新限額資訊。OAuth／目前帳戶摘要、轉送呼叫者憑證的路由、多金鑰，以及憑證或目的地位址已變更的快照，在這項預先判斷中僅供顯示。透過 `Authorization`、`x-api-key` 或 `x-goog-api-key` 標頭覆寫憑證時也適用相同規則；僅供搜尋或 MCP 使用的時段不參與判斷。若所有符合條件的目標都沒有適用的重設時間，則依設定順序選擇。實際帳戶選擇與重試仍套用一般限制。
++
+ ## 目標失敗時會發生什麼
+
+ Combo 失敗分為**跳轉**失敗與**終端**失敗。
+diff --git a/src/combos/resolve.ts b/src/combos/resolve.ts
+index 71ea750b6e..9627bf396d 100644
+--- a/src/combos/resolve.ts
++++ b/src/combos/resolve.ts
+@@ -1,7 +1,6 @@
+ import type { OcxComboTarget, OcxConfig } from "../types";
+-import { getCachedProviderQuota } from "../providers/quota-routing-cache";
++import { getCachedProviderRoutingQuota } from "../providers/quota-routing-cache";
+ import type { ProviderQuota } from "../providers/quota-types";
+-import { isCanonicalOpenAiForwardProvider } from "../providers/openai-tiers";
+ import { sleepWithAbort } from "../lib/upstream-retry";
+ import {
+   coolComboTarget,
+@@ -65,9 +64,7 @@ function targetProviderIsUsable(config: OcxConfig, target: OcxComboTarget, now:
+   if (!Object.hasOwn(config.providers, target.provider)) return false;
+   const provider = config.providers[target.provider];
+   if (!provider || provider.disabled === true) return false;
+-  // Native account selection owns model-scoped quota; a provider summary cannot veto it.
+-  return isCanonicalOpenAiForwardProvider(provider)
+-    || !cachedProviderQuotaIsExhausted(getCachedProviderQuota(target.provider, now), now);
++  return !cachedProviderQuotaIsExhausted(getCachedProviderRoutingQuota(target.provider, provider, now), now);
+ }
+
+ function quotaWindowExhausted(percent: number | undefined, resetAt: number | undefined, now: number): boolean {
+@@ -181,6 +178,7 @@ function smoothWeightedIndex(
+  * unknown (Infinity).
+  */
+ function resetWindowIndex(
++  config: OcxConfig,
+   targets: Required<OcxComboTarget>[],
+   eligible: (target: Required<OcxComboTarget>) => boolean,
+   now = Date.now(),
+@@ -190,7 +188,9 @@ function resetWindowIndex(
+   for (let index = 0; index < targets.length; index++) {
+     const target = targets[index]!;
+     if (!eligible(target)) continue;
+-    const remaining = quotaResetRemainingMs(getCachedProviderQuota(target.provider, now), now);
++    const remaining = quotaResetRemainingMs(
++      getCachedProviderRoutingQuota(target.provider, config.providers[target.provider], now), now,
++    );
+     // Strict comparison deliberately retains configured order for ties,
+     // including the no-snapshot fallback where every value is Infinity.
+     if (selected < 0 || remaining < smallestRemaining) {
+@@ -276,7 +276,7 @@ export function pickComboTarget(
+       }
+     }
+   } else if (combo.strategy === "reset-window") {
+-    targetIndex = resetWindowIndex(combo.targets, eligible, now);
++    targetIndex = resetWindowIndex(config, combo.targets, eligible, now);
+   } else {
+     targetIndex = combo.targets.findIndex(eligible);
+   }
+diff --git a/src/providers/quota-routing-cache.ts b/src/providers/quota-routing-cache.ts
+index 065d7338ca..1e45d60065 100644
+--- a/src/providers/quota-routing-cache.ts
++++ b/src/providers/quota-routing-cache.ts
+@@ -1,15 +1,53 @@
++import { createHash } from "node:crypto";
++import type { OcxProviderConfig } from "../types";
+ import type { ProviderQuota, ProviderQuotaReport } from "./quota";
++import { providerUsesKeyAuthOverride, resolveProviderApiKey } from "./key-store";
++import { getProviderRegistryEntry } from "./registry";
+
+-const quotaCache = new Map<string, ProviderQuota>();
++export interface ProviderQuotaRoutingEvidence {
++  quota: ProviderQuota;
++  binding: string;
++}
++
++type CachedQuota = {
++  quota: ProviderQuota;
++  routing?: ProviderQuotaRoutingEvidence | { quota: ProviderQuota; testOnly: true };
++};
++
++const quotaCache = new Map<string, CachedQuota>();
++
++/** Private cache identity; neither key material nor this digest enters management reports. */
++export function providerQuotaRoutingBinding(
++  name: string,
++  provider: OcxProviderConfig,
++  credential = resolveProviderApiKey(provider.apiKey)?.trim(),
++): string | null {
++  if ((provider.authMode ?? "key") !== "key" || !credential) return null;
++  // Registry-owned OAuth/forward rows normalize saved authMode before dispatch.
++  // A key probe must not constrain that later account selection.
++  const entry = getProviderRegistryEntry(name);
++  if (entry && (entry.authKind === "oauth" || entry.authKind === "forward")
++    && !providerUsesKeyAuthOverride(entry, provider, credential)) return null;
++  // Static auth headers can replace or combine with the probed API-key header.
++  // Its semantics belong to the adapter, so it is not provider-wide quota evidence.
++  if (Object.keys(provider.headers ?? {}).some(header =>
++    ["authorization", "x-api-key", "x-goog-api-key"].includes(header.toLowerCase()))) return null;
++  return createHash("sha256").update(JSON.stringify([
++    name, provider.adapter, provider.baseUrl, credential,
++  ])).digest("hex");
++}
+
+ export function clearCachedProviderQuotas(): void {
+   quotaCache.clear();
+ }
+
+-export function replaceCachedProviderQuotas(reports: ProviderQuotaReport[]): void {
++export function replaceCachedProviderQuotas(
++  reports: ProviderQuotaReport[],
++  routingEvidence?: WeakMap<ProviderQuotaReport, ProviderQuotaRoutingEvidence>,
++): void {
+   quotaCache.clear();
+   for (const report of reports) {
+-    quotaCache.set(report.provider, report.quota);
++    quotaCache.set(report.provider, { quota: report.quota, routing: routingEvidence?.get(report) });
+   }
+ }
+
+@@ -18,15 +56,34 @@ export function getCachedProviderQuota(
+   now: number,
+   maxAgeMs = 30 * 60_000,
+ ): ProviderQuota | null {
+-  const quota = quotaCache.get(provider);
++  const quota = quotaCache.get(provider)?.quota;
+   if (!quota) return null;
+   if (now - quota.updatedAt > maxAgeMs) return null;
+   return quota;
+ }
+
++/** Only inference-wide evidence for this sole credential may rank or veto a whole provider. */
++export function getCachedProviderRoutingQuota(
++  name: string,
++  provider: OcxProviderConfig | undefined,
++  now: number,
++  maxAgeMs = 30 * 60_000,
++): ProviderQuota | null {
++  if (!provider || provider.disabled === true || (provider.authMode ?? "key") !== "key") return null;
++  // An active-key report cannot speak for the other keys the dispatcher may select.
++  if ((provider.apiKeyPool?.length ?? 0) > 1) return null;
++  const routing = quotaCache.get(name)?.routing;
++  if (!routing || now - routing.quota.updatedAt > maxAgeMs) return null;
++  const binding = providerQuotaRoutingBinding(name, provider);
++  if (!binding || (!("testOnly" in routing) && routing.binding !== binding)) return null;
++  return routing.quota;
++}
++
+ export function setCachedProviderQuotaForTests(
+   provider: string,
+   quota: ProviderQuota,
+ ): void {
+-  quotaCache.set(provider, quota);
++  // Unit tests deliberately assert the supplied quota's scope. Production publication
++  // requires the producer's private, credential-bound evidence map above.
++  quotaCache.set(provider, { quota, routing: { quota, testOnly: true } });
+ }
+diff --git a/src/providers/quota.ts b/src/providers/quota.ts
+index 69ee60626c..6909e46131 100644
+--- a/src/providers/quota.ts
++++ b/src/providers/quota.ts
+@@ -39,7 +39,9 @@ import {
+ } from "./quota-wire";
+ import {
+   clearCachedProviderQuotas,
++  providerQuotaRoutingBinding,
+   replaceCachedProviderQuotas,
++  type ProviderQuotaRoutingEvidence,
+ } from "./quota-routing-cache";
+ import {
+   aggregateCodexPoolCapacity,
+@@ -103,6 +105,7 @@ const XAI_CREDITS_URL = `${XAI_BILLING_URL}?format=credits`;
+ const LAST_GOOD_MAX_AGE_MS = CODEX_CAPACITY_MAX_QUOTA_AGE_MS;
+ const nativeMainReportGenerations = new WeakMap<ProviderQuotaReport, number>();
+ const accountReportCurrent = new WeakMap<ProviderQuotaReport, () => boolean>();
++const routingEvidence = new WeakMap<ProviderQuotaReport, ProviderQuotaRoutingEvidence>();
+ let providerQuotaBeforePublishForTests: (() => void | Promise<void>) | null = null;
+
+ /** Test-only seam for identity/config invalidation after probes but before publication. */
+@@ -447,7 +450,9 @@ async function fetchA6apiQuota(provider: string, config: OcxProviderConfig): Pro
+     ? { expiresAt: normalizedExpiry }
+     : {};
+   if (unlimited) {
+-    return report(provider, "a6api:billing", {
++    // Every row is an API-credit constraint on inference, so the display quota is also
++    // the routing projection. Passing it explicitly is the opt-in.
++    const quota: ProviderQuota = {
+       creditsUsd: {
+         used: 0,
+         limit: 0,
+@@ -458,7 +463,8 @@ async function fetchA6apiQuota(provider: string, config: OcxProviderConfig): Pro
+       },
+       customWindows: [{ label: "Unlimited API credits", percent: 0 }],
+       updatedAt: Date.now(),
+-    });
++    };
++    return keyReport(provider, "a6api:billing", quota, config, apiKey, quota);
+   }
+   const limitUsd = firstFinite(subscription, ["hard_limit_usd"]);
+   const grantedUnits = firstFinite(token, ["total_granted"]);
+@@ -481,7 +487,7 @@ async function fetchA6apiQuota(provider: string, config: OcxProviderConfig): Pro
+   const percent = normalizePercent((usedUsd / limitUsd) * 100);
+   if (percent === undefined) return TERMINAL_QUOTA_FAILURE;
+   const label = `API credits ($${remainingUsd.toFixed(2)} of $${limitUsd.toFixed(2)} remaining)`;
+-  return report(provider, "a6api:billing", {
++  const quota: ProviderQuota = {
+     creditsUsd: {
+       used: usedUsd,
+       limit: limitUsd,
+@@ -491,7 +497,9 @@ async function fetchA6apiQuota(provider: string, config: OcxProviderConfig): Pro
+     },
+     customWindows: [{ label, percent }],
+     updatedAt: Date.now(),
+-  });
++  };
++  // The credit balance funds inference itself, so display and routing scope agree.
++  return keyReport(provider, "a6api:billing", quota, config, apiKey, quota);
+ }
+
+ function parseOpenCodeGoUsageWindow(value: unknown): { percent: number; resetAt?: number } | null {
+@@ -539,7 +547,7 @@ async function fetchOpenCodeGoQuota(provider: string, config: OcxProviderConfig)
+     } : {}),
+     updatedAt: Date.now(),
+   };
+-  return report(provider, "opencode-go:usage", quota);
++  return keyReport(provider, "opencode-go:usage", quota, config, apiKey, quota);
+ }
+
+ /**
+@@ -583,10 +591,13 @@ async function fetchOpenRouterQuota(provider: string, config: OcxProviderConfig)
+   if (percent === undefined) return null;
+   const remaining = Math.max(0, limit - used);
+   const label = `API credits ($${remaining.toFixed(2)} of $${limit.toFixed(2)} remaining)`;
+-  return report(provider, "openrouter:key-info", {
++  // The per-key spending cap stops every request this credential can make, so the
++  // whole report is inference-wide routing evidence.
++  const quota: ProviderQuota = {
+     customWindows: [{ label, percent }],
+     updatedAt: Date.now(),
+-  });
++  };
++  return keyReport(provider, "openrouter:key-info", quota, config, apiKey, quota);
+ }
+
+ /**
+@@ -685,7 +696,7 @@ async function fetchClineQuota(provider: string, config: OcxProviderConfig): Pro
+       windows += 1;
+     }
+   }
+-  return windows > 0 ? report(provider, "cline:plan-usage-limits", quota) : null;
++  return windows > 0 ? keyReport(provider, "cline:plan-usage-limits", quota, config, apiKey, quota) : null;
+ }
+
+ /**
+@@ -757,7 +768,7 @@ async function fetchOllamaCloudQuota(provider: string, config: OcxProviderConfig
+   }
+   const body = asRecord(await readQuotaJson(response));
+   const quota = parseOllamaCloudQuota(body);
+-  return quota ? report(provider, "ollama-cloud:usage", quota) : null;
++  return quota ? keyReport(provider, "ollama-cloud:usage", quota, config, apiKey, quota) : null;
+ }
+
+ /**
+@@ -887,10 +898,18 @@ async function fetchZaiQuota(provider: string, config: OcxProviderConfig): Promi
+     // model window — for example a plan reporting only the monthly MCP `TIME_LIMIT` row.
+     // Returning `null` here would preserve the previous token windows for up to 30 minutes
+     // and keep quota-aware routing acting on a report the provider has already superseded.
+-    return quota ? report(provider, "zai:quota-limit", quota) : AUTHORITATIVE_EMPTY_QUOTA;
++    return quota
++      ? keyReport(provider, "zai:quota-limit", quota, config, apiKey, quota)
++      : AUTHORITATIVE_EMPTY_QUOTA;
+   }
+   const legacy = parseZaiQuotaLegacyFields(data);
+-  return legacy ? report(provider, "zai:quota-limit", legacy) : null;
++  if (!legacy) return null;
++  // The legacy monthly figure also carries MCP usage; it is display evidence, not
++  // proof that model inference is unavailable. Modern TOKEN_LIMIT rows above are scoped.
++  const inferenceQuota = { ...legacy };
++  delete inferenceQuota.monthlyPercent;
++  delete inferenceQuota.monthlyResetAt;
++  return keyReport(provider, "zai:quota-limit", legacy, config, apiKey, inferenceQuota);
+ }
+
+ /**
+@@ -1073,7 +1092,9 @@ async function fetchSyntheticQuota(provider: string, config: OcxProviderConfig):
+     quota.customWindows = [...(quota.customWindows ?? []), { label: "Search hourly", percent: searchHourly }];
+     windows += 1;
+   }
+-  return windows > 0 ? report(provider, "synthetic:quotas", quota) : null;
++  const inferenceQuota = { ...quota };
++  delete inferenceQuota.customWindows; // search.hourly does not constrain model inference.
++  return windows > 0 ? keyReport(provider, "synthetic:quotas", quota, config, apiKey, inferenceQuota) : null;
+ }
+
+ /**
+@@ -1185,6 +1206,31 @@ function report(
+   };
+ }
+
++/**
++ * Publish a credential-bound report, and routing evidence only when the producer
++ * hands over its inference-only projection.
++ *
++ * The projection is deliberately not defaulted to the display quota. A producer must
++ * decide that its rows really do constrain inference on the probed credential; omitting
++ * the argument leaves the report display-only, so a new producer cannot inherit
++ * provider-veto authority merely by calling this helper. Ownership alone is not the
++ * scope decision: providerQuotaRoutingBinding resolving is necessary, never sufficient.
++ */
++function keyReport(
++  provider: string,
++  source: string,
++  quota: ProviderQuota,
++  config: OcxProviderConfig,
++  probedCredential: string,
++  inferenceQuota?: ProviderQuota,
++): ProviderQuotaReport | null {
++  const result = report(provider, source, quota);
++  if (!result || !inferenceQuota) return result;
++  const binding = providerQuotaRoutingBinding(provider, config, probedCredential);
++  if (binding) routingEvidence.set(result, { quota: inferenceQuota, binding });
++  return result;
++}
++
+ function tagNativeMainReport(
+   value: ProviderQuotaReport | null,
+   generation: number,
+@@ -1193,6 +1239,27 @@ function tagNativeMainReport(
+   return value;
+ }
+
++/**
++ * Test-only seam: publish exactly as a credential-bound producer does, and hand back the
++ * routing evidence the publication actually attached.
++ *
++ * Live producers all pass a projection today, so no probe fixture can prove the OTHER half
++ * of the contract: that omitting it stays display-only. Routing an omitted argument through
++ * the real helper keeps that provable, and a re-introduced `= quota` default would be
++ * observed here (a defaulted parameter also fires for an explicitly undefined argument).
++ */
++export function publishKeyReportForTests(
++  provider: string,
++  source: string,
++  quota: ProviderQuota,
++  config: OcxProviderConfig,
++  probedCredential: string,
++  inferenceQuota?: ProviderQuota,
++): { report: ProviderQuotaReport | null; routing: ProviderQuotaRoutingEvidence | undefined } {
++  const result = keyReport(provider, source, quota, config, probedCredential, inferenceQuota);
++  return { report: result, routing: result ? routingEvidence.get(result) : undefined };
++}
++
+ function isProviderQuotaReportCurrent(value: ProviderQuotaReport): boolean {
+   const generation = nativeMainReportGenerations.get(value);
+   return (generation === undefined || isMainAccountIdentityGenerationLive(generation))
+@@ -1888,7 +1955,7 @@ export function reconcileProviderAccountQuotaRows(context: GenerationContext): n
+     const reports = cache.response.reports.filter(report => context.providerNames.has(report.provider));
+     removed += cache.response.reports.length - reports.length;
+     cache = { ...cache, response: { ...cache.response, reports } };
+-    replaceCachedProviderQuotas(reports);
++    replaceCachedProviderQuotas(reports, routingEvidence);
+   }
+   liveAccountQuotaKeys = new Set(context.oauthAccountKeys);
+   liveProviderQuotaKeys = new Set(context.providerNames);
+@@ -2317,7 +2384,7 @@ async function fetchKimiQuota(provider: string, config: OcxProviderConfig, acces
+   });
+   if (!response.ok) return null;
+   const quota = parseKimiQuotaPayload(await readQuotaJson(response));
+-  return quota ? report(provider, "kimi:usages", quota) : null;
++  return quota ? keyReport(provider, "kimi:usages", quota, config, accessToken, quota) : null;
+ }
+
+ /**
+@@ -2444,7 +2511,7 @@ async function fetchCommandCodeQuota(provider: string, config: OcxProviderConfig
+   const fiveHour = parseCommandCodeWindow(limits?.fiveHour);
+   const weekly = parseCommandCodeWindow(limits?.weekly);
+   const creditsUsd = await fetchCommandCodeSpend(bearer, credits, orgQuery);
+-  return report(provider, "command-code:credits", {
++  const quota: ProviderQuota = {
+     ...(fiveHour ? {
+       fiveHourPercent: fiveHour.percent,
+       ...(fiveHour.resetAt !== undefined ? { fiveHourResetAt: fiveHour.resetAt } : {}),
+@@ -2455,7 +2522,9 @@ async function fetchCommandCodeQuota(provider: string, config: OcxProviderConfig
+     } : {}),
+     ...(creditsUsd ? { creditsUsd } : {}),
+     updatedAt: Date.now(),
+-  });
++  };
++  // Rolling windows and the credit balance both gate inference on this bearer.
++  return keyReport(provider, "command-code:credits", quota, config, bearer, quota);
+ }
+
+ /** Cursor included usage via api2.cursor.sh (Bearer from OAuth) — unofficial, may change. */
+@@ -2964,7 +3033,9 @@ async function maybeFetchProviderQuota(
+     // probe to run — the row is the active account's last in-band observation.
+     if (provider.authMode === "oauth" && hasPassiveAccountQuota(name)) return fetchPassiveProviderQuota(name);
+     const reader = keyQuotaReaderForProvider(name, provider);
+-    return reader ? reader(name, provider) : null;
++    // Keep destination/auth fields bound to the same request as the reader's captured
++    // bearer, even if the live provider object changes while the quota probe awaits.
++    return reader ? reader(name, { ...provider }) : null;
+   } catch {
+     return null;
+   }
+@@ -3151,7 +3222,7 @@ export async function fetchProviderQuotaReports(config: OcxConfig, forceRefresh
+     ) {
+       const reports = response.reports.filter(item => mayCommitProviderQuotaKey(item.provider, writerGeneration));
+       cache = { key, ts: Date.now(), response: { ...response, reports } };
+-      replaceCachedProviderQuotas(reports);
++      replaceCachedProviderQuotas(reports, routingEvidence);
+       notifyProviderQuotaSnapshot(reports, config);
+     }
+     return response;
+diff --git a/structure/04_transports-and-sidecars.md b/structure/04_transports-and-sidecars.md
+index 3aac18b6ef..23ab3bb17e 100644
+--- a/structure/04_transports-and-sidecars.md
++++ b/structure/04_transports-and-sidecars.md
+@@ -1638,6 +1638,40 @@ retried. Guarded paths: the ChatGPT passthrough and generic adapter fetch in
+ fallback. Adapters with their own `fetchResponse` (kiro, cursor, google) keep their own retry
+ policies; kiro imports the shared abort/sleep helpers from this module.
+
++## Cached quota used by Combo selection
++
++Provider quota reports describe the observed account, model group, or service window; they are
++not automatically proof that every request through the provider is unavailable. Before account
++selection, Combo exclusion and `reset-window` ranking consume only the producer's inference-wide
++subset for the current single API key. Synthetic search windows and legacy ZAI MCP monthly data
++remain display rows, while credential-wide key limits such as the OpenRouter spending cap remain
++eligible for early exclusion.
++
++Routing evidence is published only when a producer hands the reporting helper its inference-only
++projection. Omitting that argument leaves the report display-only, so a new quota producer cannot
++inherit provider-veto authority merely by reporting through the credential-bound helper, and
++ownership by itself is never the scope decision. The producer records the subset it opts into in
++a private WeakMap bound to the provider name, adapter, destination and captured probe credential.
++Publication retains that evidence without adding it to report JSON.
++
++The cache getter rechecks the live key, effective registry authentication, static
++credential headers, key-pool size and freshness. OAuth/current-account reports, caller-forward
++routes and ambiguous credential scopes cannot rank or veto the provider before its normal
++account selection. Restoring a matching configuration may reuse still-fresh evidence; a new
++credential cannot inherit another key's cap. The same getter controls immediate selection,
++bounded cooldown waiting and reset-window ordering. This does not override explicit eligibility,
++target cooldowns, account admission or response-driven retry rules.
++
++```text
++[Decision Log]
++- 목적과 의도: Keep account-, model- and service-scoped quota from disabling an otherwise usable Combo provider while retaining valid single-key inference caps.
++- 기존 구현 및 제약 조건: The routing cache retained only the display quota and treated any exhausted window as a provider-wide veto before account/key selection.
++- 검토한 주요 대안: Remove quota pruning entirely; infer scope from display labels; or require producer-owned inference scope and current credential binding.
++- 선택한 방식: Publish private scoped evidence only for a producer that explicitly supplies its inference projection, and validate it in both provider exclusion and reset-window ranking.
++- 다른 대안 대신 이 방식을 선택한 이유: Display labels cannot prove credential ownership, while deleting the gate would lose valid OpenRouter and other single-key caps.
++- 장점, 단점 및 영향: Scoped/ambiguous reports become unknown for early routing and may require normal dispatch to establish availability; actual account and retry limits remain authoritative.
++```
++
+ ## Same-provider combo quota fallback
+
+ For a failover combo with multiple models on the same Codex-login OpenAI provider, a pre-stream
+diff --git a/tests/codex-integration/combos.test.ts b/tests/codex-integration/combos.test.ts
+index 98174c3848..76e4f26ca9 100644
+--- a/tests/codex-integration/combos.test.ts
++++ b/tests/codex-integration/combos.test.ts
+@@ -910,7 +910,7 @@ describe("combo failure policy and advancement", () => {
+     expect(sleeps).toEqual([1_000]);
+   });
+
+-  test("still filters exhausted quota on a noncanonical forward destination", () => {
++  test("does not infer provider-wide quota from a noncanonical forward row without a credential", () => {
+     const now = 50_000;
+     const config = baseConfig({
+       providers: {
+@@ -927,7 +927,8 @@ describe("combo failure policy and advancement", () => {
+
+     const pick = pickComboTarget(config, "free", { now });
+
+-    expect(pick?.target.provider).toBe("b");
++    // This is quota selection, not proof that this custom forward route can authenticate.
++    expect(pick?.target.provider).toBe("a");
+   });
+
+   test("retains caller eligibility restrictions for native targets", () => {
+@@ -1150,6 +1151,20 @@ describe("deterministic combo selection", () => {
+     });
+   });
+
++  test.each(["oauth", "header", "key-pool"])("reset-window does not rank an inapplicable snapshot: %s", kind => {
++    const now = Date.now();
++    const config = baseConfig({ combos: { free: { strategy: "reset-window", targets: [
++      { provider: "a", model: "m1" }, { provider: "b", model: "m2" },
++    ] } } });
++    setCachedProviderQuotaForTests("a", { updatedAt: now, weeklyResetAt: now + 2_000 });
++    setCachedProviderQuotaForTests("b", { updatedAt: now, weeklyResetAt: now + 1_000 });
++    expect(pickComboTarget(config, "free", { now })?.target.provider).toBe("b");
++    if (kind === "oauth") config.providers.b!.authMode = "oauth";
++    else if (kind === "header") config.providers.b!.headers = { Authorization: "Bearer different-key" };
++    else config.providers.b!.apiKeyPool = [{ id: "one", key: "one" }, { id: "two", key: "two" }];
++    expect(pickComboTarget(config, "free", { now })?.target.provider).toBe("a");
++  });
++
+   test("reset-window treats elapsed resets as unknown and falls back to configured order", () => {
+     const now = Date.now();
+     const config = baseConfig({
+diff --git a/tests/providers/provider-quota.test.ts b/tests/providers/provider-quota.test.ts
+index 56d69951d5..0f7ea31451 100644
+--- a/tests/providers/provider-quota.test.ts
++++ b/tests/providers/provider-quota.test.ts
+@@ -18,10 +18,14 @@ import {
+   parseXaiCreditsResponse,
+   QUOTA_RESPONSE_MAX_BYTES,
+   readProviderQuotaJsonForTests,
++  publishKeyReportForTests,
+   setAntigravityAccountQuotaTransportForTests,
+   setProviderQuotaBeforePublishForTests,
+ } from "../../src/providers/quota";
+ import type { OcxConfig } from "../../src/types";
++import { clearComboTargetCooldowns, coolComboTarget, pickComboTarget, pickComboTargetWithWait } from "../../src/combos";
++import { routedProviderConfig } from "../../src/router";
++import { buildOpenAIChatPassthroughRequest } from "../../src/adapters/openai-chat";
+ import { PROXY_ENV_KEYS } from "../../src/lib/proxy-env";
+ import { repoPath } from "../helpers/repo-root";
+ const proxyKeys = PROXY_ENV_KEYS.flatMap(key => [key, key.toLowerCase()]);
+@@ -95,6 +99,7 @@ beforeEach(() => {
+ });
+
+ afterEach(() => {
++  clearComboTargetCooldowns();
+   for (const key of proxyKeys) {
+     if (originalProxyEnv[key] === undefined) delete process.env[key];
+     else process.env[key] = originalProxyEnv[key];
+@@ -703,6 +708,241 @@ describe("fetchProviderQuotaReports", () => {
+     } as OcxConfig;
+   }
+
++  function quotaCombo(config: OcxConfig): OcxConfig {
++    const provider = config.defaultProvider;
++    return {
++      ...config,
++      providers: {
++        ...config.providers,
++        fallback: { adapter: "openai-chat", baseUrl: "https://fallback.example/v1", apiKey: "fallback-key" },
++      },
++      combos: { "quota-scope": { strategy: "failover", targets: [
++        { provider, model: "primary-model" }, { provider: "fallback", model: "fallback-model" },
++      ] } },
++    };
++  }
++
++  test("routing quota scope keeps Synthetic search exhaustion out of model selection", async () => {
++    globalThis.fetch = (async () => Response.json({
++      data: { rollingFiveHourLimit: 20, weeklyTokenLimit: 30, search: { hourly: 100 } },
++    })) as typeof fetch;
++    const config = quotaCombo(keyQuotaConfig("synthetic", "https://api.synthetic.new/v2"));
++    const reports = await fetchProviderQuotaReports(config, true);
++    expect(reports.reports[0]?.quota.customWindows?.[0]?.percent).toBe(100);
++    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("synthetic");
++  });
++
++  test("routing quota scope keeps ZAI legacy MCP exhaustion out of model selection", async () => {
++    globalThis.fetch = (async () => Response.json({
++      success: true, data: { fiveHourPercent: 20, weeklyPercent: 30, monthlyMCPUsage: 100 },
++    })) as typeof fetch;
++    const config = quotaCombo(keyQuotaConfig("zai", "https://api.z.ai/api/coding/paas/v4"));
++    const reports = await fetchProviderQuotaReports(config, true);
++    expect(reports.reports[0]?.quota.monthlyPercent).toBe(100);
++    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("zai");
++  });
++
++  test("routing quota scope keeps a key-bound display-only report out of model selection", async () => {
++    // MiniMax publishes its Token Plan countdown through the display-only path. The provider
++    // is single-key `key` auth, so ownership alone would resolve a routing binding; without
++    // an inference projection the exhausted row must still not rank or veto the target.
++    globalThis.fetch = (async () => Response.json({
++      success: true, data: { remains_time: 0, total_time: 1_000_000_000 },
++    })) as typeof fetch;
++    const config = quotaCombo(keyQuotaConfig("minimax", "https://api.minimax.io/v1"));
++    const reports = await fetchProviderQuotaReports(config, true);
++    expect(reports.reports[0]?.quota.customWindows?.[0]?.percent).toBe(100);
++    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("minimax");
++  });
++
++  test("routing quota scope retains the OpenRouter single-key spending cap", async () => {
++    globalThis.fetch = (async () => Response.json({ data: { limit: 20, limit_remaining: 0 } })) as typeof fetch;
++    const config = quotaCombo(keyQuotaConfig("openrouter", "https://openrouter.ai/api/v1"));
++    await fetchProviderQuotaReports(config, true);
++    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("fallback");
++  });
++
++  test("keyReport publishes routing evidence only for an explicit inference projection", () => {
++    // The MiniMax case above rides the display-only `report()` path, so it would still pass if
++    // `keyReport`'s projection were quietly defaulted back to the display quota. This drives the
++    // credential-bound helper directly: the binding resolves for BOTH calls (same single-key
++    // provider and probed credential), so the only variable left is the projection itself.
++    const provider = keyQuotaConfig("openrouter", "https://openrouter.ai/api/v1").providers.openrouter!;
++    const exhausted = { monthlyPercent: 100 };
++
++    const omitted = publishKeyReportForTests("openrouter", "openrouter:key-info", exhausted, provider, "openrouter-secret");
++    expect(omitted.report?.quota.monthlyPercent).toBe(100);
++    expect(omitted.routing).toBeUndefined();
++
++    const projected = { monthlyPercent: 100 };
++    const explicit = publishKeyReportForTests(
++      "openrouter", "openrouter:key-info", exhausted, provider, "openrouter-secret", projected,
++    );
++    expect(explicit.routing?.quota).toBe(projected);
++    expect(typeof explicit.routing?.binding).toBe("string");
++  });
++
++  test("routing quota scope does not apply a probed key cap to an Authorization override", async () => {
++    const probeAuth: Array<string | null> = [];
++    globalThis.fetch = (async (_input, init) => {
++      probeAuth.push(new Headers(init?.headers).get("authorization"));
++      return Response.json({ data: { limit: 20, limit_remaining: 0 } });
++    }) as typeof fetch;
++    const config = quotaCombo(keyQuotaConfig("openrouter", "https://openrouter.ai/api/v1", "spent-A"));
++    config.providers.openrouter!.headers = { Authorization: "Bearer live-B" };
++    await fetchProviderQuotaReports(config, true);
++    const request = buildOpenAIChatPassthroughRequest(routedProviderConfig("openrouter", config.providers.openrouter!), {
++      messages: [{ role: "user", content: "synthetic" }],
++    }, "primary-model", false);
++    expect(probeAuth).toEqual(["Bearer spent-A"]);
++    expect(new Headers(request.headers).get("authorization")).toBe("Bearer live-B");
++    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("openrouter");
++
++    delete config.providers.openrouter!.headers;
++    await fetchProviderQuotaReports(config, true);
++    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("fallback");
++  });
++
++  test("routing quota scope rechecks an Authorization override added after publication", async () => {
++    globalThis.fetch = (async () => Response.json({ data: { limit: 20, limit_remaining: 0 } })) as typeof fetch;
++    const config = quotaCombo(keyQuotaConfig("openrouter", "https://openrouter.ai/api/v1", "spent-A"));
++    await fetchProviderQuotaReports(config, true);
++    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("fallback");
++    config.providers.openrouter!.headers = { aUtHoRiZaTiOn: "Bearer live-B" };
++    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("openrouter");
++    delete config.providers.openrouter!.headers;
++    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("fallback");
++  });
++
++  test("routing quota scope does not apply a probed key cap to an Anthropic x-api-key override", async () => {
++    const probeAuth: Array<string | null> = [];
++    globalThis.fetch = (async (_input, init) => {
++      probeAuth.push(new Headers(init?.headers).get("authorization"));
++      return Response.json({ usage: { limit: "100", used: "100" } });
++    }) as typeof fetch;
++    const config = quotaCombo(keyQuotaConfig("kimi-code", "https://api.kimi.com/coding/v1", "spent-A"));
++    config.providers["kimi-code"]!.adapter = "anthropic";
++    config.providers["kimi-code"]!.headers = { "x-api-key": "live-B" };
++    await fetchProviderQuotaReports(config, true);
++    expect(probeAuth).toEqual(["Bearer spent-A"]);
++    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("kimi-code");
++    delete config.providers["kimi-code"]!.headers;
++    await fetchProviderQuotaReports(config, true);
++    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("fallback");
++  });
++
++  test.each(["key", "omitted", "custom-key"])("routing quota scope follows effective Kimi authentication: %s", async mode => {
++    globalThis.fetch = (async () => Response.json({ usage: { limit: "100", used: "100" } })) as typeof fetch;
++    const name = mode === "custom-key" ? "kimi-code" : "kimi";
++    const config = quotaCombo(keyQuotaConfig(name, "https://api.kimi.com/coding/v1", "spent-A"));
++    if (mode === "omitted") delete config.providers[name]!.authMode;
++    expect(routedProviderConfig(name, config.providers[name]!).authMode).toBe(mode === "custom-key" ? "key" : "oauth");
++    const report = await fetchProviderQuotaReports(config, true);
++    expect(report.reports[0]?.quota.weeklyPercent).toBe(100);
++    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe(mode === "custom-key" ? "fallback" : "kimi");
++  });
++
++  test("routing quota scope keeps an exhausted Gemini group from vetoing an Antigravity Claude target", async () => {
++    await saveCredential("google-antigravity", {
++      access: "synthetic-agy-access", refresh: "synthetic-agy-refresh",
++      expires: Date.now() + 3600_000, projectId: "synthetic-project",
++    });
++    const resetTime = new Date(Date.now() + 3600_000).toISOString();
++    setAntigravityAccountQuotaTransportForTests({
++      resolveAddresses: async () => ({ hostname: "daily-cloudcode-pa.googleapis.com", addresses: [{ address: "142.250.0.1", family: 4 }], privateNetwork: false }),
++      pinnedPost: async url => {
++        expect(url.endsWith("retrieveUserQuotaSummary")).toBe(true);
++        return Response.json({ groups: [
++          { displayName: "Gemini Models", buckets: [{ window: "5h", remainingFraction: 0, resetTime }] },
++          { displayName: "Claude and GPT models", buckets: [{ window: "5h", remainingFraction: 1, resetTime }] },
++        ] });
++      },
++    });
++    const config = quotaCombo({ defaultProvider: "google-antigravity", providers: {
++      "google-antigravity": { adapter: "google", authMode: "oauth", baseUrl: "https://daily-cloudcode-pa.googleapis.com" },
++    } } as OcxConfig);
++    config.combos!["quota-scope"]!.targets[0]!.model = "claude-sonnet-4.6";
++    const report = await fetchProviderQuotaReports(config, true);
++    expect(report.reports[0]?.quota.customWindows).toEqual([
++      { label: "Gem", percent: 100, resetAt: Date.parse(resetTime) },
++      { label: "Cla", percent: 0, resetAt: Date.parse(resetTime) },
++    ]);
++    expect(pickComboTarget(config, "quota-scope")?.target).toMatchObject({ provider: "google-antigravity", model: "claude-sonnet-4.6" });
++  });
++
++  test("routing quota scope keeps an active Anthropic account report out of whole-provider selection", async () => {
++    await saveCredential("anthropic", {
++      access: "synthetic-claude-access", refresh: "synthetic-claude-refresh", expires: Date.now() + 3600_000,
++    });
++    globalThis.fetch = (async input => {
++      expect(String(input)).toBe("https://api.anthropic.com/api/oauth/usage");
++      return Response.json({ five_hour: { utilization: 100, resets_at: new Date(Date.now() + 3600_000).toISOString() } });
++    }) as typeof fetch;
++    const config = quotaCombo({ defaultProvider: "anthropic", providers: {
++      anthropic: { adapter: "anthropic", authMode: "oauth", baseUrl: "https://api.anthropic.com/v1" },
++    } } as OcxConfig);
++    const report = await fetchProviderQuotaReports(config, true);
++    expect(report.reports[0]?.quota.fiveHourPercent).toBe(100);
++    // Account selection and its exhaustion rules still decide whether this route can dispatch.
++    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("anthropic");
++    config.providers.fallback!.disabled = true;
++    const now = Date.now();
++    const waits: number[] = [];
++    coolComboTarget("quota-scope", config.combos!["quota-scope"]!.targets[0]!, { now, cooldownMs: 1_000 });
++    const afterWait = await pickComboTargetWithWait(config, "quota-scope", {
++      now, waitForCooldownMs: 1_000, sleep: async ms => { waits.push(ms); },
++    });
++    expect(waits).toEqual([1_000]);
++    expect(afterWait?.target.provider).toBe("anthropic");
++  });
++
++  test("routing quota scope retains a verified cap through a transient refresh failure", async () => {
++    let transient = false;
++    globalThis.fetch = (async () => transient
++      ? new Response("unavailable", { status: 503 })
++      : Response.json({ data: { limit: 20, limit_remaining: 0 } })) as typeof fetch;
++    const config = quotaCombo(keyQuotaConfig("openrouter", "https://openrouter.ai/api/v1"));
++    await fetchProviderQuotaReports(config, true);
++    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("fallback");
++    transient = true;
++    await fetchProviderQuotaReports(config, true);
++    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("fallback");
++  });
++
++  test("routing quota scope stops vetoing the provider when a second key is added", async () => {
++    globalThis.fetch = (async () => Response.json({ data: { limit: 20, limit_remaining: 0 } })) as typeof fetch;
++    const config = quotaCombo(keyQuotaConfig("openrouter", "https://openrouter.ai/api/v1"));
++    await fetchProviderQuotaReports(config, true);
++    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("fallback");
++    config.providers.openrouter!.apiKeyPool = [
++      { id: "old", key: "openrouter-secret" }, { id: "new", key: "second-key" },
++    ];
++    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("openrouter");
++  });
++
++  test("routing quota scope rejects a cached cap after the active key changes", async () => {
++    globalThis.fetch = (async () => Response.json({ data: { limit: 20, limit_remaining: 0 } })) as typeof fetch;
++    const config = quotaCombo(keyQuotaConfig("openrouter", "https://openrouter.ai/api/v1"));
++    await fetchProviderQuotaReports(config, true);
++    config.providers.openrouter!.apiKey = "replacement-key";
++    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("openrouter");
++  });
++
++  test("routing quota scope rejects a cached cap after an env key resolves differently", async () => {
++    const previous = process.env.OCX_TEST_ROUTING_QUOTA_KEY;
++    try {
++      process.env.OCX_TEST_ROUTING_QUOTA_KEY = "first-key";
++      globalThis.fetch = (async () => Response.json({ data: { limit: 20, limit_remaining: 0 } })) as typeof fetch;
++      const config = quotaCombo(keyQuotaConfig("openrouter", "https://openrouter.ai/api/v1", "$OCX_TEST_ROUTING_QUOTA_KEY"));
++      await fetchProviderQuotaReports(config, true);
++      process.env.OCX_TEST_ROUTING_QUOTA_KEY = "replacement-key";
++      expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("openrouter");
++    } finally {
++      if (previous === undefined) delete process.env.OCX_TEST_ROUTING_QUOTA_KEY;
++      else process.env.OCX_TEST_ROUTING_QUOTA_KEY = previous;
++    }
++  });
++
+   test("OpenRouter quota renders a credit window against the per-key cap", async () => {
+     const seen: Array<{ url: string; authorization?: string; redirect?: RequestRedirect }> = [];
+     globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+```
+
+## Current-dev consumer amendment
+
+`src/combos/resolve.ts:126` has a newer catalog `quotaInactiveReason` consumer. MODIFY its loop from separate native-forward exemption + `getCachedProviderQuota(target.provider, now)` to `getCachedProviderRoutingQuota(target.provider, provider, now)`. Unknown routing evidence returns undefined, explicit exhausted evidence retains no_credit. MODIFY the existing quota inactive tests (locate with rg quotaInactiveReason tests) to use credential-bearing provider fixtures and prove display-only/mismatched evidence cannot mark catalog rows inactive. Update stale explanatory comments to reference the scoped cache. This preserves consistency after removed imports and is necessary current-dev integration, not unrelated catalog redesign.
+
+## Design reflection D5 amendment
+
+Accept Bohr D1-D6 with D5 corrected: MODIFY `getCachedProviderRoutingQuota` to return null for nonfinite/negative/future timestamps or age `>= maxAgeMs`, aligning runtime/catalog with the editor's exclusive deadline. Retain display getter compatibility. MODIFY `tests/codex-integration/catalog-zero-credit-picker.test.ts` with genuine WeakMap publication plus positive control; then mutate apiKey/baseUrl/adapter independently and require undefined inactivity. Test timestamp at exactly 30 minutes, future, negative and NaN as unknown. This is the shared scoped evidence boundary, not a new auth flow. No local suites; hosted final tip owns execution.
diff --git a/devlog/_plan/260912_combo_carry/020_editor.md b/devlog/_plan/260912_combo_carry/020_editor.md
new file mode 100644
index 0000000000..fe03bd8982
--- /dev/null
+++ b/devlog/_plan/260912_combo_carry/020_editor.md
@@ -0,0 +1,1091 @@
+# editor carry
+
+MODIFY exactly the paths in this public source diff. Apply each original commit in order with attribution. Resolve retired structure document into current runtime.md and gui-and-management-api.md; never restore the retired file. Earlier phase dependency: runtime.
+
+Before/after source contract (review against current dev at P; source diff is the executable carry input):
+
+```diff
+diff --git a/docs-site/src/content/docs/fr/guides/combos.md b/docs-site/src/content/docs/fr/guides/combos.md
+index 9434a1e98a..9073372327 100644
+--- a/docs-site/src/content/docs/fr/guides/combos.md
++++ b/docs-site/src/content/docs/fr/guides/combos.md
+@@ -281,9 +281,7 @@ Ouvrez le tableau de bord local et choisissez **Modèles → Combos**. L'espace
+ combos, et son sélecteur de cible exclut les modèles désactivés et les combos imbriqués.
+
+ Chaque cible affiche aussi un badge de quota en direct : **Disponible**, **Quota épuisé** ou **Quota inconnu**.
+-Enregistrer et Créer ne sont désactivés que lorsque chaque cible activée dispose de preuves fraîches et complètes
+-que son quota est épuisé. Les données manquantes, obsolètes, mal formées ou agrégées de façon incomplète restent
+-inconnues et ne verrouillent jamais un contrôle. La récupération du quota réactive automatiquement l’action.
++L’éditeur bloque Enregistrer et Créer pour une raison de quota uniquement lorsque chaque cible utilisable dispose d’une confirmation serveur encore valide indiquant que la limite d’inférence liée à ses identifiants configurés est épuisée. Les quotas de compte, de modèle, de recherche et de MCP fournis uniquement à titre d’affichage, ainsi que les informations de routage absentes ou expirées, ne déclenchent pas ce blocage. Le blocage expire à la réinitialisation applicable ou à l’expiration de la validité des données et fait l’objet d’une nouvelle vérification lorsque la page devient active ou visible ; Actualiser recharge à la fois les données des combos et les quotas.
+
+ ### CLI
+
+diff --git a/docs-site/src/content/docs/guides/combos.md b/docs-site/src/content/docs/guides/combos.md
+index c7d076d9b7..ef5ccde16c 100644
+--- a/docs-site/src/content/docs/guides/combos.md
++++ b/docs-site/src/content/docs/guides/combos.md
+@@ -349,10 +349,7 @@ task workflow.
+ Open the local dashboard and choose **Models → Combos**. The workspace creates, edits, renames, and removes
+ combos, and its target picker excludes disabled models and nested combos.
+
+-Each target also shows a live quota badge: **Available**, **Out of quota**, or **Quota unknown**. Save and
+-Create are disabled only when every enabled target has fresh, complete evidence that its quota is exhausted.
+-Missing, stale, malformed, or incomplete aggregate evidence stays unknown and never locks a control. Polling
+-continues while the workspace is visible, so recovery automatically restores the action. The dashboard
++Each target also shows a live quota badge: **Available**, **Out of quota**, or **Quota unknown**. The editor blocks Save and Create for quota only when every usable target has a current server-confirmed exhausted inference limit for its configured credential. Display-only account, model, search and MCP quota, or missing or expired routing evidence, does not cause this block. The block expires at the applicable reset or freshness boundary and is rechecked when the page becomes active or visible; Refresh reloads both Combo data and quota. The dashboard
+ editor does not yet expose `cooldownMs` or `waitForCooldownMs`; use the configuration file or management
+ API until the follow-up UI work lands.
+
+diff --git a/docs-site/src/content/docs/ja/guides/combos.md b/docs-site/src/content/docs/ja/guides/combos.md
+index f6eca53214..70c902ec6e 100644
+--- a/docs-site/src/content/docs/ja/guides/combos.md
++++ b/docs-site/src/content/docs/ja/guides/combos.md
+@@ -182,8 +182,7 @@ v1/base/v2 モードと完全な暗号化タスクのワークフローについ
+ ローカル ダッシュボードを開き、**Models → コンボ**を選択します。ワークスペースはコンボを作成、編集、名前変更、削除し、そのターゲット ピッカーは無効なモデルとネストされたコンボを除外します。
+
+ 各ターゲットには **利用可能**、**クォータを使い切りました**、**クォータ不明** のライブバッジも表示されます。
+-保存と作成が無効になるのは、有効な全ターゲットについて、クォータ枯渇を示す新鮮で完全な証拠がある場合だけです。
+-欠落、古い、不正、または不完全な集約データは不明のままで、操作をロックしません。クォータが回復すると操作は自動で再び有効になります。ダッシュボードのエディターではまだ `cooldownMs` と `waitForCooldownMs` を設定できません。後続の UI 作業が完了するまでは、構成ファイルまたは管理 API を使用してください。
++エディターがクォータを理由に保存と作成をブロックするのは、使用可能なすべてのターゲットについて、設定された認証情報の推論上限に達したことを示す、サーバーによる確認が現在も有効な場合だけです。表示専用のアカウント・モデル・検索・MCP クォータや、ルーティングの根拠情報の欠落・期限切れによって、このブロックが発生することはありません。ブロックは該当するリセット時刻またはデータの有効期限に解除され、ページがアクティブになるか表示状態になると再確認されます。「更新」はコンボデータとクォータの両方を再読み込みします。ダッシュボードのエディターではまだ `cooldownMs` と `waitForCooldownMs` を設定できません。後続の UI 作業が完了するまでは、構成ファイルまたは管理 API を使用してください。
+
+ ### CLI
+
+diff --git a/docs-site/src/content/docs/ko/guides/combos.md b/docs-site/src/content/docs/ko/guides/combos.md
+index 71e557f25c..80eac32c2d 100644
+--- a/docs-site/src/content/docs/ko/guides/combos.md
++++ b/docs-site/src/content/docs/ko/guides/combos.md
+@@ -187,9 +187,7 @@ v1/base/v2 모드와 암호화된 작업의 전체 흐름은 [Sub-agent Surface]
+
+ 로컬 대시보드를 열고 **Models → Combos**를 선택합니다. 워크스페이스는 콤보를 만들고, 편집하고, 이름을 바꾸고, 제거할 수 있으며, 대상 선택기에서는 비활성 모델과 중첩 콤보를 제외합니다.
+
+-각 대상에는 **사용 가능**, **할당량 소진**, **할당량 알 수 없음** 실시간 배지도 표시됩니다. 저장과 만들기 버튼은
+-활성화된 모든 대상에 할당량 소진을 입증하는 최신의 완전한 증거가 있을 때만 비활성화됩니다. 누락되거나 오래되거나
+-형식이 잘못되었거나 집계가 불완전한 데이터는 알 수 없음으로 남으며 버튼을 잠그지 않습니다. 할당량이 복구되면 버튼도 자동으로 다시 활성화됩니다. 대시보드 편집기에서는 아직 `cooldownMs`나 `waitForCooldownMs`를 설정할 수 없습니다. 후속 UI 작업이 완료될 때까지 구성 파일이나 관리 API를 사용하세요.
++각 대상에는 **사용 가능**, **할당량 소진**, **할당량 알 수 없음** 실시간 배지도 표시됩니다. 편집기는 사용 가능한 모든 대상에 대해 설정된 인증 정보의 추론 한도가 소진되었다는 서버 확인이 현재 유효할 때만 할당량을 이유로 저장과 만들기를 차단합니다. 표시 전용 계정·모델·검색·MCP 할당량이나 누락되거나 만료된 라우팅 근거 정보는 이 차단을 일으키지 않습니다. 차단은 해당 한도의 초기화 시점이나 데이터 유효기간이 끝나면 해제되며 페이지가 활성화되거나 표시될 때 다시 확인됩니다. 새로 고침은 콤보 데이터와 할당량을 모두 다시 불러옵니다. 대시보드 편집기에서는 아직 `cooldownMs`나 `waitForCooldownMs`를 설정할 수 없습니다. 후속 UI 작업이 완료될 때까지 구성 파일이나 관리 API를 사용하세요.
+
+ ### CLI
+
+diff --git a/docs-site/src/content/docs/ru/guides/combos.md b/docs-site/src/content/docs/ru/guides/combos.md
+index 868416ae5b..b873f4ed03 100644
+--- a/docs-site/src/content/docs/ru/guides/combos.md
++++ b/docs-site/src/content/docs/ru/guides/combos.md
+@@ -234,9 +234,7 @@ effort вызывающей стороне и цели.
+ переименовывать и удалять combo, а селектор целей исключает отключённые модели и вложенные combo.
+
+ У каждой цели также отображается актуальный значок квоты: **Доступно**, **Квота исчерпана** или **Квота неизвестна**.
+-Кнопки сохранения и создания отключаются только тогда, когда для всех включённых целей есть свежие и полные
+-данные об исчерпании квоты. Отсутствующие, устаревшие, некорректные или неполные агрегированные данные остаются
+-неизвестными и никогда не блокируют управление. Восстановление квоты автоматически снова включает действие. Редактор дашборда пока не предоставляет `cooldownMs` и `waitForCooldownMs`; до появления соответствующего UI используйте файл конфигурации или Management API.
++Редактор блокирует сохранение и создание из-за квоты только тогда, когда для каждой пригодной к использованию цели есть действующее подтверждение сервера об исчерпании лимита инференса для настроенных учётных данных. Квоты аккаунта, модели, поиска и MCP, предназначенные только для отображения, а также отсутствующие или просроченные данные для принятия решения о маршрутизации не вызывают эту блокировку. Блокировка истекает при соответствующем сбросе квоты или окончании срока актуальности данных и проверяется повторно, когда страница становится активной или видимой; «Обновить» повторно загружает и данные combo, и квоты. Редактор дашборда пока не предоставляет `cooldownMs` и `waitForCooldownMs`; до появления соответствующего UI используйте файл конфигурации или Management API.
+
+ ### CLI
+
+diff --git a/docs-site/src/content/docs/tr/guides/combos.md b/docs-site/src/content/docs/tr/guides/combos.md
+index 520c157e83..b8cd5bad0d 100644
+--- a/docs-site/src/content/docs/tr/guides/combos.md
++++ b/docs-site/src/content/docs/tr/guides/combos.md
+@@ -312,9 +312,7 @@ hedef seçicisi ise devre dışı bırakılmış modelleri ve iç içe geçmiş
+ hariç tutar.
+
+ Her hedef ayrıca canlı bir kota rozeti gösterir: **Kullanılabilir**, **Kota tükendi** veya **Kota bilinmiyor**.
+-Kaydet ve Oluştur yalnızca etkin hedeflerin tamamı için kotanın tükendiğini gösteren güncel ve eksiksiz kanıt varsa
+-devre dışı bırakılır. Eksik, eski, bozuk veya tamamlanmamış toplu kanıt bilinmiyor olarak kalır ve denetimleri asla
+-kilitlemez. Kota yenilendiğinde işlem otomatik olarak yeniden etkinleşir.
++Düzenleyici, kota nedeniyle Kaydet ve Oluştur işlemlerini yalnızca kullanılabilir hedeflerin tümü için yapılandırılmış kimlik bilgisine ait çıkarım sınırının tükendiğini doğrulayan geçerli sunucu bilgisi varsa engeller. Yalnızca görüntüleme amaçlı hesap, model, arama ve MCP kotaları ya da eksik veya süresi dolmuş yönlendirme kanıtları bu engellemeye neden olmaz. Engelleme, ilgili sıfırlama zamanında veya verinin güncellik süresi dolduğunda sona erer ve sayfa etkin ya da görünür olduğunda yeniden kontrol edilir; Yenile, hem kombo verilerini hem de kotaları yeniden yükler.
+
+ ### CLI
+
+@@ -411,4 +409,3 @@ Hata hedefe özgü olmaktan ziyade uç (terminal) bir hataydı. Geçersiz girdiy
+ düzeltin, aşırı büyük bir bağlamı azaltın, bir politika reddini işleyin veya
+ reddedilen istek kaynağını düzeltin. Kombolar bu durumlar için atlama yapmaz.
+
+-
+diff --git a/docs-site/src/content/docs/zh-cn/guides/combos.md b/docs-site/src/content/docs/zh-cn/guides/combos.md
+index d84efca472..abe32ae786 100644
+--- a/docs-site/src/content/docs/zh-cn/guides/combos.md
++++ b/docs-site/src/content/docs/zh-cn/guides/combos.md
+@@ -211,9 +211,7 @@ combo 失败分为 **跳转** 失败和 **终止** 失败。
+
+ 打开本地 dashboard 并选择 **Models → Combos**。该工作区可以创建、编辑、重命名和删除 combo，其目标选择器会排除已禁用的模型和嵌套 combo。
+
+-每个目标还会显示实时额度徽章：**可用**、**额度已用尽**或**额度未知**。只有当所有已启用目标都有最新、
+-完整的额度耗尽证据时，保存和创建操作才会被禁用。缺失、过期、格式错误或聚合不完整的证据会保持为未知，
+-绝不会锁定控件。额度恢复后，操作会自动重新启用。dashboard 编辑器目前还不能设置 `cooldownMs` 或 `waitForCooldownMs`；在后续 UI 完成前，请使用配置文件或管理 API。
++每个目标还会显示实时额度徽章：**可用**、**额度已用尽**或**额度未知**。只有当每个可用目标均有当前有效的服务器确认，表明其所配置凭据的推理限额已耗尽时，编辑器才会因额度而禁止保存和创建。仅供显示的账户、模型、搜索和 MCP 额度，以及缺失或已过期的路由依据，都不会触发此限制。此限制会在适用的重置时间或数据有效期结束时解除，并在页面变为活动或可见状态时重新检查；刷新会同时重新加载 Combo 数据和额度。dashboard 编辑器目前还不能设置 `cooldownMs` 或 `waitForCooldownMs`；在后续 UI 完成前，请使用配置文件或管理 API。
+
+ ### CLI
+
+diff --git a/docs-site/src/content/docs/zh-tw/guides/combos.md b/docs-site/src/content/docs/zh-tw/guides/combos.md
+index d82b399e6f..ce3ad70a94 100644
+--- a/docs-site/src/content/docs/zh-tw/guides/combos.md
++++ b/docs-site/src/content/docs/zh-tw/guides/combos.md
+@@ -219,9 +219,7 @@ Codex v2 子代理有一個重要限制（[issue #92](https://github.com/lidge-j
+
+ 開啟本機儀表板並選擇 **Combos**。該工作區可建立、編輯、重新命名與移除 combo，且其目標 picker 會排除已停用的模型與巢狀 combo。
+
+-每個目標也會顯示即時額度徽章：**可用**、**額度已用盡**或**額度未知**。只有當所有已啟用目標都有最新、
+-完整的額度耗盡證據時，儲存與建立操作才會停用。缺失、過期、格式錯誤或聚合不完整的證據會維持未知，
+-絕不會鎖住控制項。額度恢復後，操作會自動重新啟用。
++每個目標也會顯示即時額度徽章：**可用**、**額度已用盡**或**額度未知**。只有當每個可用目標均有目前有效的伺服器確認，顯示其所設定憑證的推論限額已耗盡時，編輯器才會因配額而停用儲存與建立。僅供顯示的帳戶、模型、搜尋與 MCP 配額，以及缺失或已過期的路由依據，都不會觸發此限制。此限制會在適用的重設時間或資料有效期限結束時解除，並在頁面變為作用中或可見狀態時重新檢查；重新整理會同時重新載入 Combo 資料與配額。
+
+ ### CLI
+
+diff --git a/gui/src/combo-workspace-data.ts b/gui/src/combo-workspace-data.ts
+index bf8b881c55..b89bff656f 100644
+--- a/gui/src/combo-workspace-data.ts
++++ b/gui/src/combo-workspace-data.ts
+@@ -4,6 +4,7 @@
+  */
+
+ import { SUPPORTED_NATIVE_OPENAI_SLUGS } from "../../src/codex/catalog/native-models";
++import { PROVIDER_QUOTA_MAX_AGE_MS } from "../../src/providers/quota-types";
+ import type { TKey } from "./i18n/shared";
+
+ export { SUPPORTED_NATIVE_OPENAI_SLUGS };
+@@ -92,7 +93,7 @@ export type ComboQuotaState = "available" | "exhausted" | "unknown";
+ export type ProviderQuotaStates = Readonly<Record<string, ComboQuotaState>>;
+
+ /** Matches the management endpoint's bounded last-good quota lifetime. */
+-export const COMBO_QUOTA_MAX_AGE_MS = 30 * 60_000;
++export const COMBO_QUOTA_MAX_AGE_MS = PROVIDER_QUOTA_MAX_AGE_MS;
+
+ let comboTargetKeySeq = 0;
+
+@@ -282,133 +283,36 @@ function finiteNumber(value: unknown): number | null {
+   return typeof value === "number" && Number.isFinite(value) ? value : null;
+ }
+
+-function quotaTimestampIsFresh(value: unknown, now: number): boolean {
+-  const timestamp = finiteNumber(value);
+-  return timestamp !== null && now - timestamp < COMBO_QUOTA_MAX_AGE_MS;
+-}
+-
+-function nonNegativeInteger(value: unknown): number | null {
+-  const number = finiteNumber(value);
+-  return number !== null && Number.isInteger(number) && number >= 0 ? number : null;
+-}
+-
+-function aggregateWindowIsComplete(value: unknown, now: number): boolean {
+-  const window = recordFromUnknown(value);
+-  const usedPercent = finiteNumber(window?.usedPercent);
+-  return !!window
+-    && usedPercent !== null
+-    && usedPercent >= 0
+-    && nonNegativeInteger(window.includedAccounts) !== null
+-    && (nonNegativeInteger(window.includedAccounts) ?? 0) > 0
+-    && nonNegativeInteger(window.excludedAccounts) === 0
+-    && window.incomplete === false
+-    && quotaTimestampIsFresh(window.updatedAt, now);
+-}
+-
+-function aggregateEvidenceIsComplete(value: unknown, now: number): boolean {
+-  const aggregation = recordFromUnknown(value);
+-  if (
+-    !aggregation
+-    || aggregation.kind !== "capacity-weighted-v1"
+-    || aggregation.scope !== "routable-known"
+-    || aggregation.presentation !== "aggregate"
+-    || aggregation.incomplete !== false
+-  ) return false;
+-
+-  for (const key of [
+-    "includedAccounts",
+-    "excludedAccounts",
+-    "unknownPlanAccounts",
+-    "missingQuotaAccounts",
+-    "pausedAccounts",
+-    "reauthAccounts",
+-    "staleQuotaAccounts",
+-    "partialWindowAccounts",
+-  ] as const) {
+-    if (nonNegativeInteger(aggregation[key]) === null) return false;
+-  }
+-  if ((nonNegativeInteger(aggregation.includedAccounts) ?? 0) === 0) return false;
+-  for (const key of [
+-    "excludedAccounts",
+-    "unknownPlanAccounts",
+-    "missingQuotaAccounts",
+-    "pausedAccounts",
+-    "reauthAccounts",
+-    "staleQuotaAccounts",
+-    "partialWindowAccounts",
+-  ] as const) {
+-    if (aggregation[key] !== 0) return false;
+-  }
+-
+-  let hasWindow = false;
+-  for (const key of ["fiveHour", "weekly", "monthly"] as const) {
+-    if (!Object.hasOwn(aggregation, key)) continue;
+-    if (!aggregateWindowIsComplete(aggregation[key], now)) return false;
+-    hasWindow = true;
+-  }
+-  if (Object.hasOwn(aggregation, "customWindows")) {
+-    if (!Array.isArray(aggregation.customWindows)) return false;
+-    for (const value of aggregation.customWindows) {
+-      const custom = recordFromUnknown(value);
+-      if (!custom || typeof custom.label !== "string" || !custom.label.trim()) return false;
+-      if (!aggregateWindowIsComplete(custom, now)) return false;
+-      hasWindow = true;
+-    }
+-  }
+-  return hasWindow;
++function routingQuotaFromReport(raw: Record<string, unknown>, now: number): {
++  state: "available" | "exhausted";
++  validUntil: number;
++} | null {
++  const routing = recordFromUnknown(raw.routingQuota);
++  if (!routing || (routing.state !== "available" && routing.state !== "exhausted")) return null;
++  const updatedAt = finiteNumber(routing.updatedAt);
++  const validUntil = finiteNumber(routing.validUntil);
++  if (updatedAt === null || updatedAt < 0 || updatedAt > now
++    || now - updatedAt >= COMBO_QUOTA_MAX_AGE_MS
++    || validUntil === null || validUntil <= now
++    || validUntil > updatedAt + COMBO_QUOTA_MAX_AGE_MS) return null;
++  return { state: routing.state, validUntil };
+ }
+
+ function quotaStateFromReport(raw: Record<string, unknown>, now: number): ComboQuotaState {
+-  if (!quotaTimestampIsFresh(raw.updatedAt, now)) return "unknown";
+-  const quota = recordFromUnknown(raw.quota);
+-  if (!quota || !quotaTimestampIsFresh(quota.updatedAt, now)) return "unknown";
+-  if (raw.aggregation !== undefined && !aggregateEvidenceIsComplete(raw.aggregation, now)) return "unknown";
+-
+-  let hasEvidence = false;
+-  let exhausted = false;
+-  for (const key of ["fiveHourPercent", "weeklyPercent", "monthlyPercent"] as const) {
+-    if (!Object.hasOwn(quota, key)) continue;
+-    const percent = finiteNumber(quota[key]);
+-    if (percent === null || percent < 0) return "unknown";
+-    hasEvidence = true;
+-    if (percent >= 100) exhausted = true;
+-  }
+-  for (const key of ["fiveHourResetAt", "weeklyResetAt", "monthlyResetAt"] as const) {
+-    if (Object.hasOwn(quota, key) && finiteNumber(quota[key]) === null) return "unknown";
+-  }
+-
+-  if (Object.hasOwn(quota, "customWindows")) {
+-    if (!Array.isArray(quota.customWindows)) return "unknown";
+-    for (const value of quota.customWindows) {
+-      const window = recordFromUnknown(value);
+-      const percent = finiteNumber(window?.percent);
+-      if (!window || typeof window.label !== "string" || !window.label.trim() || percent === null || percent < 0) {
+-        return "unknown";
+-      }
+-      if (Object.hasOwn(window, "resetAt") && finiteNumber(window.resetAt) === null) return "unknown";
+-      hasEvidence = true;
+-      if (percent >= 100) exhausted = true;
+-    }
+-  }
++  return routingQuotaFromReport(raw, now)?.state ?? "unknown";
++}
+
+-  if (Object.hasOwn(quota, "creditsUsd")) {
+-    const credits = recordFromUnknown(quota.creditsUsd);
+-    if (!credits) return "unknown";
+-    const used = finiteNumber(credits.used);
+-    const limit = finiteNumber(credits.limit);
+-    const remaining = finiteNumber(credits.remaining);
+-    const percent = finiteNumber(credits.percent);
+-    if (used === null || used < 0 || limit === null || limit < 0 || remaining === null || percent === null || percent < 0) {
+-      return "unknown";
+-    }
+-    if (credits.unlimited !== undefined && typeof credits.unlimited !== "boolean") return "unknown";
+-    if (Object.hasOwn(credits, "expiresAt") && finiteNumber(credits.expiresAt) === null) return "unknown";
+-    hasEvidence = true;
+-    if (credits.unlimited !== true && remaining <= 0) exhausted = true;
++/** The next expiry also wakes the page when no poll response has arrived. */
++export function nextProviderQuotaStateExpiration(reports: unknown, now = Date.now()): number | undefined {
++  if (!Array.isArray(reports)) return undefined;
++  let next: number | undefined;
++  for (const value of reports) {
++    const report = recordFromUnknown(value);
++    if (!report || typeof report.provider !== "string" || !report.provider.trim()) continue;
++    const routing = routingQuotaFromReport(report, now);
++    if (routing && (next === undefined || routing.validUntil < next)) next = routing.validUntil;
+   }
+-
+-  if (!hasEvidence) return "unknown";
+-  return exhausted ? "exhausted" : "available";
++  return next;
+ }
+
+ /** Fail-unknown parser for the live `/api/provider-quotas` report array. */
+diff --git a/gui/src/pages/Combos.tsx b/gui/src/pages/Combos.tsx
+index ca05ca8fd5..dee11a7e69 100644
+--- a/gui/src/pages/Combos.tsx
++++ b/gui/src/pages/Combos.tsx
+@@ -5,6 +5,7 @@ import {
+   comboModelId,
+   parseComboList,
+   providerQuotaStatesFromReports,
++  nextProviderQuotaStateExpiration,
+   toPutBody,
+ } from "../combo-workspace-data";
+ import { hideRedundantChatGptForwardProviders } from "../provider-workspace/catalog";
+@@ -239,12 +240,24 @@ export default function Combos({
+       enabled: active,
+     },
+   );
+-  const providerQuotaStates = useMemo(
+-    () => quotaResource.lastAttemptOk
+-      ? providerQuotaStatesFromReports(quotaResource.data?.reports)
+-      : {},
+-    [quotaResource.data, quotaResource.lastAttemptOk],
+-  );
++  const [quotaNow, setQuotaClock] = useState(() => Date.now());
++  const quotaReports = active && quotaResource.lastAttemptOk ? quotaResource.data?.reports : undefined;
++  const providerQuotaStates = providerQuotaStatesFromReports(quotaReports, quotaNow);
++  const quotaExpiry = nextProviderQuotaStateExpiration(quotaReports, quotaNow);
++  useEffect(() => {
++    if (!active) return;
++    const recheck = () => setQuotaClock(Date.now());
++    // The render may cross this boundary before effects run. Keep its deadline and wake now.
++    // A new snapshot may be newer than this clock, so unknown state also gets one immediate check.
++    const timer = window.setTimeout(recheck,
++      quotaExpiry === undefined ? 0 : Math.max(0, quotaExpiry - Date.now()));
++    const onVisible = () => { if (document.visibilityState === "visible") recheck(); };
++    document.addEventListener("visibilitychange", onVisible);
++    return () => {
++      window.clearTimeout(timer);
++      document.removeEventListener("visibilitychange", onVisible);
++    };
++  }, [active, apiBase, quotaResource.data, quotaResource.lastAttemptOk, quotaExpiry]);
+
+   const data = state.data ?? retainedData ?? undefined;
+   const combos = data?.combos ?? [];
+@@ -361,7 +374,7 @@ export default function Combos({
+           models={models}
+           cataloguedComboIds={cataloguedComboIds}
+           loading={false}
+-          onRefresh={() => resource.refresh()}
++          onRefresh={() => { resource.refresh(); quotaResource.refresh(); }}
+           onSave={saveCombo}
+           onRemove={removeCombo}
+           onAdd={() => setAdding(true)}
+diff --git a/gui/tests/combo-workspace-dirty.test.tsx b/gui/tests/combo-workspace-dirty.test.tsx
+index 1f3566dbbe..c82ac799d4 100644
+--- a/gui/tests/combo-workspace-dirty.test.tsx
++++ b/gui/tests/combo-workspace-dirty.test.tsx
+@@ -2,7 +2,7 @@ import { afterEach, beforeEach, expect, test } from "bun:test";
+ import { Window } from "happy-dom";
+ import { act, StrictMode } from "react";
+ import type { Root } from "react-dom/client";
+-import type { ComboItem } from "../src/combo-workspace-data";
++import { type ComboItem, providerQuotaStatesFromReports } from "../src/combo-workspace-data";
+ import ComboWorkspace from "../src/components/ComboWorkspace";
+ import { LanguageProvider } from "../src/i18n/provider";
+
+@@ -178,11 +178,14 @@ test("dirty Save disables for exhausted targets and re-enables on quota recovery
+   document.body.append(container);
+   const root = createRoot(container);
+
+-  const render = (quotaState: "available" | "exhausted") => (
++  const now = Date.now();
++  const display = { provider: "openai", updatedAt: now,
++    quota: { updatedAt: now, customWindows: [{ label: "Search", percent: 100 }] } };
++  const render = (routingQuota?: Record<string, unknown>) => (
+     <LanguageProvider>
+       <ComboWorkspace
+         combos={combos}
+-        providerQuotaStates={{ openai: quotaState }}
++        providerQuotaStates={providerQuotaStatesFromReports([{ ...display, routingQuota }], now)}
+         providers={[{ name: "openai" }]}
+         models={[{ provider: "openai", id: "gpt-5" }]}
+         loading={false}
+@@ -197,7 +200,7 @@ test("dirty Save disables for exhausted targets and re-enables on quota recovery
+     </LanguageProvider>
+   );
+
+-  await act(async () => { root.render(render("exhausted")); });
++  await act(async () => { root.render(render({ state: "exhausted", updatedAt: now, validUntil: now + 60_000 })); });
+   await flushTimers();
+   await act(async () => { railButton(container, "combo/alpha").click(); });
+   await flushTimers();
+@@ -208,7 +211,11 @@ test("dirty Save disables for exhausted targets and re-enables on quota recovery
+   expect(container.querySelector<HTMLButtonElement>("#cwi-edit-save")!.disabled).toBe(true);
+   expect(container.textContent).toContain("All enabled targets are out of quota");
+
+-  await act(async () => { root.render(render("available")); });
++  await act(async () => { root.render(render()); });
++  expect(container.querySelector<HTMLButtonElement>("#cwi-edit-save")!.disabled).toBe(false);
++  expect(container.textContent).not.toContain("All enabled targets are out of quota");
++
++  await act(async () => { root.render(render({ state: "available", updatedAt: now, validUntil: now + 60_000 })); });
+   expect(container.querySelector<HTMLButtonElement>("#cwi-edit-save")!.disabled).toBe(false);
+   expect(container.textContent).not.toContain("All enabled targets are out of quota");
+
+diff --git a/gui/tests/combo-workspace-empty.test.tsx b/gui/tests/combo-workspace-empty.test.tsx
+index 4fb8416067..ba6efc49d7 100644
+--- a/gui/tests/combo-workspace-empty.test.tsx
++++ b/gui/tests/combo-workspace-empty.test.tsx
+@@ -5,6 +5,7 @@ import type { Root } from "react-dom/client";
+ import { renderToStaticMarkup } from "react-dom/server";
+ import ComboWorkspace from "../src/components/ComboWorkspace";
+ import { LanguageProvider } from "../src/i18n/provider";
++import { providerQuotaStatesFromReports } from "../src/combo-workspace-data";
+
+ const globals = ["document", "window", "navigator", "localStorage", "IS_REACT_ACT_ENVIRONMENT"] as const;
+ let previousGlobals: Record<(typeof globals)[number], unknown>;
+@@ -134,11 +135,14 @@ test("first-combo Create disables only while every usable target is known exhaus
+   document.body.append(container);
+   const root = createRoot(container);
+
+-  const render = (quotaState: "available" | "exhausted") => (
++  const now = Date.now();
++  const display = { provider: "openai", updatedAt: now,
++    quota: { updatedAt: now, customWindows: [{ label: "Search", percent: 100 }] } };
++  const render = (routingQuota?: Record<string, unknown>) => (
+     <LanguageProvider>
+       <ComboWorkspace
+         combos={[]}
+-        providerQuotaStates={{ openai: quotaState }}
++        providerQuotaStates={providerQuotaStatesFromReports([{ ...display, routingQuota }], now)}
+         providers={[{ name: "openai" }]}
+         models={[{ provider: "openai", id: "gpt-5" }]}
+         loading={false}
+@@ -153,7 +157,7 @@ test("first-combo Create disables only while every usable target is known exhaus
+     </LanguageProvider>
+   );
+
+-  await act(async () => { root.render(render("exhausted")); });
++  await act(async () => { root.render(render({ state: "exhausted", updatedAt: now, validUntil: now + 60_000 })); });
+   await act(async () => { await new Promise((resolve) => window.setTimeout(resolve, 0)); });
+
+   const providerSelect = container.querySelector<HTMLSelectElement>('select[aria-label="Provider"]')!;
+@@ -167,7 +171,11 @@ test("first-combo Create disables only while every usable target is known exhaus
+   expect(createButton.disabled).toBe(true);
+   expect(container.textContent).toContain("All enabled targets are out of quota");
+
+-  await act(async () => { root.render(render("available")); });
++  await act(async () => { root.render(render()); });
++  expect(container.querySelector<HTMLButtonElement>("#cwi-edit-create")!.disabled).toBe(false);
++  expect(container.textContent).not.toContain("All enabled targets are out of quota");
++
++  await act(async () => { root.render(render({ state: "available", updatedAt: now, validUntil: now + 60_000 })); });
+   expect(container.querySelector<HTMLButtonElement>("#cwi-edit-create")!.disabled).toBe(false);
+   expect(container.textContent).not.toContain("All enabled targets are out of quota");
+
+diff --git a/gui/tests/page-loading-contract.test.tsx b/gui/tests/page-loading-contract.test.tsx
+index 2ab6b88385..52a889fb28 100644
+--- a/gui/tests/page-loading-contract.test.tsx
++++ b/gui/tests/page-loading-contract.test.tsx
+@@ -1,6 +1,6 @@
+-import { afterEach, beforeEach, expect, test } from "bun:test";
++import { afterEach, beforeEach, expect, spyOn, test } from "bun:test";
+ import { Window } from "happy-dom";
+-import { act } from "react";
++import { act, useLayoutEffect } from "react";
+ import type { Root } from "react-dom/client";
+ import Combos from "../src/pages/Combos";
+ import { LanguageProvider } from "../src/i18n/provider";
+@@ -204,3 +204,111 @@ test("Combos announces silent revalidation over cached content via aria-busy", a
+   await act(async () => { root.unmount(); });
+   container.remove();
+ });
++
++
++test.each(["timer", "visible", "active", "commit-boundary"])("Combos expires a quota block before a new response: %s", async wake => {
++  const { createRoot } = await import("react-dom/client");
++  const startedAt = Date.now();
++  let now = startedAt;
++  const clock = spyOn(Date, "now").mockImplementation(() => now);
++  const schedule = testWindow.setTimeout.bind(testWindow);
++  const cancel = testWindow.clearTimeout.bind(testWindow);
++  const expiryTimers = new Set<number>();
++  let expire: (() => void) | undefined;
++  const scheduleSpy = spyOn(testWindow, "setTimeout").mockImplementation((callback, delay, ...args) => {
++    const timer = schedule(callback, delay, ...args);
++    if (delay === 123_456 && typeof callback === "function") {
++      expiryTimers.add(timer);
++      expire = () => callback(...args);
++    }
++    return timer;
++  });
++  const cancelSpy = spyOn(testWindow, "clearTimeout").mockImplementation(timer => {
++    expiryTimers.delete(timer);
++    cancel(timer);
++  });
++  const item = { id: "alpha", model: "combo/alpha", strategy: "failover", stickyLimit: 1,
++    targets: [{ provider: "keyed", model: "m1" }] };
++  let quotaFetches = 0;
++  const workspaceFetches = new Map<string, number>();
++  const waitForAbort = (signal: AbortSignal | null | undefined) => new Promise<Response>((_resolve, reject) => {
++    if (signal?.aborted) reject(signal.reason);
++    else signal?.addEventListener("abort", () => reject(signal.reason), { once: true });
++  });
++  globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
++    const url = String(input);
++    if (url.includes("/api/provider-quotas")) {
++      quotaFetches += 1;
++      if (quotaFetches > 1) return waitForAbort(init?.signal);
++      return Response.json({ reports: [{ provider: "keyed", updatedAt: startedAt,
++        quota: { updatedAt: startedAt, fiveHourPercent: 100 },
++        routingQuota: { state: "exhausted", updatedAt: startedAt, validUntil: startedAt + 123_456 },
++      }] });
++    }
++    const count = (workspaceFetches.get(url) ?? 0) + 1;
++    workspaceFetches.set(url, count);
++    if (count > 1) return waitForAbort(init?.signal);
++    if (url.includes("/api/combos")) return Response.json({ combos: [item] });
++    if (url.includes("/api/config")) return Response.json({ providers: {
++      keyed: { adapter: "openai-chat", authMode: "key", baseUrl: "https://provider.example/v1", defaultModel: "m1" },
++    } });
++    if (url.includes("/api/models")) return Response.json([
++      { provider: "keyed", id: "m1" }, { provider: "combo", id: "alpha" },
++    ]);
++    return new Response(null, { status: 404 });
++  }) as typeof fetch;
++  const container = document.createElement("div");
++  document.body.append(container);
++  const root = createRoot(container);
++  function ClockBoundary({ active, expireDuringCommit }: { active: boolean; expireDuringCommit: boolean }) {
++    useLayoutEffect(() => {
++      if (expireDuringCommit) now = startedAt + 123_456;
++    }, [expireDuringCommit]);
++    return <LanguageProvider><Combos apiBase={API_BASE} active={active} /></LanguageProvider>;
++  }
++  const render = (active = true, expireDuringCommit = false) =>
++    <ClockBoundary active={active} expireDuringCommit={expireDuringCommit} />;
++  try {
++    await act(async () => { root.render(render()); });
++    await act(async () => { await new Promise<void>(resolve => schedule(resolve, 0)); });
++    const rail = [...container.querySelectorAll<HTMLButtonElement>(".combos-workspace-rail-row")]
++      .find(row => row.querySelector(".combos-workspace-rail-name")?.textContent === "combo/alpha");
++    expect(rail).toBeDefined();
++    await act(async () => { rail!.click(); });
++    await act(async () => { await new Promise<void>(resolve => schedule(resolve, 0)); });
++    const alias = container.querySelector<HTMLInputElement>("#cwi-edit-alias")!;
++    await act(async () => {
++      Object.getOwnPropertyDescriptor(testWindow.HTMLInputElement.prototype, "value")!.set!.call(alias, "kept-draft");
++      alias.dispatchEvent(new testWindow.Event("input", { bubbles: true }));
++    });
++    expect(container.querySelector<HTMLButtonElement>("#cwi-edit-save")!.disabled).toBe(true);
++    expect(expire).toBeDefined();
++    if (wake === "visible") {
++      Object.defineProperty(testWindow.document, "visibilityState", { configurable: true, value: "hidden" });
++      await act(async () => { testWindow.document.dispatchEvent(new testWindow.Event("visibilitychange")); });
++    } else if (wake === "active" || wake === "commit-boundary") {
++      await act(async () => { root.render(render(false)); });
++    }
++    now = startedAt + 123_456 - (wake === "commit-boundary" ? 1 : 0);
++    await act(async () => {
++      if (wake === "timer") expire!();
++      else if (wake === "visible") {
++        Object.defineProperty(testWindow.document, "visibilityState", { configurable: true, value: "visible" });
++        testWindow.document.dispatchEvent(new testWindow.Event("visibilitychange"));
++      } else root.render(render(true, wake === "commit-boundary"));
++    });
++    if (wake === "commit-boundary") {
++      await act(async () => { await new Promise<void>(resolve => schedule(resolve, 0)); });
++    }
++    expect(container.querySelector<HTMLInputElement>("#cwi-edit-alias")!.value).toBe("kept-draft");
++    expect(container.querySelector<HTMLButtonElement>("#cwi-edit-save")!.disabled).toBe(false);
++    if (wake === "timer") expect(quotaFetches).toBe(1);
++  } finally {
++    await act(async () => { root.unmount(); });
++    container.remove();
++    scheduleSpy.mockRestore();
++    cancelSpy.mockRestore();
++    clock.mockRestore();
++  }
++  expect(expiryTimers.size).toBe(0);
++});
+diff --git a/src/providers/quota-routing-cache.ts b/src/providers/quota-routing-cache.ts
+index 1e45d60065..3acaf1be50 100644
+--- a/src/providers/quota-routing-cache.ts
++++ b/src/providers/quota-routing-cache.ts
+@@ -3,6 +3,7 @@ import type { OcxProviderConfig } from "../types";
+ import type { ProviderQuota, ProviderQuotaReport } from "./quota";
+ import { providerUsesKeyAuthOverride, resolveProviderApiKey } from "./key-store";
+ import { getProviderRegistryEntry } from "./registry";
++import { PROVIDER_QUOTA_MAX_AGE_MS } from "./quota-types";
+
+ export interface ProviderQuotaRoutingEvidence {
+   quota: ProviderQuota;
+@@ -54,7 +55,7 @@ export function replaceCachedProviderQuotas(
+ export function getCachedProviderQuota(
+   provider: string,
+   now: number,
+-  maxAgeMs = 30 * 60_000,
++  maxAgeMs = PROVIDER_QUOTA_MAX_AGE_MS,
+ ): ProviderQuota | null {
+   const quota = quotaCache.get(provider)?.quota;
+   if (!quota) return null;
+@@ -67,7 +68,7 @@ export function getCachedProviderRoutingQuota(
+   name: string,
+   provider: OcxProviderConfig | undefined,
+   now: number,
+-  maxAgeMs = 30 * 60_000,
++  maxAgeMs = PROVIDER_QUOTA_MAX_AGE_MS,
+ ): ProviderQuota | null {
+   if (!provider || provider.disabled === true || (provider.authMode ?? "key") !== "key") return null;
+   // An active-key report cannot speak for the other keys the dispatcher may select.
+diff --git a/src/providers/quota-types.ts b/src/providers/quota-types.ts
+index 873eb30221..e0bdf9cb4f 100644
+--- a/src/providers/quota-types.ts
++++ b/src/providers/quota-types.ts
+@@ -8,6 +8,13 @@
+  * blocks any later attempt to load one side without the other.
+  */
+
++export const PROVIDER_QUOTA_MAX_AGE_MS = 30 * 60_000;
++
++/** Management-only eligibility evidence; private credential binding never leaves the server. */
++export type ProviderRoutingQuota =
++  | { state: "unknown" }
++  | { state: "available" | "exhausted"; updatedAt: number; validUntil: number };
++
+ export interface ProviderQuotaWindow {
+   label: string;
+   percent: number;
+diff --git a/src/providers/quota.ts b/src/providers/quota.ts
+index ab23070bea..f6d96c5a35 100644
+--- a/src/providers/quota.ts
++++ b/src/providers/quota.ts
+@@ -54,6 +54,7 @@ import type {
+   ProviderQuota,
+   ProviderQuotaCreditsUsd,
+   ProviderQuotaWindow,
++  ProviderRoutingQuota,
+ } from "./quota-types";
+ import {
+   clearKiroAccountUsageState,
+@@ -139,6 +140,8 @@ export interface ProviderQuotaReport {
+   source: string;
+   quota: ProviderQuota;
+   updatedAt: number;
++  /** Added by the management response projection, never stored on a cached report. */
++  routingQuota?: ProviderRoutingQuota;
+   reverseEngineered?: boolean;
+   /**
+    * The row was OBSERVED in-band on a streaming turn rather than probed.
+diff --git a/src/server/management/provider-routes.ts b/src/server/management/provider-routes.ts
+index 1439d7899c..847b240994 100644
+--- a/src/server/management/provider-routes.ts
++++ b/src/server/management/provider-routes.ts
+@@ -57,6 +57,9 @@ import {
+ import { extractGoogleAiStudioModelItems } from "../../providers/google-ai-studio-model-discovery";
+ import { routedSlug, slugEquals } from "../../providers/slug-codec";
+ import { clearAccountQuotaCache, clearProviderQuotaCache, fetchProviderQuotaReports } from "../../providers/quota";
++import { getCachedProviderRoutingQuota } from "../../providers/quota-routing-cache";
++import { PROVIDER_QUOTA_MAX_AGE_MS, type ProviderRoutingQuota } from "../../providers/quota-types";
++import { cachedProviderQuotaIsExhausted } from "../../combos/resolve";
+ import { clearKeyCooldowns } from "../../providers/key-failover";
+ import { providerRequestPacingStatus } from "../../providers/request-pacing";
+ import { CODEX_FORWARD_BASE_URL, isCanonicalOpenAiForwardProvider } from "../../providers/openai-tiers";
+@@ -689,12 +692,54 @@ function canonicalOpenAiBudgetPatchError(
+     ?? providerEmptyToolOutputConfigError("openai", applied.next);
+ }
+
++function providerRoutingQuota(config: OcxConfig, name: string, now: number): ProviderRoutingQuota {
++  const provider = hasOwnProvider(config.providers, name) ? config.providers[name] : undefined;
++  const quota = getCachedProviderRoutingQuota(name, provider, now);
++  if (!quota || !Number.isFinite(quota.updatedAt) || quota.updatedAt < 0 || quota.updatedAt > now
++    || now >= quota.updatedAt + PROVIDER_QUOTA_MAX_AGE_MS) return { state: "unknown" };
++
++  // Removing search/MCP windows may leave only a timestamp. That is not inference evidence.
++  const percentages = [quota.fiveHourPercent, quota.weeklyPercent, quota.monthlyPercent,
++    ...(quota.customWindows ?? []).map(window => window.percent)];
++  const hasPercentage = percentages.some(value => typeof value === "number" && Number.isFinite(value) && value >= 0);
++  const credits = quota.creditsUsd;
++  const hasCredits = credits !== undefined && Number.isFinite(credits.percent)
++    && credits.percent >= 0 && Number.isFinite(credits.remaining);
++  if (!hasPercentage && !hasCredits) return { state: "unknown" };
++
++  const state = cachedProviderQuotaIsExhausted(quota, now) ? "exhausted" : "available";
++  let validUntil = quota.updatedAt + PROVIDER_QUOTA_MAX_AGE_MS;
++  if (state === "exhausted") {
++    const resets = [quota.fiveHourResetAt, quota.weeklyResetAt, quota.monthlyResetAt,
++      ...(quota.customWindows ?? []).map(window => window.resetAt)]
++      .filter((reset): reset is number => typeof reset === "number" && Number.isFinite(reset)
++        && reset > now && reset < validUntil)
++      .sort((left, right) => left - right);
++    // Reuse dispatch's predicate: another exhausted window or USD cap may still block.
++    for (const reset of resets) {
++      if (!cachedProviderQuotaIsExhausted(quota, reset)) {
++        validUntil = reset;
++        break;
++      }
++    }
++  }
++  return { state, updatedAt: quota.updatedAt, validUntil };
++}
++
+ export async function handleProviderRoutes(ctx: ManagementContext): Promise<Response | null> {
+   const { req, url, config, deps, principal, convergeCodexCatalog, syncClaudeAgentDefsBestEffort } = ctx;
+
+   if (url.pathname === "/api/provider-quotas" && req.method === "GET") {
+     const forceRefresh = url.searchParams.get("refresh") === "1" || url.searchParams.get("refresh") === "true";
+-    return jsonResponse(await fetchProviderQuotaReports(config, forceRefresh));
++    const snapshot = await fetchProviderQuotaReports(config, forceRefresh);
++    const now = Date.now();
++    return jsonResponse({
++      ...snapshot,
++      reports: snapshot.reports.map(report => ({
++        ...report,
++        routingQuota: providerRoutingQuota(config, report.provider, now),
++      })),
++    });
+   }
+
+   if (url.pathname === "/api/provider-request-pacing" && req.method === "GET") {
+diff --git a/structure/04_transports-and-sidecars.md b/structure/04_transports-and-sidecars.md
+index ecade01c78..f91195e8bb 100644
+--- a/structure/04_transports-and-sidecars.md
++++ b/structure/04_transports-and-sidecars.md
+@@ -1657,6 +1657,15 @@ credential cannot inherit another key's cap. The same getter controls immediate
+ bounded cooldown waiting and reset-window ordering. This does not override explicit eligibility,
+ target cooldowns, account admission or response-driven retry rules.
+
++The management quota response projects a separate `routingQuota` from this evidence after each
++probe or cached read, using the current provider row. It contains only a state, observation time
++and `validUntil`; the cached display report and private binding remain unchanged. Known states
++expire after 30 minutes or, for exhaustion, when the dispatch predicate first clears at a reset
++boundary. Multiple windows and USD blockers use that same predicate. The Combo editor uses only
++this projection for quota-based Save/Create blocking and treats missing, invalid or expired
++evidence as unknown. It schedules the rendered expiry even when that deadline passes before
++effects run, rechecks on activation/visibility, and refreshes quota alongside Combo data.
++
+ ```text
+ [Decision Log]
+ - 목적과 의도: Keep account-, model- and service-scoped quota from disabling an otherwise usable Combo provider while retaining valid single-key inference caps.
+diff --git a/tests/gui/combo-workspace-data.test.ts b/tests/gui/combo-workspace-data.test.ts
+index e3d340f2f8..e754020636 100644
+--- a/tests/gui/combo-workspace-data.test.ts
++++ b/tests/gui/combo-workspace-data.test.ts
+@@ -13,6 +13,7 @@ import {
+   isValidComboId,
+   parseComboList,
+   providerQuotaStatesFromReports,
++  nextProviderQuotaStateExpiration,
+   toPutBody,
+   updateComboAliasDraft,
+   validateComboDraft,
+@@ -42,6 +43,31 @@ function quotaReport(
+   };
+ }
+
++describe("server-scoped Combo quota", () => {
++  test("display exhaustion without routing authority stays unknown", () => {
++    expect(providerQuotaStatesFromReports([
++      quotaReport("oauth", { fiveHourPercent: 100 }),
++      quotaReport("search", { customWindows: [{ label: "Search", percent: 100 }] }),
++    ], QUOTA_NOW)).toEqual({ oauth: "unknown", search: "unknown" });
++  });
++
++  test("uses current server routing state instead of display windows", () => {
++    expect(providerQuotaStatesFromReports([
++      quotaReport("search", { customWindows: [{ label: "Search", percent: 100 }] }, {
++        routingQuota: { state: "available", updatedAt: QUOTA_NOW, validUntil: QUOTA_NOW + 60_000 },
++      }),
++    ], QUOTA_NOW)).toEqual({ search: "available" });
++  });
++
++  test("expires routing authority at its reset boundary", () => {
++    expect(providerQuotaStatesFromReports([
++      quotaReport("spent", { fiveHourPercent: 100 }, {
++        routingQuota: { state: "exhausted", updatedAt: QUOTA_NOW - 100, validUntil: QUOTA_NOW },
++      }),
++    ], QUOTA_NOW)).toEqual({ spent: "unknown" });
++  });
++});
++
+ function combo(overrides: Partial<ComboItem> = {}): ComboItem {
+   return {
+     id: "free",
+@@ -297,87 +323,57 @@ describe("combo-workspace-data", () => {
+     ]);
+   });
+
+-  test("derives exhausted state from USD, percentage, and custom-window evidence", () => {
++  test("accepts known routing states independently of display data", () => {
+     expect(providerQuotaStatesFromReports([
+-      quotaReport("usd", {
+-        creditsUsd: { used: 10, limit: 10, remaining: 0, percent: 100 },
++      quotaReport("  keyed  ", { fiveHourPercent: 0 }, {
++        routingQuota: { state: "exhausted", updatedAt: QUOTA_NOW, validUntil: QUOTA_NOW + 60_000 },
+       }),
+-      quotaReport("percent", { fiveHourPercent: 100 }),
+-      quotaReport("custom", { customWindows: [{ label: "Daily", percent: 101 }] }),
+-    ], QUOTA_NOW)).toEqual({
+-      usd: "exhausted",
+-      percent: "exhausted",
+-      custom: "exhausted",
+-    });
+-  });
+-
+-  test("keeps unlimited credits available and stale or malformed evidence unknown", () => {
+-    expect(providerQuotaStatesFromReports([
+-      quotaReport("unlimited", {
+-        creditsUsd: { used: 0, limit: 0, remaining: 0, percent: 0, unlimited: true },
++      quotaReport("unlimited", { creditsUsd: { remaining: 0, unlimited: true } }, {
++        routingQuota: { state: "available", updatedAt: QUOTA_NOW, validUntil: QUOTA_NOW + 60_000 },
+       }),
+-      quotaReport("stale", { weeklyPercent: 100 }, { updatedAt: QUOTA_NOW - 30 * 60_000 }),
+-      quotaReport("malformed", { fiveHourPercent: "100" }),
+-      quotaReport("missing", {}),
+-    ], QUOTA_NOW)).toEqual({
+-      unlimited: "available",
+-      stale: "unknown",
+-      malformed: "unknown",
+-      missing: "unknown",
+-    });
++    ], QUOTA_NOW)).toEqual({ keyed: "exhausted", unlimited: "available" });
++  });
++
++  test("rejects malformed, future, stale and overlong routing lifetimes", () => {
++    const fresh = { state: "exhausted", updatedAt: QUOTA_NOW, validUntil: QUOTA_NOW + 1000 };
++    const bad = [
++      undefined, null, [], { ...fresh, state: "maybe" },
++      { ...fresh, updatedAt: "100" }, { ...fresh, updatedAt: NaN },
++      { ...fresh, updatedAt: -1 }, { ...fresh, updatedAt: QUOTA_NOW + 1 },
++      { ...fresh, updatedAt: QUOTA_NOW - 30 * 60_000 },
++      { ...fresh, validUntil: undefined }, { ...fresh, validUntil: Infinity },
++      { ...fresh, validUntil: QUOTA_NOW }, { ...fresh, validUntil: QUOTA_NOW + 30 * 60_000 + 1 },
++    ];
++    for (const routingQuota of bad) {
++      expect(providerQuotaStatesFromReports([
++        quotaReport("keyed", { weeklyPercent: 100 }, { routingQuota }),
++      ], QUOTA_NOW)).toEqual({ keyed: "unknown" });
++    }
+   });
+
+-  test("trims provider ids and rejects incomplete aggregate quota evidence", () => {
++  test("complete display aggregates cannot authorize a provider-wide block", () => {
+     expect(providerQuotaStatesFromReports([
+-      quotaReport("  openai  ", { weeklyPercent: 75 }),
+       quotaReport("pool", { weeklyPercent: 100 }, {
+         aggregation: {
+-          kind: "capacity-weighted-v1",
+-          scope: "routable-known",
+-          presentation: "aggregate",
+-          incomplete: true,
+-          excludedAccounts: 1,
+-          unknownPlanAccounts: 0,
++          kind: "capacity-weighted-v1", scope: "routable-known", presentation: "aggregate",
++          incomplete: false, includedAccounts: 2, excludedAccounts: 0, unknownPlanAccounts: 0,
++          missingQuotaAccounts: 0, pausedAccounts: 0, reauthAccounts: 0, staleQuotaAccounts: 0,
+           partialWindowAccounts: 0,
++          weekly: { usedPercent: 100, includedAccounts: 2, excludedAccounts: 0, incomplete: false, updatedAt: QUOTA_NOW },
+         },
+       }),
+-      quotaReport("malformed-pool", { weeklyPercent: 100 }, {
+-        aggregation: {
+-          kind: "capacity-weighted-v1",
+-          scope: "routable-known",
+-          presentation: "aggregate",
+-          incomplete: false,
+-        },
+-      }),
+-      quotaReport("complete-pool", { weeklyPercent: 100 }, {
+-        aggregation: {
+-          kind: "capacity-weighted-v1",
+-          scope: "routable-known",
+-          presentation: "aggregate",
+-          incomplete: false,
+-          includedAccounts: 2,
+-          excludedAccounts: 0,
+-          unknownPlanAccounts: 0,
+-          missingQuotaAccounts: 0,
+-          pausedAccounts: 0,
+-          reauthAccounts: 0,
+-          staleQuotaAccounts: 0,
+-          partialWindowAccounts: 0,
+-          weekly: {
+-            usedPercent: 100,
+-            includedAccounts: 2,
+-            excludedAccounts: 0,
+-            incomplete: false,
+-            updatedAt: QUOTA_NOW,
+-          },
+-        },
+-      }),
+-    ], QUOTA_NOW)).toEqual({
+-      openai: "available",
+-      pool: "unknown",
+-      "malformed-pool": "unknown",
+-      "complete-pool": "exhausted",
+-    });
++    ], QUOTA_NOW)).toEqual({ pool: "unknown" });
++  });
++
++  test("conflicting duplicate rows stay unknown and the next valid expiry is selected", () => {
++    const rows = [
++      quotaReport("keyed", {}, { routingQuota: { state: "available", updatedAt: QUOTA_NOW, validUntil: QUOTA_NOW + 5000 } }),
++      quotaReport("keyed", {}, { routingQuota: { state: "exhausted", updatedAt: QUOTA_NOW, validUntil: QUOTA_NOW + 1000 } }),
++      quotaReport("bad", {}, { routingQuota: { state: "exhausted", updatedAt: QUOTA_NOW, validUntil: QUOTA_NOW - 1 } }),
++    ];
++    expect(providerQuotaStatesFromReports(rows, QUOTA_NOW)).toEqual({ keyed: "unknown", bad: "unknown" });
++    expect(nextProviderQuotaStateExpiration(rows, QUOTA_NOW)).toBe(QUOTA_NOW + 1000);
++    expect(nextProviderQuotaStateExpiration(rows, QUOTA_NOW + 5000)).toBeUndefined();
+   });
+
+   test("combo quota excludes disabled targets and disables only when every usable target is exhausted", () => {
+diff --git a/tests/server/management-provider-validation.test.ts b/tests/server/management-provider-validation.test.ts
+index 09bfb1e67c..949791f2d6 100644
+--- a/tests/server/management-provider-validation.test.ts
++++ b/tests/server/management-provider-validation.test.ts
+@@ -48,6 +48,8 @@ import { getAccountSet, saveCredential } from "../../src/oauth/store";
+ import { fastPolicyForModel } from "../../src/providers/service-tier";
+ import { resolveWireProtocolOverride } from "../../src/server/adapter-resolve";
+ import { removeTreeWithRetry } from "../helpers/remove-tree";
++import { clearProviderQuotaCache, fetchProviderQuotaReports, setProviderQuotaBeforePublishForTests } from "../../src/providers/quota";
++import { setCachedProviderQuotaForTests } from "../../src/providers/quota-routing-cache";
+
+ // Full-suite Windows load: startServer + multi-step provider PATCH/GET flows exceed the
+ // default 5s per-test budget (same flake class as 810fa115 / claude-management-api).
+@@ -136,6 +138,153 @@ afterEach(() => {
+   if (existsSync(TEST_DIR)) removeTreeWithRetry(TEST_DIR);
+ });
+
++describe("provider quota routing state", () => {
++  function quotaConfig(name = "openrouter", baseUrl = "https://openrouter.ai/api/v1"): OcxConfig {
++    return { port: 10100, defaultProvider: name, providers: { [name]: {
++      adapter: "openai-chat", authMode: "key", baseUrl, apiKey: "synthetic-probed-key",
++    } } };
++  }
++
++  async function readQuota(cfg: OcxConfig, force = false) {
++    const url = new URL(`http://localhost/api/provider-quotas${force ? "?refresh=1" : ""}`);
++    const response = await handleManagementAPI(new Request(url), url, cfg);
++    expect(response?.status).toBe(200);
++    return response!.json();
++  }
++
++  beforeEach(() => {
++    mkdirSync(TEST_DIR, { recursive: true });
++    process.env.OPENCODEX_HOME = TEST_DIR;
++    clearProviderQuotaCache();
++    setProviderQuotaBeforePublishForTests(null);
++  });
++
++  afterEach(() => {
++    clearProviderQuotaCache();
++    setProviderQuotaBeforePublishForTests(null);
++  });
++
++  test("projects bound inference state without mutating display reports", async () => {
++    const cfg: OcxConfig = {
++      port: 10100,
++      defaultProvider: "openrouter",
++      providers: {
++        openrouter: {
++          adapter: "openai-chat", authMode: "key",
++          baseUrl: "https://openrouter.ai/api/v1", apiKey: "synthetic-probed-key",
++        },
++      },
++    };
++    globalThis.fetch = (async () => Response.json({ data: { limit: 20, limit_remaining: 0 } })) as typeof fetch;
++    const url = new URL("http://localhost/api/provider-quotas");
++    const response = await handleManagementAPI(new Request(url), url, cfg);
++    expect(response?.status).toBe(200);
++    const dto = await response!.json();
++    const row = dto.reports.find((item: { provider: string }) => item.provider === "openrouter");
++    expect(row.routingQuota).toEqual({
++      state: "exhausted", updatedAt: row.quota.updatedAt,
++      validUntil: row.quota.updatedAt + 30 * 60_000,
++    });
++    const cached = await fetchProviderQuotaReports(cfg, false);
++    expect(cached.reports[0]).not.toHaveProperty("routingQuota");
++    expect(row.quota).toEqual(cached.reports[0]!.quota);
++    expect(JSON.stringify(dto)).not.toContain("synthetic-probed-key");
++    expect(JSON.stringify(dto)).not.toContain("binding");
++  });
++
++  test("single-key capacity recovers on refresh and an uncapped key drops its old cap", async () => {
++    const cfg = quotaConfig();
++    let payload = { limit: 20 as number | null, limit_remaining: 0 };
++    globalThis.fetch = (async () => Response.json({ data: payload })) as typeof fetch;
++    expect((await readQuota(cfg)).reports[0].routingQuota.state).toBe("exhausted");
++    payload = { limit: 20, limit_remaining: 8 };
++    expect((await readQuota(cfg, true)).reports[0].routingQuota.state).toBe("available");
++    payload = { limit: null, limit_remaining: 0 };
++    expect((await readQuota(cfg, true)).reports).toEqual([]);
++  });
++
++  test.each(["authorization", "x-api-key", "x-goog-api-key", "key-pool", "oauth"])(
++    "rechecks current credential scope: %s", async change => {
++      const cfg = quotaConfig();
++      globalThis.fetch = (async () => Response.json({ data: { limit: 20, limit_remaining: 0 } })) as typeof fetch;
++      expect((await readQuota(cfg)).reports[0].routingQuota.state).toBe("exhausted");
++      if (change === "key-pool") cfg.providers.openrouter!.apiKeyPool = [
++        { id: "primary", key: "synthetic-probed-key" },
++        { id: "secondary", key: "other-key" },
++      ];
++      else if (change === "oauth") cfg.providers.openrouter!.authMode = "oauth";
++      else cfg.providers.openrouter!.headers = { [change]: "other-credential" };
++      const dto = await readQuota(cfg);
++      expect(dto.reports.every((row: { routingQuota: { state: string } }) => row.routingQuota.state === "unknown")).toBe(true);
++    },
++  );
++
++  test("reads a provider row replaced while the quota probe is awaiting publication", async () => {
++    const cfg = quotaConfig();
++    let replaced = false;
++    globalThis.fetch = (async () => Response.json({ data: { limit: 20, limit_remaining: 0 } })) as typeof fetch;
++    setProviderQuotaBeforePublishForTests(() => {
++      cfg.providers.openrouter = { ...cfg.providers.openrouter!, apiKey: "replacement-key" };
++      replaced = true;
++    });
++    const dto = await readQuota(cfg);
++    expect(replaced).toBe(true);
++    expect(dto.reports.every((row: { routingQuota: { state: string } }) => row.routingQuota.state === "unknown")).toBe(true);
++  });
++
++  test("search-only and MCP-only display windows have no inference authority", async () => {
++    const cfg: OcxConfig = { port: 10100, defaultProvider: "synthetic", providers: {
++      ...quotaConfig("synthetic", "https://api.synthetic.new/v2").providers,
++      ...quotaConfig("zai", "https://api.z.ai/api/coding/paas/v4").providers,
++    } };
++    globalThis.fetch = (async input => String(input).includes("synthetic")
++      ? Response.json({ data: { search: { hourly: 100 } } })
++      : Response.json({ success: true, data: { monthlyMCPUsage: 100 } })) as typeof fetch;
++    const dto = await readQuota(cfg);
++    expect(dto.reports).toHaveLength(2);
++    expect(dto.reports.every((row: { routingQuota: { state: string } }) => row.routingQuota.state === "unknown")).toBe(true);
++    expect(dto.reports.find((row: { provider: string }) => row.provider === "synthetic").quota.customWindows[0].percent).toBe(100);
++    expect(dto.reports.find((row: { provider: string }) => row.provider === "zai").quota.monthlyPercent).toBe(100);
++  });
++
++  test("an exhausted OAuth account report stays display-only", async () => {
++    const cfg = quotaConfig("kimi", "https://api.kimi.com/coding/v1");
++    cfg.providers.kimi!.authMode = "oauth";
++    await saveCredential("kimi", { access: "synthetic-account-access", refresh: "synthetic-account-refresh", expires: Date.now() + 3600_000 });
++    globalThis.fetch = (async () => Response.json({ usage: { limit: "100", used: "100" } })) as typeof fetch;
++    const dto = await readQuota(cfg);
++    expect(dto.reports[0].quota.weeklyPercent).toBe(100);
++    expect(dto.reports[0].routingQuota).toEqual({ state: "unknown" });
++  });
++
++  test("cached responses respect reset boundaries, persistent blockers and evidence expiry", async () => {
++    const cfg = quotaConfig();
++    let probes = 0;
++    globalThis.fetch = (async () => {
++      probes += 1;
++      return Response.json({ data: { limit: 20, limit_remaining: 0 } });
++    }) as typeof fetch;
++    const first = await readQuota(cfg);
++    const now = Date.now();
++    const quota = { updatedAt: now, fiveHourPercent: 100, fiveHourResetAt: now + 10_000,
++      weeklyPercent: 100, weeklyResetAt: now + 20_000 };
++    setCachedProviderQuotaForTests("openrouter", quota);
++    expect((await readQuota(cfg)).reports[0].routingQuota.validUntil).toBe(now + 20_000);
++    setCachedProviderQuotaForTests("openrouter", { ...quota, creditsUsd: { used: 20, limit: 20, remaining: 0, percent: 100 } });
++    expect((await readQuota(cfg)).reports[0].routingQuota.validUntil).toBe(now + 30 * 60_000);
++    setCachedProviderQuotaForTests("openrouter", { updatedAt: now, fiveHourPercent: 100, fiveHourResetAt: now - 1 });
++    expect((await readQuota(cfg)).reports[0].routingQuota.state).toBe("available");
++    setCachedProviderQuotaForTests("openrouter", { updatedAt: now,
++      creditsUsd: { used: 0, limit: 0, remaining: 0, percent: 0, unlimited: true } });
++    expect((await readQuota(cfg)).reports[0].routingQuota.state).toBe("available");
++    setCachedProviderQuotaForTests("openrouter", { ...quota, updatedAt: now - 30 * 60_000 });
++    const stale = await readQuota(cfg);
++    expect(stale.reports[0].routingQuota).toEqual({ state: "unknown" });
++    expect(stale.reports[0].quota).toEqual(first.reports[0].quota);
++    expect(probes).toBe(1);
++  });
++});
++
+ describe("provider management validation", () => {
+   test("provider reload adopts only the validated disk row without rewriting config", async () => {
+     if (existsSync(TEST_DIR)) removeTreeWithRetry(TEST_DIR);
+```
diff --git a/devlog/_plan/260912_combo_carry/030_verification.md b/devlog/_plan/260912_combo_carry/030_verification.md
new file mode 100644
index 0000000000..e13e814d63
--- /dev/null
+++ b/devlog/_plan/260912_combo_carry/030_verification.md
@@ -0,0 +1,15 @@
+# Final verification
+
+Depends on editor. MODIFY PR descriptions with exact source/head, manual chain map, attribution and hosted CI evidence; NEW .tmp/combo-handoff/HANDOFF.md, security review and screenshots. No planned product edits; any hosted failure requires a concrete P amendment before repair.
+
+Before: no same-repository carries, no final cumulative proof. After: bottom runtime PR -> editor child PR with editor-only delta; git merge-base --is-ancestor lower upper exits zero, gh pr view proves head/base, gh run view proves successful final-head hosted CI and run URL. Capture actual rendered Combo editor with synthetic fixture data using an existing runtime or hosted-built artifact (no local build/install). Fresh exhausted target disables Save; unknown or expired permits it. Screenshot file must be durably accessible and included in upper PR body. No screenshot waiver.
+
+Security review checks binding creation, private WeakMap retention, report serialization, key-pool/OAuth exclusions and invalidation against current configuration. Review is distinct from maintainer approval. CI negatives cover changed credentials, destination, auth, headers, key pools, display-only limits, fresh/expired/malformed evidence. All local tests NOT RUN. Record any unmet browser/architect/review gate honestly.
+
+## Audit repair amendment
+
+MODIFY lower-layer `tests/providers/provider-quota.test.ts`: explicit-projection test `exhausted` and `projected` objects each gain `updatedAt: Date.now()`. MODIFY lower-layer `tests/codex-integration/catalog-zero-credit-picker.test.ts`: display and bound report fixtures each gain `label: "Alpha"`. Keep runtime and assertions unchanged. Commit on own lower branch, rebase own editor branch onto the new lower tip, push lower normally and upper with explicit lease plus --no-verify. This preserves editor-only upper delta. Independent runtime security audit PASS; these low fixture contract findings are accepted. Recheck original current heads and final carry bases/head/CI; no merge.
+
+## Check-phase repair from independent editor audit
+
+Accepted Bacon P2: mixed retained/fresh report timestamps can leave fresh exhaustion unknown until an older deadline. MODIFY Combos quota loader to update its observation clock on each successful non-aborted snapshot before publication; preserve expiry/visibility effects. Add deterministic mixed-snapshot refresh regression in existing page-loading-contract test with a retained older row and fresh exhausted target, preserving a dirty alias. Update canonical GUI contract. This is C's observe-fix-recheck loop within the verification cycle, not an unrecorded new phase. No local suite. Re-push and replace final-tip CI evidence.
diff --git a/devlog/_plan/260912_combo_carry/031_exhausted.png b/devlog/_plan/260912_combo_carry/031_exhausted.png
new file mode 100644
index 0000000000..c01bafdad9
Binary files /dev/null and b/devlog/_plan/260912_combo_carry/031_exhausted.png differ
diff --git a/devlog/_plan/260912_combo_carry/032_unknown.png b/devlog/_plan/260912_combo_carry/032_unknown.png
new file mode 100644
index 0000000000..e469fd0495
Binary files /dev/null and b/devlog/_plan/260912_combo_carry/032_unknown.png differ
diff --git a/devlog/_plan/260912_combo_carry/033_expired.png b/devlog/_plan/260912_combo_carry/033_expired.png
new file mode 100644
index 0000000000..e469fd0495
Binary files /dev/null and b/devlog/_plan/260912_combo_carry/033_expired.png differ
diff --git a/devlog/_plan/260912_combo_carry/034_render_evidence.md b/devlog/_plan/260912_combo_carry/034_render_evidence.md
new file mode 100644
index 0000000000..3f1885699f
--- /dev/null
+++ b/devlog/_plan/260912_combo_carry/034_render_evidence.md
@@ -0,0 +1,20 @@
+# Combo editor render evidence
+
+Rendered source b3175ae940cdb7855aa4959982b3a357c8a6fd89; GUI tree 39d746c992b2e10fc4c281169db3b83e89d40637.
+Vite development server served this worktree using existing installed dependencies, with its cache
+inside ignored scratch space. No install, build, typecheck or test suite was run. A loopback-only
+synthetic API supplied a single-key OpenRouter target; no real account or user service was used.
+
+Browser viewport 1440x862, DPR2. Opened Models -> Combos -> review-combo and edited the public model
+name to quota-review. DOM inspection read #cwi-edit-save.disabled; screenshots were opened and
+visually inspected. No save request was submitted.
+
+| Input | Observed Save disabled | Image |
+| --- | --- | --- |
+| Fresh server-confirmed exhausted routingQuota | true | [Exhausted](031_exhausted.png) |
+| routingQuota state unknown with exhausted display quota | false | [Unknown](032_unknown.png) |
+| Exhausted routingQuota with past validUntil | false | [Expired](033_expired.png) |
+
+The initial fixture omitted the unrelated aliases defaults and caused a fixture rendering error;
+the fixture was corrected to the API shape before these captures. These are rendered client
+observations with synthetic API responses, not server integration or hosted CI proof.
diff --git a/devlog/_plan/260912_combo_carry/040_pnpm_ci_repair.md b/devlog/_plan/260912_combo_carry/040_pnpm_ci_repair.md
new file mode 100644
index 0000000000..2c5fec8f33
--- /dev/null
+++ b/devlog/_plan/260912_combo_carry/040_pnpm_ci_repair.md
@@ -0,0 +1,27 @@
+# Native-platform pnpm shim regression fixtures
+
+The final all-lane run found two pnpm shim tests failing on Windows. Both request Linux shim
+semantics against Windows filesystem metadata. The tested source and fixture blobs are identical
+at the Combo base, failing tip and current dev; this is source evidence of pre-existing code, not
+an executed baseline reproduction. Hosted run34674363301 job103503916566 contains the failure.
+
+Scope: MODIFY tests/update/update-pnpm.test.ts only, plus this record. Production resolver,
+POSIX executable-bit guard, declaration file and update/job.ts remain unchanged. Local suites,
+build/typecheck/install remain NOT RUN; hosted CI observes the repair. No workflow changes.
+
+NEW local fixture helper emits actual-host launchers: POSIX ocx/opencodex scripts with executable
+permissions; Windows cmd and PowerShell files for both commands. MODIFY the active-target and
+alias cases to use the helper and verifier's real host default. The stale-target case replaces
+both forms of only opencodex on Windows, preserving rejection coverage for both command names.
+The two previously failing cases continue to run on every platform.
+
+NEW separate POSIX permission case: native valid target passes, removing one shim's execute bits
+rejects that command, restoring permissions passes. This new filesystem-specific case runs on
+POSIX only; NTFS cannot provide the claimed mode-bit contract. This is not a skip of either
+failing test and does not weaken the production permission predicate.
+
+Preserve the existing explicit Windows cmd/PowerShell case. Reject the earlier proposed stat
+injection: host-native fixtures preserve coverage without changing production APIs. Use a new
+owned dev repair PR, independent read-only review, --no-verify push and repaired cumulative tip
+hosted CI. Original Combo all-lane FAIL remains recorded. Windows shard3's separate devin CLI
+discovery failure is handed to the parent for its owner; this pnpm change does not claim to fix it.
diff --git a/devlog/_plan/260912_combo_carry/050_active_reactivation_repair.md b/devlog/_plan/260912_combo_carry/050_active_reactivation_repair.md
new file mode 100644
index 0000000000..d6049fe85b
--- /dev/null
+++ b/devlog/_plan/260912_combo_carry/050_active_reactivation_repair.md
@@ -0,0 +1,9 @@
+# Deterministic Combo reactivation expiry verification
+
+Hosted run 34674763850, job 103503977506 failed the active reactivation case because Save remained disabled. The test did not explicitly execute the activation effect's zero-delay callback.
+
+The fixture now captures cancellable immediate timers only during active and commit-boundary scenarios, commits inactive/active state synchronously to preserve the cached quota snapshot, requires one new callback and executes it inside act. The old expiry timer must be cancelled. Dirty alias preservation, initial disabled state, final enabled state, timer/visibility scenarios and cleanup assertions remain. Subsequent fetches stay unresolved so a new server response cannot satisfy the assertion.
+
+Independent source review found no blocker and traced the callback to the active-dependent effect in Combos.tsx. This covers reactivation while the resource cache survives; it does not claim coverage after cache eviction.
+
+Local tests, build, typecheck and installation: NOT RUN by maintainer instruction. git diff --check passes. Hosted CI at the published final head remains required before merge.
diff --git a/devlog/_plan/260912_grok_reset_coupon_gui/000_plan.md b/devlog/_plan/260912_grok_reset_coupon_gui/000_plan.md
new file mode 100644
index 0000000000..e300fc35c0
--- /dev/null
+++ b/devlog/_plan/260912_grok_reset_coupon_gui/000_plan.md
@@ -0,0 +1,195 @@
+# Grok reset coupons — dashboard surface
+
+## Reader summary
+
+PR #4306 gave opencodex a Grok reset-coupon client, a journaled redemption ledger,
+two management routes, and a CLI verb, but it deliberately left the dashboard out.
+An operator who hits an xAI weekly limit therefore sees the same wall the Codex
+pool showed before its ticket badge existed: the coupon is there, the proxy can
+read and spend it, and nothing in the UI says so. This unit adds that surface — a
+ticket badge per xAI OAuth account row in Providers > Accounts, and a dialog that
+lists each coupon's validity window and redeems the nearest-expiry one. It changes
+nothing on the server: both actions call routes that already shipped.
+
+This document is the post-audit contract. It supersedes its own first draft: the
+architect review (`010`), the architect reflection (`020`), and the independent
+audit (`030`) are folded into the decisions, file map, verifiers and criteria below.
+
+## Loop spec
+
+- **Loop archetype:** satisfy-spec. The contract is fixed by the merged management
+  routes and by the Codex reset-credit surface this mirrors.
+- **Trigger:** user request on 2026-09-12 — "여기서 코덱스 처럼 리셋쿠폰 아이콘도 생기고
+  쓸수 있게해줘", pointing at the xAI Grok Accounts tab.
+- **Goal:** an operator reads remaining Grok coupons and redeems one from the
+  dashboard, and is never told a redemption succeeded when it did not.
+- **Non-goals:** no server change (routes, ledger, gRPC-Web client stay as merged);
+  no auto-redeem; no change to the Codex reset-credit surface; no new dependency;
+  no quota-probe change.
+- **Verifier:** the table below. Each row records the command's exit code at plan
+  time, or "not run yet" where the artifact it observes lands in B, plus whether it
+  observes this unit's files.
+- **Stop condition:** merged into `dev` with exact-head CI green and `dev` ancestry
+  proven.
+- **Memory artifact:** `devlog/_plan/260912_grok_reset_coupon_gui/`, closing into
+  `devlog/_fin/` after the merge.
+- **Expected terminal outcomes:** DONE on merge; BLOCKED if review requires the
+  server change this unit excluded; NEEDS_HUMAN if a second maintainer approval is
+  required and unavailable.
+- **Escalation condition:** main reclaims a delegated slice after two distinct
+  agents fail its packet. Delegation is limited to locale catalogs and docs-site
+  locale text, which have disjoint write sets; moving implementation to a worker
+  would require a P-phase amendment.
+- **Resource bounds:** none set by the user; no token or time budget is claimed.
+
+## Design decisions (post-audit)
+
+**D1 — eager read, bounded, with the cost stated.** Codex reset credits ride the
+quota payload (`gui/src/codex-quota-utils.ts:21`), so its badge count is free. xAI
+quota carries no equivalent, and the request is explicitly for a Codex-style badge
+that shows the number, so lazy-on-open would ship a different feature. The panel
+therefore reads `GET /api/grok/reset-coupons` once per account when the xAI
+Accounts panel mounts. Honest cost: each read is a token refresh plus a live
+gRPC-Web billing RPC with no server cache
+(`src/server/management/grok-coupon-routes.ts:83`), React StrictMode makes that
+**2N** reads for N accounts in development, and a panel remount re-reads because
+this unit adds no TTL cache. The bound is a **three-at-a-time queue inside the
+hook** — implemented, not asserted — plus the fact that only the currently open
+provider's accounts are in the read set. Folding the count into the xAI quota probe
+is the recorded follow-up.
+
+**D2 — roster epoch and per-account cancel tokens are separate.** A single scalar
+generation cannot serve both: bumping it for one row's retry silently discards
+every sibling read and strands those badges on the placeholder. The scalar stays
+the roster epoch, bumped only by the effect and its cleanup; each in-flight read
+additionally carries a per-account token, so one row's refresh or redemption never
+cancels another row's read.
+
+**D3 — redemption truth comes from `code`, not from HTTP 200.** The ledger settles
+failures terminally (`src/grok/reset-coupon-ledger.ts:133`) and the route replays a
+settled record as HTTP 200 with `replayed: true` and the original code
+(`src/server/management/grok-coupon-routes.ts:174`). A client that reads only
+`replayed` announces a failed redemption as a completed reset. The hook therefore
+returns the settled `code`; only `redeemed` is success, every other code routes
+through the failure table. 409 clears the held operation id, `capacity` gets its
+own retryable message, and no failure message claims a coupon was not consumed
+unless that is known — `redeem_failed` can follow an upstream call that already
+went out.
+
+**D4 — the operation id is client-minted or the request is refused.** The
+idempotency the journal offers is only reachable when the client holds the id
+across attempts. If `crypto` can produce neither `randomUUID` nor
+`getRandomValues`, the dialog refuses to redeem and says so, instead of posting
+without an id and letting the server mint a fresh one per attempt.
+
+**D5 — an aborted redemption is an unknown outcome, and the dialog stops posting.**
+The 30 s bound can abort while the server is still calling RedeemReset against a
+record that is still `open`, and an `open` record re-executes on the next attempt
+(`src/grok/reset-coupon-ledger.ts:87`). A second POST therefore spends a second
+coupon whether it carries a new id or the same one. After an abort the dialog
+issues **no further consume request at all**: it holds the operation id, enters an
+explicit unknown state, and offers exactly one action, re-reading the account. If
+the coupon has disappeared it reports the coupon as consumed; if it is still listed
+the state stays unresolved and the copy says so, pointing at a later re-read rather
+than at a retry button. A new confirmation cannot be started while an unknown
+outcome is outstanding.
+
+**D6 — one reauth predicate, and the OAuth surface gate is local.** The read set
+and the badge use the same predicate, built from the same health state the row
+renders (`showReauth`), so no row is fetched and then hidden. The enabling
+condition names the OAuth surface directly rather than relying on the roster loader
+three files away to leave `accounts` empty for key-auth xAI.
+
+**D7 — no new CSS.** Badge and dialog reuse `badge-clickable`, `credit-list`,
+`credit-item`, `modal-overlay`, `modal-card` (`gui/src/styles.css:1065`). The
+loading placeholder keeps the Codex pattern of an `aria-hidden` slot carrying a
+literal `0` (`gui/src/components/codex-account-pool-helpers.tsx:34`), which is why
+criterion 4 below is scoped to visible copy rather than to every glyph.
+
+## File change map
+
+| File | Change |
+| --- | --- |
+| `gui/src/hooks/useGrokResetCoupons.ts` | new — bounded per-account read queue (D1), roster epoch + per-account tokens (D2), settled-`code` redemption result (D3), abort reported distinctly (D5), NaN validity sorts last |
+| `gui/src/components/provider-workspace/GrokResetCoupons.tsx` | new — badge and dialog; failure table incl. `capacity`; 409 clears the id; unknown-outcome state; unconditional `tokenId`; fail-closed when no id can be minted; `role="alert"` for failures; focus moves to the confirmation |
+| `gui/src/components/provider-workspace/ProviderAuthPanel.tsx` | wire the badge into xAI OAuth rows, host the dialog, single reauth predicate, OAuth-surface gate computed before the hook call |
+| `gui/src/i18n/en.ts` | 36 `grokCoupon.*` keys (source of truth) |
+| `gui/src/i18n/{de,fr,ja,ko,ru,tr,zh,zh-TW}.ts` | the same 36 keys, translated; zh-TW translates `couponNextBadge` rather than joining the keep-English allowlist |
+| `gui/tests/grok-reset-coupons.test.tsx` | new — the activation cases below |
+| `docs-site/src/content/docs/**/reference/management-api.md` | name the dashboard surface beside the coupon routes: English root + `ko`, `ja`, `zh-cn`, `zh-tw`, `fr`, `ru`, `tr` |
+| `structure/providers/xai-grok.md` | record the dashboard surface under the coupon section |
+| `structure/gui-and-management-api.md` | add the coupon routes and their GUI owner to the route/owner table (`structure/manifest.json:299` lists `gui/` under this doc) |
+
+Scope boundary — IN: the files above. OUT: `src/` (server, ledger, CLI), the Codex
+reset-credit surface, `src/lab/`, quota probing, `gui/dist`, and
+`gui/tests/locale-parity.test.ts` (no allowlist edit is needed once zh-TW
+translates the badge word).
+
+## Verifier table
+
+| Command | Exit at plan time | Observes this change? |
+| --- | --- | --- |
+| `cd gui && bun test tests/locale-parity.test.ts` | 1 — `de key count: 2653` vs `2682` | yes: reads every `gui/src/i18n/*.ts` |
+| `cd gui && bun test tests/i18n-locales.test.ts` | 1 — same key-set assertion | yes: compares each catalog to `en` |
+| `cd gui && bun run lint` | 0 | yes: `oxlint .` covers `src/hooks` and `src/components`, including rules-of-hooks |
+| `cd gui && bun run lint:i18n` | 0 | partly: `oxlint src/pages src/components …` sees the new component but **not** `src/hooks` or `src/i18n` (`gui/.oxlintrc.json` ignores `src/i18n/**`) |
+| `cd gui && bun test tests/grok-reset-coupons.test.tsx` | file lands in B | yes: mounts `ProviderAuthPanel` with an xAI item |
+| `cd gui && bun test tests` | not run yet | yes: full GUI suite |
+| `cd gui && bun run build` | not run yet | yes: `tsc -b && vite build` over `gui/src` |
+| `bun run structure:check` | 0 | yes: gates `structure/` doc-map and ownership for `gui/` |
+| `bun run typecheck` and `bun run test` (root) | not run yet | PR-ready gate required by `AGENTS.md` |
+| `rg -l 'reset-coupons' docs-site/src/content/docs` | 0 (16 files today) | human review: no automated gate reads docs-site locale prose |
+
+## Conditional paths and how C triggers them (C-ACTIVATION-GROUNDING-01)
+
+| Path | Trigger in the test | Observable proof |
+| --- | --- | --- |
+| Read failure | GET returns 502 | row renders `data-grok-coupon-badge="error"`; dialog offers retry |
+| Auth failure on read | GET returns 401 `auth_failed` | dialog says sign in again, not "billing unavailable" |
+| Replayed **failure** | consume returns 200 `{"replayed":true,"code":"redeem_failed"}` | failure message in the alert channel; no success claim |
+| Replayed success | consume returns 200 `{"replayed":true,"code":"redeemed"}` | replay message, no second POST |
+| Identity mismatch | consume returns 409 | failure message **and** the held operation id is cleared, proven by the next POST carrying a different id |
+| Ledger capacity | consume returns 503 `capacity` | its own retryable message, distinct from the generic failure |
+| Aborted redemption | consume never settles until the bound aborts | unknown-outcome state, a re-read, no new operation id |
+| Aborted redemption issues no retry | after the abort, the dialog's only control is the re-read | no second POST to `/consume` is recorded by the fetch stub |
+| Read queue bound | five-account roster with GETs held open | at most three `/reset-coupons` requests are in flight at any moment |
+| Sibling reads survive | two accounts; row A retries while row B's read is in flight | row B still resolves to its count |
+| Reauth row | account with `needsReauth` | no badge and no GET for that id |
+
+## Accept criteria
+
+1. An xAI OAuth row shows a ticket badge whose number equals `tokens.length` from
+   `GET /api/grok/reset-coupons?accountId=<id>` for that row.
+2. The dialog lists every coupon with its validity window, nearest expiry first,
+   and an unparsable `validityEnd` sorts last instead of being treated as nearest.
+3. Redeeming posts `{accountId, tokenId, operationId}` with a UUIDv4 id and an
+   always-present `tokenId`; with no id mintable, the dialog refuses instead of
+   posting.
+4. Every grok-specific visible string resolves through a `grokCoupon.*` key present
+   in all nine catalogs; shared `common.*` keys and the Codex-inherited
+   `aria-hidden` placeholder are the only exceptions.
+5. `cd gui && bun test tests`, `bun run lint`, `bun run lint:i18n`, and
+   `bun run build` are green, and `bun run structure:check` passes.
+6. The docs-site coupon rows name the dashboard surface in the English root and
+   every translated locale, verified by reading the eight files.
+7. A replayed redemption whose `code` is not `redeemed` is reported as a failure.
+8. A 409 identity mismatch clears the held operation id.
+9. A 503 `capacity` reports its own retryable message, and no failure message
+   claims a coupon was not consumed unless that is known.
+10. One row's retry or redemption never cancels another row's in-flight read.
+11. An aborted redemption enters the unknown-outcome state, keeps its operation id,
+    re-reads the account, and issues no further consume request.
+12. At most three coupon reads are in flight at once.
+
+## PR gate
+
+`AGENTS.md` requires `bun run typecheck` and `bun run test` before the PR is
+review-ready, the repository PR template in full, and — because this PR is about
+`gui` — **a screenshot of the UI change in the description**
+(`.github/PULL_REQUEST_TEMPLATE.md:8`). The PR targets `dev`.
+
+## Source-of-truth sync (SOT-SYNC-01)
+
+`structure/providers/xai-grok.md` owns the Grok coupon contract and gains the
+dashboard surface. `structure/gui-and-management-api.md` owns `gui/` per
+`structure/manifest.json:299` and gains the coupon routes with their GUI owner.
diff --git a/devlog/_plan/260912_grok_reset_coupon_gui/005_status.md b/devlog/_plan/260912_grok_reset_coupon_gui/005_status.md
new file mode 100644
index 0000000000..470176c606
--- /dev/null
+++ b/devlog/_plan/260912_grok_reset_coupon_gui/005_status.md
@@ -0,0 +1,45 @@
+# Unit status — Grok reset-coupon dashboard surface
+
+## wp1 — in Check
+
+**What shipped.** The xAI account rows in Providers > Accounts carry a ticket badge
+with their remaining coupon count, and the badge opens a dialog that lists validity
+windows and redeems the coupon closest to expiry. Server side is untouched: both
+actions call the routes merged in #4306.
+
+**What the audit changed.** The first implementation would have told a user that a
+failed redemption succeeded — the route replays a settled failure as HTTP 200 with
+`replayed: true` — and would have retried an aborted redemption against a ledger
+record that re-executes, spending a second coupon. Both are fixed; the second is
+fixed by refusing to post again at all. A single generation counter would also have
+let one row's retry strand its siblings' badges; reads now carry per-account tokens.
+
+**Evidence.**
+
+- `gui/tests/grok-reset-coupons.test.tsx` — 9 pass, covering badge counts, the
+  redeem body, replayed failure, 409 id clearing, 503 capacity, the aborted-unknown
+  state with no second POST, sibling-read survival, and the three-in-flight bound.
+- `cd gui && bun test tests` — 1963 pass / 0 fail (pre-rebase tree).
+- Receipt: `.codexclaw/evidence/<session>/test-receipt.json` over
+  `grok-reset-coupons` + `locale-parity` + `i18n-locales` — 23 pass / 0 fail.
+- `bun run lint`, `lint:i18n`, `build`, `structure:check`, root `typecheck` — exit 0.
+- Root `bun run test`: **NOT RUN.** Two local attempts died in a parallel worker with
+  SIGSEGV on `tests/routing/routing-policy-surface-parity.test.ts`, which passes
+  alone (6 pass); the user then instructed no further local suite runs, so exact-head
+  CI on #4330 is the authority.
+- Live: a proxy built from this branch read the real account pool and rendered
+  0 / 0 / 1 badges; the dialog listed the actual coupon expiring 2026-09-13.
+
+**Delivery.** Issue #4329, PR #4330 into `dev`, screenshots on the never-merged
+`codex/pr-assets-grok-coupon-gui` branch.
+
+**Residual, carried not closed.** `src/grok/reset-coupon-ledger.ts:87` returns
+`execute` for a record that is still `open`, so any client that retries a timed-out
+redemption can spend a second coupon. This unit's client never retries, which is a
+mitigation, not a fix. The route-side fix belongs to a follow-up against `src/`.
+
+**What did not improve.** The badge count still costs one billing RPC per account
+per panel mount, with no TTL cache. Folding it into the xAI quota probe would make
+it free, and that remains the recorded follow-up rather than something this unit
+attempted.
+
diff --git a/devlog/_plan/260912_grok_reset_coupon_gui/010_architect_dispositions.md b/devlog/_plan/260912_grok_reset_coupon_gui/010_architect_dispositions.md
new file mode 100644
index 0000000000..008ed71b01
--- /dev/null
+++ b/devlog/_plan/260912_grok_reset_coupon_gui/010_architect_dispositions.md
@@ -0,0 +1,32 @@
+# Architect review dispositions (round 1)
+
+Reviewer: read-only architect subagent, 2026-09-12. Verdict text is reproduced in
+`evidence/architect-round1.md`. Main owns the plan; each decision below is main's
+disposition, not the reviewer's.
+
+| ID | Finding | Disposition |
+| --- | --- | --- |
+| D1 | Eager one-GET-per-account is the most expensive of three read strategies; lazy-on-open matches the Codex detail fetch | **Rebutted with an amendment.** The request is explicitly "코덱스처럼 리셋쿠폰 아이콘도 생기고" — a badge with no number until clicked does not satisfy it, and xAI quota carries no `resetCredits` equivalent to make the count free. Eager stays, bounded: at most three reads in flight, and the read set is only the accounts of the provider whose panel is open. Folding the count into the xAI quota probe is recorded as the follow-up. |
+| D2 | One scalar generation ref serves as both roster epoch and per-request cancel token, so a single-account refresh or redeem silently discards sibling reads and strands their badges | **Folded.** The roster epoch stays a scalar bumped only by the effect and its cleanup; each in-flight read now carries a per-account token, so one row's retry cannot cancel another row's read. |
+| D3a | A retried redemption against a still-`open` journal record executes again, so one confirmation can spend two coupons | **Acknowledged as a backend residual.** The `open` → `execute` path is the server's deliberate resumption branch (`src/grok/reset-coupon-ledger.ts:87`) and this unit does not touch `src/`. The client keeps redemption single-flight and the residual is recorded for a follow-up issue against the route. |
+| D3b | A settled *failure* replays as HTTP 200 with `replayed: true`, and the client reads only that flag, so a failed redemption is announced as a successful one | **Folded — this was the worst defect.** The client now reads `code` out of the 200 body and treats only `redeemed` as success; any other replayed code routes through the failure table. |
+| D3c | 409 identity mismatch never clears the held operation id, so "try again" reproduces the same 409 forever | **Folded.** The id is cleared on 409 and on any failure that makes it unusable. |
+| D3d | 503 capacity arrives as code `capacity`, which has no mapping and falls back to copy claiming nothing was consumed | **Folded.** `capacity` gets its own retryable message, and the generic failure copy no longer asserts that no coupon was consumed, because `redeem_failed` can follow an upstream call that already went out. |
+| D4a | The fetch filter tests `account.needsReauth` while the render guard uses `showReauth`, so a health-flagged row is fetched and never rendered | **Folded.** Both use one predicate built from `accountNeedsReauth`-equivalent health state. |
+| D4b | `grokCouponsEnabled` does not reference `surface`, so API-key xAI is excluded only by accident | **Folded.** The gate now requires the OAuth surface locally. |
+| D5a | Seven locale catalogs are missing all 29 keys; `tests/i18n-locales.test.ts` and `tests/locale-parity.test.ts` fail | **Folded** — already in the file-change map; confirmed failing at plan time (`de key count: 2653` vs `2682`). |
+| D5b | Failure outcome uses `role="status"` where the panel's convention for failures is `role="alert"`; confirmation step does not move focus | **Folded.** Failures announce assertively and the confirmation step takes focus. |
+| D6a | `byExpiry` sorts client-side while the server's no-token default picks upstream order, so `fifoNote` promises the client's rule | **Rebutted as written.** The dialog always sends an explicit `tokenId`, so the server's default ordering never applies to this surface; the promise the copy makes is the one the request enforces. |
+| D6b | The GET's 400/401/502 collapse into one opaque error | **Folded in part.** The entry keeps the response status so the dialog can separate "sign in again" from an upstream billing failure; finer codes stay out of scope. |
+| D6c | docs-site owes an update | **Folded** — already in the file-change map. |
+
+## Amendment to the plan
+
+D1's bound and D2's per-account token change `gui/src/hooks/useGrokResetCoupons.ts`;
+D3b/D3c/D3d and D5b change `gui/src/components/provider-workspace/GrokResetCoupons.tsx`;
+D4a/D4b change the wiring in `ProviderAuthPanel.tsx`. No new files, and the scope
+boundary is unchanged: `src/` stays out.
+
+Two new locale keys follow from the dispositions: `grokCoupon.capacity` and
+`grokCoupon.authExpired`, bringing the key set to 31.
+
diff --git a/devlog/_plan/260912_grok_reset_coupon_gui/020_reflection_gaps.md b/devlog/_plan/260912_grok_reset_coupon_gui/020_reflection_gaps.md
new file mode 100644
index 0000000000..0a21016154
--- /dev/null
+++ b/devlog/_plan/260912_grok_reset_coupon_gui/020_reflection_gaps.md
@@ -0,0 +1,37 @@
+# Architect reflection — remaining gaps and final dispositions
+
+Verdict: **ALIGNED**, with six residual gaps. All six are folded below; the plan's
+file-change map and accept criteria in `000_plan.md` are amended accordingly.
+
+1. **Abort path for redemption (surviving edge of D3a).** After the 30 s bound
+   aborts, the outcome is unknown and the old code left a live "Use coupon"
+   button. Folded: an aborted redemption puts the dialog into an explicit unknown
+   state, re-reads the coupon list, and does not offer a same-id retry. The user
+   sees the refreshed count and decides from it.
+2. **`byExpiry` NaN ordering.** Folded: an unparsable `validityEnd` sorts last
+   instead of collapsing the comparator to `0`, so a malformed timestamp cannot
+   make a confidently wrong coupon the "nearest expiry".
+3. **Conditional `tokenId`.** Folded: the dialog refuses to redeem when it holds
+   no coupon id rather than posting without one and letting the server's
+   upstream-order default apply. This makes the D6a rebuttal an enforced invariant.
+4. **C-activation coverage for the folded defects.** Folded into the verifier
+   contract: the GUI test must cover a replayed *failure* (200 with
+   `code: "redeem_failed"`, `replayed: true`), a 409 identity mismatch clearing the
+   held id, a 503 `capacity`, and a two-account roster where one row's retry must
+   not strand the other row's read.
+5. **Accept criteria did not fail on regression.** Folded: criteria 7-10 below.
+6. **Bookkeeping.** The key set is 31, not 29. No read cache or TTL is specified:
+   a panel remount re-reads, bounded by three concurrent reads and by the fact
+   that only the open provider's accounts are in the read set. That is accepted
+   cost, recorded rather than hidden.
+
+## Amended accept criteria (extends 000_plan.md)
+
+7. A replayed redemption whose `code` is not `redeemed` is reported as a failure,
+   never as a completed reset.
+8. A 409 identity mismatch clears the held operation id so the next attempt is not
+   guaranteed to repeat it.
+9. A 503 `capacity` reports its own retryable message, and no failure message
+   claims a coupon was not consumed unless that is known.
+10. One row's retry or redemption never cancels another row's in-flight read.
+
diff --git a/devlog/_plan/260912_grok_reset_coupon_gui/030_audit_round1.md b/devlog/_plan/260912_grok_reset_coupon_gui/030_audit_round1.md
new file mode 100644
index 0000000000..e0a39e9717
--- /dev/null
+++ b/devlog/_plan/260912_grok_reset_coupon_gui/030_audit_round1.md
@@ -0,0 +1,44 @@
+# Independent audit round 1 — dispositions
+
+Auditor: independent adversarial subagent (xai/grok-4.6), read-only.
+Verdict: **GAPS(8)**. All eight are folded; nothing is rebutted.
+
+| # | Blocker | Disposition |
+| --- | --- | --- |
+| 1 | `000_plan.md` still carried the pre-fold contract (29 keys, scalar cancel, `replayed` as success, "nothing was consumed" copy) while `020` claimed it was amended | **Folded.** `000_plan.md` is rewritten as the post-audit contract: D1-D7, a new file map, a new verifier table, a nine-row activation table, and twelve accept criteria. `010`/`020` remain as the consultation record. |
+| 2 | File map missed `structure/gui-and-management-api.md` (owns `gui/` per `structure/manifest.json:299`), missed that D3b also changes the hook, and under-counted the keys | **Folded.** Both structure docs are in the map, the hook owns the settled-`code` result, and the key set is fixed at 36 including the unknown-outcome copy. zh-TW translates `couponNextBadge` so `locale-parity.test.ts` needs no allowlist edit. |
+| 3 | Criteria were unobservable: criterion 4 was false (the dialog uses `common.*` and a literal `0`), criteria 7-10 lived only in `020`, and the new behaviors had no criteria | **Folded.** Criterion 4 is scoped to grok-specific visible copy with the shared keys and the inherited `aria-hidden` placeholder named as exceptions; criteria 7-12 are in `000_plan.md`. |
+| 4 | Verifier table claimed observation it did not have: `lint:i18n` cannot see `src/hooks` or `src/i18n`, and nothing observed docs-site or structure | **Folded.** The table now records `lint:i18n` as partial, adds `bun run lint`, `bun test tests/i18n-locales.test.ts`, `bun run structure:check`, the root PR-ready gates, and marks docs-site prose as human review rather than a gate. |
+| 5 | "Refuse a same-id retry" after an abort is the double-spend, not a mitigation: minting a new id while RedeemReset may still be executing against an `open` record spends a second coupon | **Folded, and the rule is inverted.** D5 now keeps the same operation id, blocks a new confirmation while the outcome is unknown, and offers only a re-read plus a same-id retry. The backend residual stays recorded, but the client no longer converts it into a second spend. |
+| 6 | The "three in flight" bound existed only in prose, and the StrictMode cost was understated | **Folded.** The bound is a queue inside the hook with its own accept criterion, and D1 states the real cost: 2N reads under StrictMode, no TTL cache, re-read on remount. |
+| 7 | `gui/AGENTS.md` PR-ready requires `bun run lint`; the root template requires a GUI screenshot | **Folded.** Both are in criterion 5 and in the new PR gate section. |
+| 8 | The WIP could post without `operationId` (`newOperationId()` may return `undefined`), which breaks the whole D3 premise | **Folded.** D4 makes the id mandatory: no id, no POST, with user-visible copy. |
+
+Nits accepted: the "every command was run" line is replaced by a per-row exit
+column; the `aria-hidden` `0` placeholder is now named in D7; the `i18n-locales`
+path is corrected to `gui/tests/`; the OAuth-surface gate is required to be
+computed before the hook call. `parseCoupons` rejecting a whole malformed list
+stays as designed — a partially-parsed coupon list is worse than an error badge —
+and is now stated rather than implicit.
+
+
+## Audit round 2 — dispositions
+
+Verdict: **GAPS(2)**, both folded.
+
+1. *Same-id retry after an abort is still a second RedeemReset against an `open`
+   record.* Correct. D5 is inverted again: after an abort the dialog issues no
+   consume request at all. Its only control is a re-read; a coupon that disappears
+   is reported consumed, and a coupon still listed leaves the state unresolved with
+   copy that says so.
+2. *Criterion 12 had no activation.* Folded: the activation table gains a
+   five-account roster with held-open GETs, proving at most three are in flight.
+
+Nit folded: the loop-spec no longer claims every verifier command was run; the
+table's exit column carries the truth.
+
+Residual carried into the PR (not closed by this unit): a redemption whose journal
+record is still `open` re-executes if anything ever retries it. This unit's client
+never retries, so it cannot cause that spend, but the route's `open` -> `execute`
+branch stays as merged and is recorded as the follow-up against `src/`.
+
diff --git a/devlog/_plan/260912_grok_reset_coupon_gui/evidence/architect-round1.md b/devlog/_plan/260912_grok_reset_coupon_gui/evidence/architect-round1.md
new file mode 100644
index 0000000000..e034a1f850
--- /dev/null
+++ b/devlog/_plan/260912_grok_reset_coupon_gui/evidence/architect-round1.md
@@ -0,0 +1,10 @@
+# Architect review round 1 (read-only subagent)
+
+Full verdict retained in the session transcript. Findings carried into
+`010_architect_dispositions.md` as D1-D6 with main dispositions. Headline items:
+
+- D2: one scalar generation ref cancels sibling reads on a single-row refresh.
+- D3b: a settled failure replays as HTTP 200 `replayed:true`; the client announced it as success.
+- D3a: a still-`open` journal record re-executes, so one confirmation can spend two coupons (backend residual).
+- D4a: fetch filter and render guard use different reauth predicates.
+- D5a: seven locale catalogs missing all new keys; parity test fails.
diff --git a/devlog/_plan/260912_grok_reset_coupons/000_plan.md b/devlog/_plan/260912_grok_reset_coupons/000_plan.md
new file mode 100644
index 0000000000..22ba5d65b9
--- /dev/null
+++ b/devlog/_plan/260912_grok_reset_coupons/000_plan.md
@@ -0,0 +1,53 @@
+# Grok reset coupons — roadmap (000)
+
+## Reader summary
+
+Grok's consumer billing now hands out "reset coupons" (Codex-style usage-reset
+credits). This unit teaches opencodex to read them and, only on an explicit
+operator action, redeem one — using the xAI OAuth tokens opencodex already
+stores, with no browser session. Live probes this session proved the upstream
+contract (see [001_survey_seams.md](./001_survey_seams.md)); the implementation
+mirrors the existing Codex reset-credit architecture end to end so operators get
+the same safety shape they already know.
+
+## Loop spec
+
+- **Archetype:** satisfy-spec (feature delivery against a verified upstream contract).
+- **Trigger:** user request this session: "이슈 올리고 pr 하고 머지까지" (file the issue, open the PR, merge) for Grok reset-coupon read + gated redeem.
+- **Goal:** ocx can list a Grok account's remaining reset coupons (count + validity window) and redeem one only through an explicit, idempotent, journaled operator action, surfaced via management API + CLI; delivered as a templated issue + PR to `dev`, merged with exact-head CI evidence.
+- **Non-goals:** no auto-redeem in this unit (opt-in auto-redeem is a follow-up); no GUI surface; no changes to the Codex reset-credit path; no new dependency (hand-rolled gRPC-Web codec, no @bufbuild/protobuf runtime import).
+- **Verifier:** `bun test tests/providers/xai/grok-reset-coupons.test.ts` (targets the new test file directly), `bun run typecheck` (package.json:11 "bun x tsc --noEmit"), `bun run test` (package.json:12 "bun scripts/test.ts" — full tree, reads all domains incl. our layout registrations), `bun run privacy:scan` (package.json "bun scripts/privacy-scan.ts" — scans the tree incl. new files). Live smoke (sanitized) re-proves the read path against the real endpoint.
+- **Stop condition:** all criteria met (goalplan c1–c6) and the PR is merged with exact-head CI + issue closed; report DONE. Missing authority (push/merge refusal) reports BLOCKED.
+- **Memory artifact:** this unit (devlog/_plan/260912_grok_reset_coupons/, moves to _fin at wp4 D); goalplan + ledger under .codexclaw/goalplans/implement-grok-reset-coupon-support-in-opencodex/; evidence under .codexclaw/evidence/.
+- **Expected terminal outcomes:** DONE (all criteria + merged), BLOCKED (missing external authority or upstream contract change), BUDGET_EXHAUSTED (host bounds), NEEDS_HUMAN (upstream schema drift on RedeemReset success shape).
+- **Escalation condition:** upstream rejects the documented RedeemReset request shape on a real redeem → stop, report, ask operator how to proceed (spending a coupon is operator-owned). Main reclaims a lane after two distinct agents fail its packet (DISPATCH-RETIRE-01); pushing a slice to a worker requires a P-phase amendment.
+
+## Resource bounds (HOTL)
+
+Tool scope: local git/gh, repo files in this worktree, spawned read/executor subagents (unlimited parallel dispatch explicitly authorized by the operator this session; model picker left empty = inherit), ocx 10100 + aside lanes. Write scope: this worktree; remote branch push, issue, PR, and merge were explicitly authorized in the same session. Token budget: unset by operator (host default). Wall clock: until DONE/BLOCKED within this session.
+
+## Dependency-ordered phase map
+
+| Phase | Work-phase | Doc | Outcome |
+|---|---|---|---|
+| wp1 | Docs-first roadmap cycle (this cycle) | 000–030 | Roadmap locked at D |
+| wp2 | Core gRPC-Web client + xai account integration | [010_phase1_core_client.md](./010_phase1_core_client.md) | src/grok/grpc-web.ts + src/grok/reset-coupons.ts + src/grok/reset-coupon-ledger.ts + focused tests + layout registration |
+| wp3 | Surfaces: management API + CLI with gated consume | [020_phase2_surfaces.md](./020_phase2_surfaces.md) | GET/POST routes + ocx account grok-reset-coupons with --consume --yes + operation-id idempotency |
+| wp4 | Delivery: docs sync, issue, PR, exact-head CI, merge | [030_phase3_delivery.md](./030_phase3_delivery.md) | docs-site updated, templated issue + PR, merged into dev, issue closed |
+
+## Scope boundary
+
+IN: files named in 010/020/030 only. OUT: src/lab/*, src/router.ts, src/server/lifecycle.ts, src/server/responses/core.ts (lab boundary, tests/lab/core-lab-boundary.test.ts), Codex reset-credit modules, GUI.
+
+## Conditional-path activation (C-ACTIVATION-GROUNDING-01)
+
+| Planned conditional path | Activation scenario at C |
+|---|---|
+| grpc-status non-zero (e.g. 3 "Invalid token_id") | stubbed fetch returns trailer frame status 3; test asserts surfaced message |
+| 401/expired token → one refresh + replay | stubbed fetch 401 then 200; test asserts refresh called once with stored refresh token |
+| Consume without --yes | CLI test asserts refusal before any fetch |
+| Same operationId replay | ledger test: second call with same id returns journaled settlement, fetch called once |
+
+## SoT sync (SOT-SYNC-01)
+
+docs-site reference pages (targets verified by the docsite lane: docs-site/src/content/docs/reference/cli/providers-accounts.md, docs-site/src/content/docs/reference/management-api.md) + structure/ ownership check at wp2 P re-verification; devlog unit promotes to _fin at wp4 D.
diff --git a/devlog/_plan/260912_grok_reset_coupons/001_survey_seams.md b/devlog/_plan/260912_grok_reset_coupons/001_survey_seams.md
new file mode 100644
index 0000000000..179a2563d5
--- /dev/null
+++ b/devlog/_plan/260912_grok_reset_coupons/001_survey_seams.md
@@ -0,0 +1,97 @@
+# Grok Reset Coupons Seam Survey
+
+This document records the architectural survey, upstream API evidence, codebase seams, and system constraints for supporting Grok reset coupons (read and redeem) within OpenCodex.
+
+## 1. Upstream API Evidence
+
+### Endpoints
+- **Endpoint A (Read Remaining Resets):** `POST https://grok.com/prod_mc_billing.ConsumerUiSvc/GetRemainingResets`
+  - Request message: Empty protobuf payload (`0` bytes in data frame).
+  - Response message: Repeated reset token descriptors.
+  - Verification method: Live probe this session via gRPC-Web client against `grok.com`.
+- **Endpoint B (Redeem Reset):** `POST https://grok.com/prod_mc_billing.ConsumerUiSvc/RedeemReset`
+  - Request protobuf schema: Field 1 (tag 1, wire type 2 = length-delimited string): `token_id`.
+  - Verification method: Live probe this session with a synthetic token identifier. Returned HTTP 200 with gRPC trailer `grpc-status: 3` and message `redeem_reset(), Invalid token_id`. Intentionally probing non-existent method names returned `grpc-status: 12` (UNIMPLEMENTED), verifying the method path and service definition.
+
+### Transport & Framing
+- **Protocol:** gRPC-Web over HTTP/2 or HTTP/1.1 with binary protobuf serialization.
+- **Headers:**
+  - `Content-Type: application/grpc-web+proto`
+  - `X-Grpc-Web: 1`
+  - `Accept: application/grpc-web+proto`
+- **Wire Envelope (5-byte header prefix per frame):**
+  - Byte 0 (`flag`): `0x00` for data frames, `0x80` for trailers.
+  - Bytes 1-4 (`length`): 32-bit unsigned big-endian integer denoting frame payload byte count.
+- **Response Structure:**
+  - One or more data frames (`flag: 0x00`) carrying serialized protobuf response bytes.
+  - Exactly one trailer frame (`flag: 0x80`) containing ASCII header/trailer lines (e.g., `grpc-status:0\r\ngrpc-message:\r\n`).
+- **Edge Behavior:**
+  - Plain `application/json` POST requests to the RPC endpoint return HTTP 200 with an empty `application/grpc` body. The upstream endpoint strictly requires valid gRPC-Web 5-byte framing and protobuf wire format.
+  - Verification method: Live probe this session comparing JSON request vs framed binary request.
+
+### Authentication Headers
+- **Verified Header Tuple:**
+  - `Authorization: Bearer <xai OIDC access token>`
+  - `X-XAI-Token-Auth: xai-grok-cli`
+- **Cookie Requirement:** None. No session cookies or browser credentials are required when the bearer token and token-auth header are present.
+- **Verification method:** Live probe this session using refreshed xAI OAuth tokens without cookie headers.
+
+### Response Protobuf Field Mapping
+Hand-decoded from live payload bytes returned by `GetRemainingResets`:
+- **Top-Level Message (`GetRemainingResetsResponse`):**
+  - Field 10 (wire type 2, length-delimited): repeated `ConsumerResetToken`
+- **Nested Message (`ConsumerResetToken`):**
+  - Field 10 (wire type 2, length-delimited string): `tokenId`
+  - Field 20 (wire type 2, length-delimited submessage): `validityStart` (`google.protobuf.Timestamp`)
+    - Subfield 1 (wire type 0, varint): `seconds` (Unix epoch seconds)
+  - Field 30 (wire type 2, length-delimited submessage): `validityEnd` (`google.protobuf.Timestamp`)
+    - Subfield 1 (wire type 0, varint): `seconds` (Unix epoch seconds)
+- **Observed Live Sample:** Active test account returned 1 token with a 31-day validity span between `validityStart` and `validityEnd`.
+- **Verification method:** Live probe this session followed by binary protobuf wire decoding of returned bytes.
+
+---
+
+## 2. Repo Seam Survey
+
+### OAuth Refresh Chain & Account Storage
+- `src/oauth/xai.ts:369` (`refreshXaiToken(refreshToken, signal)`): Refreshes xAI OIDC OAuth tokens against the authorization server with request abort signaling.
+- `src/oauth/index.ts:248-251` (`xai` OAuth provider entry in provider registry): Binds `refresh: refreshXaiToken` into the central OAuth registry map.
+- `src/oauth/index.ts:613` (`getValidAccessSnapshotForAccount(provider, accountId, opts)`): Resolves an active token snapshot, automatically performing refresh with store file locking when expired or expiring.
+- `src/oauth/store.ts:864` (`listAccounts(provider)`): Enumerates stored accounts for provider `xai`, supporting account discovery and status checks.
+- `src/oauth/store.ts:890` (`getAccountCredentialWithStatus`): Retrieves the credential record and token status for a specific account without breaking isolation.
+- `src/oauth/store.ts:923` (`captureOAuthAccountSelection("xai")`): Records the chosen account selection state for persistent CLI and server context.
+
+### Header Constants & Transport Defaults
+- `src/providers/xai-transport.ts:28-56` (`XAI_GROK_COMPATIBILITY`): Defines xAI and Grok compatibility header constants, specifically `tokenAuth` header key `x-xai-token-auth` and value `xai-grok-cli`.
+
+### Grok Domain Logic
+- `src/grok/*.ts`: Core domain modules containing Grok-specific client definitions, error mapping, and billing/quota abstractions.
+
+### Test Layout Registration
+- `tests/providers/xai/grok-*.test.ts`: Unit and integration test suites for Grok-specific functionality.
+- `scripts/test-layout/layout.json:694-704`: Explicit layout mapping registering Grok test files to their runner tiers.
+- `tests/fixtures/test-layout-expected.json`: Snapshot expectation fixture for repository test layout verification that must match `layout.json`.
+
+### Management Route Table & Lazy Dispatch
+- `src/server/management/route-registry.ts:94`: Codex reset-credits GET endpoint registration (`/api/codex-auth/reset-credits`).
+- `src/server/management/route-registry.ts:102`: Codex reset-credits consume POST endpoint registration (`/api/codex-auth/reset-credits/consume`).
+- `src/server/management/route-registry.ts:127-140`: Existing `/api/grok` management route definitions.
+- `src/server/management-api.ts:140-144` (`handleQuotaResetRoutesOnDemand`): Lazy dynamic import pattern — namespace guard at 141, dynamic `import()` at 142, dispatch-chain entry at 243 — loading quota/reset route handlers only when matching endpoints are invoked.
+- `src/server/management-api.ts:383`: The `/api/codex-auth/` prefix dispatch.
+
+### Codex Reset-Credit Mirror Pattern
+- `src/codex/reset-credit-operation-ledger.ts:1191` (`openManualResetCreditOperation` definition): Journaled reset credit operation handler with atomicity, recovery records, and read/consume execution. `src/codex/auth-api.ts:2605-2647` is the consume-route call site.
+- `src/codex/reset-credit-recovery.ts:40` (`isCodexResetCreditOperationId`): Operation ID syntax and format validation guard.
+- `src/cli/account-auth.ts:275-302` (`resetCredits()`): CLI execution handler enforcing that `--consume` mandates explicit `--yes` confirmation and validates `--operation-id` via the recovery guard.
+- `src/cli/account.ts:62,358-360`: Account command parser registering the reset-credits subcommand and argument options.
+- `src/cli/registry.ts:224,236`: CLI router and dispatcher table wiring the reset-credits handler.
+
+---
+
+## 3. Constraints & Risks
+
+- **Lab Boundary Invariant:** Core router and server lifecycle modules (`src/router.ts`, `src/server/lifecycle.ts`, and `src/server/responses/core.ts`) must never import from `src/lab`. Any new reset coupon abstraction must remain in production domain modules (`src/grok/`, `src/oauth/`, `src/server/management/`) without leaking experimental lab dependencies.
+- **Privacy & Token Leak Prevention:** Authorization tokens, refresh tokens, and raw Bearer headers must never be written to logs, serialized to persistent console output, or returned in unmasked debug messages.
+- **Bun-Native Runtime Invariants:** The codebase runs on the Bun runtime. Implementations must use standard Web APIs (`fetch`, `Uint8Array`, `DataView`, `ReadableStream`) or Bun-native primitives; Node-only modules (such as `http2`, `tls`, `stream/promises` specifics) must not be introduced.
+- **Branch and Contribution Policy:** All changes and pull requests must target the `dev` branch.
+- **Transport Strictness:** Upstream `grok.com` rejects non-framed JSON payloads with empty responses. The gRPC-Web encoder/decoder must handle 5-byte frame prefixes, varint parsing, and trailer parsing robustly without external heavy runtime dependencies.
diff --git a/devlog/_plan/260912_grok_reset_coupons/005_status.md b/devlog/_plan/260912_grok_reset_coupons/005_status.md
new file mode 100644
index 0000000000..146b4785a5
--- /dev/null
+++ b/devlog/_plan/260912_grok_reset_coupons/005_status.md
@@ -0,0 +1,21 @@
+# Unit status — Grok reset coupons
+
+## wp1 (docs-only roadmap cycle) — in Check
+
+- Authored: 000_plan.md (loop-spec, phase map), 001_survey_seams.md (live-probe
+  research), 010_phase1_core_client.md, 020_phase2_surfaces.md,
+  030_phase3_delivery.md (diff-level PRDs).
+- Authoring: 3 parallel Aside doc lanes + main integration.
+- Audit: spawned reviewer adversarial audit round 1 = GAPS(15) — folded
+  (API unification getGrokRemainingResets/redeemGrokResetCoupon + Codex-mirror
+  ledger kinds execute|replay|identity-mismatch|capacity; field fixes
+  accountId/accessToken; real verifier commands; citation corrections; locale
+  sync + structure anchor). Round 2 = sole blocker evidenced stale;
+  confirmation round = VERDICT: PASS (residual cosmetic nits non-blocking).
+- Architect reflection (same Aside session): 4 gaps — 3 folded, 1 rebutted with
+  structure/providers/xai-grok.md:1,3 evidence.
+- Check gates: unit consistency grep CLEAN; bun test
+  tests/test-layout.test.ts tests/test-layout-tooling.test.ts = 17 pass / 0 fail.
+- Next: wp2 consumes 010 (core client), wp3 consumes 020 (surfaces), wp4
+  consumes 030 (delivery). Implementation begins next cycle per
+  LOOP-DOCS-FIRST-01.
diff --git a/devlog/_plan/260912_grok_reset_coupons/010_phase1_core_client.md b/devlog/_plan/260912_grok_reset_coupons/010_phase1_core_client.md
new file mode 100644
index 0000000000..2f71a2535b
--- /dev/null
+++ b/devlog/_plan/260912_grok_reset_coupons/010_phase1_core_client.md
@@ -0,0 +1,1175 @@
+# 010 Phase 1 Core Client: Grok Reset Coupons
+
+This document specifies the exact diff-level implementation PRD for Phase 1 of Grok Reset Coupons support in OpenCodex.
+
+---
+
+## 1. Architectural Context and Decisions
+
+### 1.1 Upstream Verification Facts
+- **Endpoint A (Read):** `POST https://grok.com/prod_mc_billing.ConsumerUiSvc/GetRemainingResets` with empty protobuf message payload (`0` bytes in gRPC-Web data frame).
+- **Endpoint B (Redeem):** `POST https://grok.com/prod_mc_billing.ConsumerUiSvc/RedeemReset` with protobuf message field 1 = `token_id` (wire type 2, length-delimited string). Probing with a synthetic token identifier returns HTTP 200 with trailer `grpc-status: 3` and trailer message `redeem_reset(), Invalid token_id`. Probing invalid method names returns `grpc-status: 12` (UNIMPLEMENTED).
+- **Transport Framing:** gRPC-Web binary framing. Request headers:
+  - `Content-Type: application/grpc-web+proto`
+  - `X-Grpc-Web: 1`
+  - 5-byte envelope prefix per frame: `flag` (1 byte, `0x00` = data, `0x80` = trailer) + `length` (4 bytes, unsigned big-endian 32-bit integer).
+  - Plain `application/json` POST requests return HTTP 200 with an empty `application/grpc` body. Binary gRPC-Web framing is strictly mandatory.
+- **Authentication Headers:**
+  - `Authorization: Bearer <xai OIDC access token>`
+  - `X-XAI-Token-Auth: xai-grok-cli` (key at `src/providers/xai-transport.ts:34`, value at `src/providers/xai-transport.ts:54`, from `XAI_GROK_COMPATIBILITY.headers.tokenAuth`).
+  - No browser cookies or session cookies required.
+- **Protobuf Wire Schema:**
+  - `GetRemainingResetsResponse`:
+    - Field 10 (wire type 2): repeated `ConsumerResetToken`.
+    - Nested `ConsumerResetToken`:
+      - Field 10 (wire type 2): `tokenId` (string).
+      - Field 20 (wire type 2): `validityStart` (`Timestamp` submessage with field 1 varint `seconds`).
+      - Field 30 (wire type 2): `validityEnd` (`Timestamp` submessage with field 1 varint `seconds`).
+  - `RedeemResetRequest`:
+    - Field 1 (wire type 2): `tokenId` (string).
+  - `RedeemResetResponse`:
+    - Empty message or success descriptor framed by gRPC status code `0` in trailers.
+
+### 1.2 Architect Decisions
+- **D1:** Core client modules reside in `src/grok/grpc-web.ts`, `src/grok/reset-coupons.ts`, and `src/grok/reset-coupon-ledger.ts`.
+- **D2:** Zero external dependencies for protobuf or gRPC-Web. Minimal self-contained varint / length-delimited codec and 5-byte framing parser using standard Web API typed arrays (`Uint8Array`, `DataView`).
+- **D3:** Management routes (`GET /api/grok/reset-coupons` and `POST /api/grok/reset-coupons/consume`) wire via lazy route dispatch mirroring Codex reset-credit patterns.
+- **D4:** CLI subcommand `grok-reset-coupons` in `src/cli/account-auth.ts` requires `--yes` confirmation when `--consume` is passed, validating operation IDs.
+- **D5:** Test suites in `tests/providers/xai/grok-reset-coupons.test.ts`, explicitly mapped to `providers/xai` tier in `scripts/test-layout/layout.json` and `tests/fixtures/test-layout-expected.json`.
+
+---
+
+## 2. Repo Seams & Anchor Points
+
+1. `src/oauth/xai.ts:369`: `refreshXaiToken(refreshToken, signal)` — token refresher for expired xAI access tokens.
+2. `src/oauth/index.ts:248-251`: Central provider registry entry binding `xai` token refresh callback.
+3. `src/oauth/index.ts:613`: `getValidAccessSnapshotForAccount(provider, accountId, opts)` — returns fresh access token, auto-refreshing under lock when expired.
+4. `src/oauth/store.ts:864`: `listAccounts(provider)` — lists stored accounts for provider `xai`.
+5. `src/oauth/store.ts:890`: `getAccountCredentialWithStatus` — retrieves account credential and validity status.
+6. `src/oauth/store.ts:923`: `captureOAuthAccountSelection("xai")` — active account selection context.
+7. `src/providers/xai-transport.ts:28-56`: `XAI_GROK_COMPATIBILITY` header definitions (`tokenAuth: "x-xai-token-auth"`, value `"xai-grok-cli"`).
+8. `src/grok/*.ts`: Grok domain modules (`catalog.ts`, `effort.ts`, `inject.ts`, `status.ts`, `sync.ts`).
+9. `scripts/test-layout/layout.json:694-704`: Test layout map registering `grok-*.test.ts` suites under `providers/xai`.
+10. `tests/fixtures/test-layout-expected.json:528-538`: Snapshot fixture for test layout verification.
+11. `src/server/management/route-registry.ts:94,102,127-140`: Route table definitions for reset credits and Grok APIs.
+12. `src/server/management-api.ts:140-144`: Lazy dispatch pattern `handleQuotaResetRoutesOnDemand` (namespace guard at 141, dynamic `import()` at 142, dispatch-chain entry at 243); `:383` is the `/api/codex-auth/` prefix dispatch.
+13. `openManualResetCreditOperation` is defined at `src/codex/reset-credit-operation-ledger.ts:1191`; `src/codex/auth-api.ts:2605-2647` is the consume-route call site for the journaled read and consume handlers.
+14. `src/codex/reset-credit-auto-redeem.ts:71-105`: Crash-safe disk journal pattern using `atomicWriteFile`.
+15. `src/codex/reset-credit-recovery.ts:40`: UUID operation ID validation regex and type guard.
+16. `src/cli/account-auth.ts:275-302`: CLI reset-credits command execution pattern.
+17. `src/cli/account.ts:62,358-360`: Account command line options parser.
+18. `src/cli/registry.ts:224,236`: CLI route registry.
+
+---
+
+## 3. Protobuf Wire Encoding and Decoding Specification
+
+### 3.1 Field Table
+
+| Message | Field Number | Field Name | Wire Type | Wire Type ID | Representation |
+|:---|:---:|:---|:---|:---:|:---|
+| `RedeemResetRequest` | 1 | `tokenId` | Length-delimited | 2 | UTF-8 encoded string |
+| `GetRemainingResetsResponse` | 10 | `tokens` | Length-delimited | 2 | Repeated `ConsumerResetToken` submessage |
+| `ConsumerResetToken` | 10 | `tokenId` | Length-delimited | 2 | UTF-8 encoded string |
+| `ConsumerResetToken` | 20 | `validityStart` | Length-delimited | 2 | `google.protobuf.Timestamp` submessage |
+| `ConsumerResetToken` | 30 | `validityEnd` | Length-delimited | 2 | `google.protobuf.Timestamp` submessage |
+| `Timestamp` | 1 | `seconds` | Varint | 0 | 64-bit varint (Unix epoch seconds) |
+| `Timestamp` | 2 | `nanos` | Varint | 0 | 32-bit varint (fractional nanoseconds, optional) |
+
+### 3.2 Wire Tag Calculation
+Tag = `(field_number << 3) | wire_type`:
+- `RedeemResetRequest.tokenId` (Field 1, Wire Type 2): `(1 << 3) | 2 = 10` (`0x0a`).
+- `GetRemainingResetsResponse.tokens` (Field 10, Wire Type 2): `(10 << 3) | 2 = 82` (`0x52`).
+- `ConsumerResetToken.tokenId` (Field 10, Wire Type 2): `(10 << 3) | 2 = 82` (`0x52`).
+- `ConsumerResetToken.validityStart` (Field 20, Wire Type 2): `(20 << 3) | 2 = 162` (`0xa2, 0x01`).
+- `ConsumerResetToken.validityEnd` (Field 30, Wire Type 2): `(30 << 3) | 2 = 242` (`0xf2, 0x01`).
+- `Timestamp.seconds` (Field 1, Wire Type 0): `(1 << 3) | 0 = 8` (`0x08`).
+
+---
+
+## 4. File-by-File Implementation Plan
+
+### 4.1 File 1: `src/grok/grpc-web.ts` (NEW)
+
+#### Exact Exported Signatures
+```typescript
+export interface GrpcWebTrailer {
+  status: number;
+  statusMessage?: string;
+  metadata: Record<string, string>;
+}
+
+export interface DecodedGrpcWebResponse {
+  messages: Uint8Array[];
+  status: number;
+  statusMessage?: string;
+  trailers?: GrpcWebTrailer;
+}
+
+export class GrpcWebError extends Error {
+  readonly status: number;
+  readonly statusMessage: string;
+  constructor(status: number, statusMessage: string);
+}
+
+export function encodeGrpcWebEnvelope(message: Uint8Array): Uint8Array;
+export function decodeGrpcWebResponse(bytes: Uint8Array): DecodedGrpcWebResponse;
+export function parseGrpcWebTrailers(bytes: Uint8Array): GrpcWebTrailer;
+```
+
+#### Before / After Code
+**Before:** File does not exist.
+
+**After:**
+```typescript
+/**
+ * Minimal, zero-dependency gRPC-Web binary framing encoder and decoder.
+ * Supports 5-byte header prefix: 0x00 data frames, 0x80 trailer frames.
+ */
+
+export interface GrpcWebTrailer {
+  status: number;
+  statusMessage?: string;
+  metadata: Record<string, string>;
+}
+
+export interface DecodedGrpcWebResponse {
+  messages: Uint8Array[];
+  status: number;
+  statusMessage?: string;
+  trailers?: GrpcWebTrailer;
+}
+
+export class GrpcWebError extends Error {
+  readonly status: number;
+  readonly statusMessage: string;
+
+  constructor(status: number, statusMessage: string) {
+    super(`gRPC-Web call failed with status ${status}: ${statusMessage}`);
+    this.name = "GrpcWebError";
+    this.status = status;
+    this.statusMessage = statusMessage;
+  }
+}
+
+const FRAME_DATA = 0x00;
+const FRAME_TRAILER = 0x80;
+const HEADER_SIZE = 5;
+
+/**
+ * Encodes a protobuf payload into a single gRPC-Web binary data frame (flag 0x00).
+ */
+export function encodeGrpcWebEnvelope(message: Uint8Array): Uint8Array {
+  const envelope = new Uint8Array(HEADER_SIZE + message.length);
+  envelope[0] = FRAME_DATA;
+  const view = new DataView(envelope.buffer, envelope.byteOffset, envelope.byteLength);
+  view.setUint32(1, message.length, false); // Big-endian u32
+  envelope.set(message, HEADER_SIZE);
+  return envelope;
+}
+
+/**
+ * Parses ASCII key-value lines from a gRPC-Web trailer frame payload.
+ */
+export function parseGrpcWebTrailers(bytes: Uint8Array): GrpcWebTrailer {
+  const text = new TextDecoder("utf-8").decode(bytes);
+  const lines = text.split(/\r?\n/);
+  const metadata: Record<string, string> = {};
+  let status = 0;
+  let statusMessage: string | undefined;
+
+  for (const line of lines) {
+    const colonIdx = line.indexOf(":");
+    if (colonIdx === -1) continue;
+    const key = line.slice(0, colonIdx).trim().toLowerCase();
+    const value = line.slice(colonIdx + 1).trim();
+    if (!key) continue;
+    metadata[key] = value;
+    if (key === "grpc-status") {
+      const parsed = parseInt(value, 10);
+      if (!Number.isNaN(parsed)) {
+        status = parsed;
+      }
+    } else if (key === "grpc-message") {
+      try {
+        statusMessage = decodeURIComponent(value);
+      } catch {
+        statusMessage = value;
+      }
+    }
+  }
+
+  return { status, statusMessage, metadata };
+}
+
+/**
+ * Decodes a contiguous gRPC-Web binary stream into data messages and trailing metadata.
+ */
+export function decodeGrpcWebResponse(bytes: Uint8Array): DecodedGrpcWebResponse {
+  const messages: Uint8Array[] = [];
+  let offset = 0;
+  let trailer: GrpcWebTrailer | undefined;
+
+  while (offset + HEADER_SIZE <= bytes.length) {
+    const flag = bytes[offset];
+    const view = new DataView(bytes.buffer, bytes.byteOffset + offset, HEADER_SIZE);
+    const length = view.getUint32(1, false);
+    const frameStart = offset + HEADER_SIZE;
+    const frameEnd = frameStart + length;
+
+    if (frameEnd > bytes.length) {
+      throw new Error(`Incomplete gRPC-Web frame at offset ${offset}: expected ${length} bytes, got ${bytes.length - frameStart}`);
+    }
+
+    const payload = bytes.subarray(frameStart, frameEnd);
+
+    if (flag === FRAME_DATA) {
+      messages.push(payload);
+    } else if (flag === FRAME_TRAILER) {
+      trailer = parseGrpcWebTrailers(payload);
+    }
+
+    offset = frameEnd;
+  }
+
+  const finalStatus = trailer ? trailer.status : 0;
+  const finalMessage = trailer?.statusMessage;
+
+  return {
+    messages,
+    status: finalStatus,
+    statusMessage: finalMessage,
+    trailers: trailer,
+  };
+}
+```
+
+#### Acceptance Criteria & Verifier
+- **Acceptance Criteria:**
+  1. `encodeGrpcWebEnvelope(bytes)` writes `0x00` at index 0, length in big-endian u32 at indices 1-4, and copies input payload starting at index 5.
+  2. `decodeGrpcWebResponse(bytes)` parses multiple 0x00 frames and extracts 0x80 trailer frame with parsed `grpc-status` and `grpc-message`.
+  3. Throws descriptive error on truncated payload frames.
+- **Verifier Command:**
+  ```bash
+  bun test tests/providers/xai/grok-reset-coupons.test.ts
+  ```
+
+---
+
+### 4.2 File 2: `src/grok/reset-coupons.ts` (NEW)
+
+#### Exact Exported Signatures
+```typescript
+export const GROK_CONSUMER_UI_BASE_URL = "https://grok.com";
+export const GROK_GET_REMAINING_RESETS_ENDPOINT =
+  "https://grok.com/prod_mc_billing.ConsumerUiSvc/GetRemainingResets";
+export const GROK_REDEEM_RESET_ENDPOINT =
+  "https://grok.com/prod_mc_billing.ConsumerUiSvc/RedeemReset";
+
+export interface GrokResetCoupon {
+  tokenId: string;
+  validityStart: string;
+  validityEnd: string;
+}
+
+export interface GetRemainingResetsOptions {
+  accessToken: string;
+  fetchFn?: typeof globalThis.fetch;
+  signal?: AbortSignal;
+  endpoint?: string;
+}
+
+export interface RedeemResetOptions {
+  accessToken: string;
+  tokenId: string;
+  fetchFn?: typeof globalThis.fetch;
+  signal?: AbortSignal;
+  endpoint?: string;
+}
+
+export interface RedeemResetResult {
+  success: boolean;
+  status: number;
+  statusMessage?: string;
+}
+
+export function encodeVarint(value: number | bigint): Uint8Array;
+export function decodeVarint(bytes: Uint8Array, offset: number): { value: number; bytesRead: number };
+export function encodeRedeemResetRequest(tokenId: string): Uint8Array;
+export function decodeGetRemainingResetsResponse(payload: Uint8Array): GrokResetCoupon[];
+export function getGrokRemainingResets(options: GetRemainingResetsOptions): Promise<{ tokens: GrokResetCoupon[] }>;
+export function redeemGrokResetCoupon(options: RedeemResetOptions): Promise<RedeemResetResult>;
+```
+
+#### Before / After Code
+**Before:** File does not exist.
+
+**After:**
+```typescript
+import { XAI_GROK_COMPATIBILITY } from "../providers/xai-transport";
+import {
+  decodeGrpcWebResponse,
+  encodeGrpcWebEnvelope,
+  GrpcWebError,
+} from "./grpc-web";
+
+export const GROK_CONSUMER_UI_BASE_URL = "https://grok.com";
+export const GROK_GET_REMAINING_RESETS_ENDPOINT =
+  "https://grok.com/prod_mc_billing.ConsumerUiSvc/GetRemainingResets";
+export const GROK_REDEEM_RESET_ENDPOINT =
+  "https://grok.com/prod_mc_billing.ConsumerUiSvc/RedeemReset";
+
+export interface GrokResetCoupon {
+  tokenId: string;
+  validityStart: string;
+  validityEnd: string;
+}
+
+export interface GetRemainingResetsOptions {
+  accessToken: string;
+  fetchFn?: typeof globalThis.fetch;
+  signal?: AbortSignal;
+  endpoint?: string;
+}
+
+export interface RedeemResetOptions {
+  accessToken: string;
+  tokenId: string;
+  fetchFn?: typeof globalThis.fetch;
+  signal?: AbortSignal;
+  endpoint?: string;
+}
+
+export interface RedeemResetResult {
+  success: boolean;
+  status: number;
+  statusMessage?: string;
+}
+
+/**
+ * Encodes a 32/64-bit non-negative integer into protobuf varint wire bytes.
+ */
+export function encodeVarint(value: number | bigint): Uint8Array {
+  const bytes: number[] = [];
+  let val = BigInt(value);
+  while (val >= 0x80n) {
+    bytes.push(Number((val & 0x7fn) | 0x80n));
+    val >>= 7n;
+  }
+  bytes.push(Number(val & 0x7fn));
+  return new Uint8Array(bytes);
+}
+
+/**
+ * Decodes a protobuf varint from bytes at offset.
+ */
+export function decodeVarint(bytes: Uint8Array, offset: number): { value: number; bytesRead: number } {
+  let result = 0;
+  let shift = 0;
+  let count = 0;
+
+  while (offset + count < bytes.length) {
+    const b = bytes[offset + count];
+    count++;
+    result |= (b & 0x7f) << shift;
+    if ((b & 0x80) === 0) break;
+    shift += 7;
+    if (shift > 35) {
+      // For timestamps seconds, JS safe integers suffice.
+      break;
+    }
+  }
+
+  return { value: result, bytesRead: count };
+}
+
+/**
+ * Encodes RedeemResetRequest protobuf: field 1 (string token_id).
+ */
+export function encodeRedeemResetRequest(tokenId: string): Uint8Array {
+  const tokenBytes = new TextEncoder().encode(tokenId);
+  const tag = (1 << 3) | 2; // Field 1, Wire Type 2
+  const tagBytes = encodeVarint(tag);
+  const lenBytes = encodeVarint(tokenBytes.length);
+
+  const out = new Uint8Array(tagBytes.length + lenBytes.length + tokenBytes.length);
+  out.set(tagBytes, 0);
+  out.set(lenBytes, tagBytes.length);
+  out.set(tokenBytes, tagBytes.length + lenBytes.length);
+  return out;
+}
+
+/**
+ * Decodes a Timestamp submessage (field 1: int64 seconds).
+ */
+function decodeTimestamp(bytes: Uint8Array): number {
+  let offset = 0;
+  let seconds = 0;
+
+  while (offset < bytes.length) {
+    const { value: tag, bytesRead: tagLen } = decodeVarint(bytes, offset);
+    offset += tagLen;
+    const fieldNum = tag >> 3;
+    const wireType = tag & 0x7;
+
+    if (wireType === 0) {
+      const { value, bytesRead } = decodeVarint(bytes, offset);
+      offset += bytesRead;
+      if (fieldNum === 1) seconds = value;
+    } else if (wireType === 2) {
+      const { value: len, bytesRead } = decodeVarint(bytes, offset);
+      offset += bytesRead + len;
+    } else {
+      break;
+    }
+  }
+
+  return seconds;
+}
+
+/**
+ * Decodes a ConsumerResetToken submessage.
+ */
+function decodeConsumerResetToken(bytes: Uint8Array): GrokResetCoupon | null {
+  let offset = 0;
+  let tokenId = "";
+  let startSec = 0;
+  let endSec = 0;
+
+  while (offset < bytes.length) {
+    const { value: tag, bytesRead: tagLen } = decodeVarint(bytes, offset);
+    offset += tagLen;
+    const fieldNum = tag >> 3;
+    const wireType = tag & 0x7;
+
+    if (wireType === 2) {
+      const { value: len, bytesRead: lenRead } = decodeVarint(bytes, offset);
+      offset += lenRead;
+      const sub = bytes.subarray(offset, offset + len);
+      offset += len;
+
+      if (fieldNum === 10) {
+        tokenId = new TextDecoder("utf-8").decode(sub);
+      } else if (fieldNum === 20) {
+        startSec = decodeTimestamp(sub);
+      } else if (fieldNum === 30) {
+        endSec = decodeTimestamp(sub);
+      }
+    } else if (wireType === 0) {
+      const { bytesRead } = decodeVarint(bytes, offset);
+      offset += bytesRead;
+    } else {
+      break;
+    }
+  }
+
+  if (!tokenId) return null;
+
+  return {
+    tokenId,
+    validityStart: startSec > 0 ? new Date(startSec * 1000).toISOString() : "",
+    validityEnd: endSec > 0 ? new Date(endSec * 1000).toISOString() : "",
+  };
+}
+
+/**
+ * Decodes GetRemainingResetsResponse protobuf message: field 10 (repeated ConsumerResetToken).
+ */
+export function decodeGetRemainingResetsResponse(payload: Uint8Array): GrokResetCoupon[] {
+  const tokens: GrokResetCoupon[] = [];
+  let offset = 0;
+
+  while (offset < payload.length) {
+    const { value: tag, bytesRead: tagLen } = decodeVarint(payload, offset);
+    offset += tagLen;
+    const fieldNum = tag >> 3;
+    const wireType = tag & 0x7;
+
+    if (wireType === 2) {
+      const { value: len, bytesRead: lenRead } = decodeVarint(payload, offset);
+      offset += lenRead;
+      const sub = payload.subarray(offset, offset + len);
+      offset += len;
+
+      if (fieldNum === 10) {
+        const token = decodeConsumerResetToken(sub);
+        if (token) tokens.push(token);
+      }
+    } else if (wireType === 0) {
+      const { bytesRead } = decodeVarint(payload, offset);
+      offset += bytesRead;
+    } else {
+      break;
+    }
+  }
+
+  return tokens;
+}
+
+function buildGrokHeaders(accessToken: string): Record<string, string> {
+  return {
+    "Content-Type": "application/grpc-web+proto",
+    "X-Grpc-Web": "1",
+    "Accept": "application/grpc-web+proto",
+    "Authorization": `Bearer ${accessToken}`,
+    [XAI_GROK_COMPATIBILITY.headers.tokenAuth]: "xai-grok-cli",
+  };
+}
+
+/**
+ * Reads available Grok reset tokens for the authenticated xAI account.
+ */
+export async function getGrokRemainingResets(options: GetRemainingResetsOptions): Promise<{ tokens: GrokResetCoupon[] }> {
+  const fetchImpl = options.fetchFn ?? globalThis.fetch;
+  const endpoint = options.endpoint ?? GROK_GET_REMAINING_RESETS_ENDPOINT;
+  const emptyBody = encodeGrpcWebEnvelope(new Uint8Array(0));
+
+  const res = await fetchImpl(endpoint, {
+    method: "POST",
+    headers: buildGrokHeaders(options.accessToken),
+    body: emptyBody,
+    signal: options.signal,
+  });
+
+  if (!res.ok) {
+    throw new Error(`GetRemainingResets HTTP error ${res.status}: ${res.statusText}`);
+  }
+
+  const rawBytes = new Uint8Array(await res.arrayBuffer());
+  const decoded = decodeGrpcWebResponse(rawBytes);
+
+  if (decoded.status !== 0) {
+    throw new GrpcWebError(decoded.status, decoded.statusMessage ?? "Unknown gRPC error");
+  }
+
+  if (decoded.messages.length === 0) {
+    return { tokens: [] };
+  }
+
+  return { tokens: decodeGetRemainingResetsResponse(decoded.messages[0]) };
+}
+
+/**
+ * Redeems a specific Grok reset token by tokenId.
+ */
+export async function redeemGrokResetCoupon(options: RedeemResetOptions): Promise<RedeemResetResult> {
+  const fetchImpl = options.fetchFn ?? globalThis.fetch;
+  const endpoint = options.endpoint ?? GROK_REDEEM_RESET_ENDPOINT;
+  const protoMessage = encodeRedeemResetRequest(options.tokenId);
+  const envelope = encodeGrpcWebEnvelope(protoMessage);
+
+  const res = await fetchImpl(endpoint, {
+    method: "POST",
+    headers: buildGrokHeaders(options.accessToken),
+    body: envelope,
+    signal: options.signal,
+  });
+
+  if (!res.ok) {
+    throw new Error(`RedeemReset HTTP error ${res.status}: ${res.statusText}`);
+  }
+
+  const rawBytes = new Uint8Array(await res.arrayBuffer());
+  const decoded = decodeGrpcWebResponse(rawBytes);
+
+  if (decoded.status !== 0) {
+    throw new GrpcWebError(decoded.status, decoded.statusMessage ?? "Unknown gRPC error");
+  }
+
+  return {
+    success: true,
+    status: decoded.status,
+    statusMessage: decoded.statusMessage,
+  };
+}
+```
+
+#### Acceptance Criteria & Verifier
+- **Acceptance Criteria:**
+  1. `getGrokRemainingResets` issues POST with `Content-Type: application/grpc-web+proto`, `X-Grpc-Web: 1`, `Authorization: Bearer <token>`, and `x-xai-token-auth: xai-grok-cli`.
+  2. Protobuf decoder correctly parses field 10 repeated `GrokResetCoupon` tokens with `tokenId` and ISO-string `validityStart`/`validityEnd` (epoch seconds are kept internally as `validityStartSeconds`/`validityEndSeconds` only during decode).
+  3. `redeemGrokResetCoupon` encodes field 1 string `token_id` in a 5-byte envelope and surfaces `GrpcWebError` on non-zero gRPC statuses (e.g. status 3 invalid token).
+- **Verifier Command:**
+  ```bash
+  bun test tests/providers/xai/grok-reset-coupons.test.ts
+  ```
+
+---
+
+### 4.3 File 3: `src/grok/reset-coupon-ledger.ts` (NEW)
+
+#### Exact Exported Signatures
+```typescript
+export type GrokResetCouponOperationKind = "execute" | "replay" | "identity-mismatch" | "capacity";
+
+export interface GrokResetCouponOperationIdentity {
+  accountId: string;
+  tokenId?: string;
+  operationId: string;
+}
+
+export interface GrokResetCouponOperationRecord {
+  kind: GrokResetCouponOperationKind;
+  operationId: string;
+  accountId?: string;
+  tokenId?: string;
+  code?: string;
+  settledAt?: number;
+}
+
+export function grokCouponJournalPath(customDir?: string): string;
+export function openGrokResetCouponOperation(identity: GrokResetCouponOperationIdentity, now?: number, journalPath?: string): GrokResetCouponOperationRecord;
+export function recordGrokResetCouponSettlement(settlement: { operationId: string; tokenId?: string; code: string; status: "success" | "failed" }, now?: number, journalPath?: string): void;
+```
+
+#### Before / After Code
+**Before:** File does not exist.
+
+**After:**
+```typescript
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteFile } from "../config/atomic-write";
+import { getConfigDir } from "../config/paths";
+
+export type GrokResetCouponOperationKind = "execute" | "replay" | "identity-mismatch" | "capacity";
+
+export interface GrokResetCouponOperationIdentity {
+  accountId: string;
+  tokenId?: string;
+  operationId: string;
+}
+
+export interface GrokResetCouponOperationRecord {
+  kind: GrokResetCouponOperationKind;
+  operationId: string;
+  accountId?: string;
+  tokenId?: string;
+  code?: string;
+  settledAt?: number;
+}
+
+interface GrokResetCouponOperationState {
+  accountId: string;
+  tokenId?: string;
+  status: "open" | "settled" | "failed";
+  code?: string;
+  createdAt: number;
+  updatedAt: number;
+}
+
+interface GrokResetCouponLedger {
+  version: 1;
+  operations: Record<string, GrokResetCouponOperationState>;
+}
+
+export function grokCouponJournalPath(customDir?: string): string {
+  const dir = customDir ?? getConfigDir();
+  return join(dir, "grok-reset-coupon-ledger.json");
+}
+
+function readGrokCouponLedger(filePath: string): GrokResetCouponLedger {
+  if (!existsSync(filePath)) {
+    return { version: 1, operations: {} };
+  }
+  try {
+    const raw = readFileSync(filePath, "utf-8");
+    const parsed = JSON.parse(raw) as GrokResetCouponLedger;
+    return parsed && parsed.version === 1 && parsed.operations && typeof parsed.operations === "object"
+      ? parsed
+      : { version: 1, operations: {} };
+  } catch {
+    return { version: 1, operations: {} };
+  }
+}
+
+function writeGrokCouponLedger(filePath: string, ledger: GrokResetCouponLedger, now = Date.now()): void {
+  // Prune settled/failed operations older than 30 days to avoid unbounded growth
+  const retentionCutoff = now - 30 * 24 * 60 * 60_000;
+  ledger.operations = Object.fromEntries(
+    Object.entries(ledger.operations).filter(
+      ([, op]) => op.status === "open" || op.updatedAt > retentionCutoff,
+    ),
+  );
+  atomicWriteFile(filePath, JSON.stringify(ledger, null, 2));
+}
+
+const MAX_GROK_RESET_COUPON_OPERATION_IDS = 256;
+
+export function openGrokResetCouponOperation(
+  identity: GrokResetCouponOperationIdentity,
+  now = Date.now(),
+  journalPath?: string,
+): GrokResetCouponOperationRecord {
+  const filePath = journalPath ?? grokCouponJournalPath();
+  const ledger = readGrokCouponLedger(filePath);
+
+  if (Object.keys(ledger.operations).length >= MAX_GROK_RESET_COUPON_OPERATION_IDS) {
+    return { kind: "capacity", operationId: identity.operationId };
+  }
+
+  const existing = ledger.operations[identity.operationId];
+  if (existing) {
+    if (existing.accountId !== identity.accountId) {
+      return { kind: "identity-mismatch", operationId: identity.operationId };
+    }
+    if (existing.status !== "open") {
+      // Durably settled already: replay the recorded outcome instead of
+      // trusting upstream idempotency for an irreversible spend.
+      return {
+        kind: "replay",
+        operationId: identity.operationId,
+        accountId: existing.accountId,
+        tokenId: existing.tokenId,
+        code: existing.code,
+        settledAt: existing.updatedAt,
+      };
+    }
+    return {
+      kind: "execute",
+      operationId: identity.operationId,
+      accountId: existing.accountId,
+      tokenId: existing.tokenId,
+    };
+  }
+
+  ledger.operations[identity.operationId] = {
+    accountId: identity.accountId,
+    ...(identity.tokenId === undefined ? {} : { tokenId: identity.tokenId }),
+    status: "open",
+    createdAt: now,
+    updatedAt: now,
+  };
+  writeGrokCouponLedger(filePath, ledger, now);
+  return {
+    kind: "execute",
+    operationId: identity.operationId,
+    accountId: identity.accountId,
+    tokenId: identity.tokenId,
+  };
+}
+
+export function recordGrokResetCouponSettlement(
+  settlement: { operationId: string; tokenId?: string; code: string; status: "success" | "failed" },
+  now = Date.now(),
+  journalPath?: string,
+): void {
+  const filePath = journalPath ?? grokCouponJournalPath();
+  const ledger = readGrokCouponLedger(filePath);
+  const existing = ledger.operations[settlement.operationId];
+  if (!existing) return;
+
+  existing.status = settlement.status === "success" ? "settled" : "failed";
+  existing.code = settlement.code;
+  if (settlement.tokenId !== undefined) existing.tokenId = settlement.tokenId;
+  existing.updatedAt = now;
+
+  writeGrokCouponLedger(filePath, ledger, now);
+}
+
+```
+
+#### Acceptance Criteria & Verifier
+- **Acceptance Criteria:**
+  1. Ledger uses `atomicWriteFile` ensuring durability without partial-write corruption.
+  2. `openGrokResetCouponOperation` returns `"execute"` for a new or still-open operation, `"replay"` with the recorded outcome for an already-settled operation, `"identity-mismatch"` when the `operationId` belongs to another account, and `"capacity"` when the ledger is full — the Codex-mirror result kinds of `openManualResetCreditOperation` (`src/codex/reset-credit-operation-ledger.ts:1191-1207`; call-site pattern at `src/codex/auth-api.ts:2616-2641`).
+  3. `recordGrokResetCouponSettlement` durably records the final outcome so later opens replay it.
+- **Verifier Command:**
+  ```bash
+  bun test tests/providers/xai/grok-reset-coupons.test.ts
+  ```
+
+---
+
+### 4.4 File 4: `scripts/test-layout/layout.json` (MODIFY)
+
+#### Exact Changes
+Add `"grok-reset-coupons.test.ts": "providers/xai"` into the JSON map under the `providers/xai` section.
+
+#### Before / After Code
+**Before (lines 694-706):**
+```json
+    "grok-attribution.test.ts": "providers/xai",
+    "grok-config-inject.test.ts": "providers/xai",
+    "grok-effort-inject.test.ts": "providers/xai",
+    "grok-lifecycle.test.ts": "providers/xai",
+    "grok-management-api.test.ts": "providers/xai",
+    "grok-models-effort-list.test.ts": "providers/xai",
+    "grok-orphan-adoption.test.ts": "providers/xai",
+    "grok-selection.test.ts": "providers/xai",
+    "grok-status.test.ts": "providers/xai",
+    "grok-sync.test.ts": "providers/xai",
+    "grok-writer-boundary.test.ts": "providers/xai",
+    "gui-api-error.test.ts": "gui",
+```
+
+**After:**
+```json
+    "grok-attribution.test.ts": "providers/xai",
+    "grok-config-inject.test.ts": "providers/xai",
+    "grok-effort-inject.test.ts": "providers/xai",
+    "grok-lifecycle.test.ts": "providers/xai",
+    "grok-management-api.test.ts": "providers/xai",
+    "grok-models-effort-list.test.ts": "providers/xai",
+    "grok-orphan-adoption.test.ts": "providers/xai",
+    "grok-reset-coupons.test.ts": "providers/xai",
+    "grok-selection.test.ts": "providers/xai",
+    "grok-status.test.ts": "providers/xai",
+    "grok-sync.test.ts": "providers/xai",
+    "grok-writer-boundary.test.ts": "providers/xai",
+    "gui-api-error.test.ts": "gui",
+```
+
+#### Acceptance Criteria & Verifier
+- **Acceptance Criteria:** `layout.json` parses as valid JSON with alphabetical key ordering preserved.
+- **Verifier Command:**
+  ```bash
+  bun test tests/test-layout.test.ts tests/test-layout-tooling.test.ts
+  ```
+
+---
+
+### 4.5 File 5: `tests/fixtures/test-layout-expected.json` (MODIFY)
+
+#### Exact Changes
+Add `"grok-reset-coupons.test.ts": "providers/xai"` into the snapshot expectation fixture to keep it synchronized with `layout.json`.
+
+#### Before / After Code
+**Before (lines 534-540):**
+```json
+  "grok-orphan-adoption.test.ts": "providers/xai",
+  "grok-selection.test.ts": "providers/xai",
+  "grok-status.test.ts": "providers/xai",
+  "grok-sync.test.ts": "providers/xai",
+  "grok-writer-boundary.test.ts": "providers/xai",
+  "gui-api-error.test.ts": "gui",
+```
+
+**After:**
+```json
+  "grok-orphan-adoption.test.ts": "providers/xai",
+  "grok-reset-coupons.test.ts": "providers/xai",
+  "grok-selection.test.ts": "providers/xai",
+  "grok-status.test.ts": "providers/xai",
+  "grok-sync.test.ts": "providers/xai",
+  "grok-writer-boundary.test.ts": "providers/xai",
+  "gui-api-error.test.ts": "gui",
+```
+
+#### Acceptance Criteria & Verifier
+- **Acceptance Criteria:** Test layout verification passes cleanly with zero layout mismatch.
+- **Verifier Command:**
+  ```bash
+  bun test tests/test-layout.test.ts tests/test-layout-tooling.test.ts
+  ```
+
+---
+
+### 4.6 File 6: `tests/providers/xai/grok-reset-coupons.test.ts` (NEW)
+
+#### Exact Test List
+1. **gRPC-Web framing round-trip:** Encodes data payload and decodes response with trailers, verifying flag bytes `0x00` and `0x80`, u32 length prefix, and parsed status.
+2. **Decode captured live-shape fixture:** Decodes response bytes mimicking live `GetRemainingResets` response (field 10 tokens, field 10 tokenId, field 20/30 timestamps) and asserts exact parsed `GrokResetCoupon` ISO strings.
+3. **Auth header assertions:** Intercepts outgoing HTTP request and verifies presence of `Authorization: Bearer <token>` and `X-XAI-Token-Auth: xai-grok-cli` without cookies.
+4. **gRPC-status error surfacing:** Asserts that upstream trailer `grpc-status: 3` and message `redeem_reset(), Invalid token_id` throws `GrpcWebError` with status code 3.
+5. **Ledger idempotent replay:** Opens an operation in a temporary test ledger, verifies re-opening a settled operation returns kind `replay`, and records settlement via `recordGrokResetCouponSettlement`.
+6. **Refresh-on-401 with stubbed fetch:** Simulates initial 401 response triggering OAuth token refresh and subsequent retry to completion.
+
+#### Before / After Code
+**Before:** File does not exist.
+
+**After:**
+```typescript
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  decodeGrpcWebResponse,
+  encodeGrpcWebEnvelope,
+  GrpcWebError,
+  parseGrpcWebTrailers,
+} from "../../../src/grok/grpc-web";
+import {
+  getGrokRemainingResets,
+  decodeGetRemainingResetsResponse,
+  encodeRedeemResetRequest,
+  encodeVarint,
+  GROK_GET_REMAINING_RESETS_ENDPOINT,
+  GROK_REDEEM_RESET_ENDPOINT,
+  redeemGrokResetCoupon,
+} from "../../../src/grok/reset-coupons";
+import {
+  grokCouponJournalPath,
+  openGrokResetCouponOperation,
+  recordGrokResetCouponSettlement,
+} from "../../../src/grok/reset-coupon-ledger";
+
+describe("grok reset coupons", () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "grok-coupons-test-"));
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("round-trips grpc-web data framing and parses trailers", () => {
+    const payload = new TextEncoder().encode("test-payload-bytes");
+    const dataEnvelope = encodeGrpcWebEnvelope(payload);
+
+    expect(dataEnvelope[0]).toBe(0x00);
+    const view = new DataView(dataEnvelope.buffer, dataEnvelope.byteOffset, 5);
+    expect(view.getUint32(1, false)).toBe(payload.length);
+
+    const trailerPayload = new TextEncoder().encode("grpc-status:0\r\ngrpc-message:ok\r\n");
+    const trailerEnvelope = new Uint8Array(5 + trailerPayload.length);
+    trailerEnvelope[0] = 0x80;
+    const trailerView = new DataView(trailerEnvelope.buffer, trailerEnvelope.byteOffset, 5);
+    trailerView.setUint32(1, trailerPayload.length, false);
+    trailerEnvelope.set(trailerPayload, 5);
+
+    const combined = new Uint8Array(dataEnvelope.length + trailerEnvelope.length);
+    combined.set(dataEnvelope, 0);
+    combined.set(trailerEnvelope, dataEnvelope.length);
+
+    const decoded = decodeGrpcWebResponse(combined);
+    expect(decoded.messages.length).toBe(1);
+    expect(new TextDecoder().decode(decoded.messages[0])).toBe("test-payload-bytes");
+    expect(decoded.status).toBe(0);
+    expect(decoded.statusMessage).toBe("ok");
+  });
+
+  it("decodes captured live-shape GetRemainingResetsResponse fixture", () => {
+    // Construct protobuf binary:
+    // Field 10 (tokens):
+    //   Field 10 (tokenId): "token_live_abc123"
+    //   Field 20 (validityStart): Field 1 (seconds): 1726110000
+    //   Field 30 (validityEnd): Field 1 (seconds): 1728788400
+    const buildTimestamp = (sec: number) => {
+      const secTag = (1 << 3) | 0; // field 1, varint
+      const secBytes = encodeVarint(sec);
+      const out = new Uint8Array(1 + secBytes.length);
+      out[0] = secTag;
+      out.set(secBytes, 1);
+      return out;
+    };
+
+    const buildToken = (tokenId: string, startSec: number, endSec: number) => {
+      const idBytes = new TextEncoder().encode(tokenId);
+      const idTag = (10 << 3) | 2;
+      const idLen = encodeVarint(idBytes.length);
+
+      const startBytes = buildTimestamp(startSec);
+      const startTag = (20 << 3) | 2;
+      const startLen = encodeVarint(startBytes.length);
+
+      const endBytes = buildTimestamp(endSec);
+      const endTag = (30 << 3) | 2;
+      const endLen = encodeVarint(endBytes.length);
+
+      const totalLen =
+        1 + idLen.length + idBytes.length +
+        encodeVarint(startTag).length + startLen.length + startBytes.length +
+        encodeVarint(endTag).length + endLen.length + endBytes.length;
+
+      const out = new Uint8Array(totalLen);
+      let offset = 0;
+      out[offset++] = idTag;
+      out.set(idLen, offset);
+      offset += idLen.length;
+      out.set(idBytes, offset);
+      offset += idBytes.length;
+
+      const startTagBytes = encodeVarint(startTag);
+      out.set(startTagBytes, offset);
+      offset += startTagBytes.length;
+      out.set(startLen, offset);
+      offset += startLen.length;
+      out.set(startBytes, offset);
+      offset += startBytes.length;
+
+      const endTagBytes = encodeVarint(endTag);
+      out.set(endTagBytes, offset);
+      offset += endTagBytes.length;
+      out.set(endLen, offset);
+      offset += endLen.length;
+      out.set(endBytes, offset);
+      offset += endBytes.length;
+
+      return out;
+    };
+
+    const tokenSub = buildToken("token_live_abc123", 1726110000, 1728788400);
+    const topTag = (10 << 3) | 2;
+    const topLen = encodeVarint(tokenSub.length);
+    const responsePayload = new Uint8Array(1 + topLen.length + tokenSub.length);
+    responsePayload[0] = topTag;
+    responsePayload.set(topLen, 1);
+    responsePayload.set(tokenSub, 1 + topLen.length);
+
+    const tokens = decodeGetRemainingResetsResponse(responsePayload);
+    expect(tokens.length).toBe(1);
+    expect(tokens[0].tokenId).toBe("token_live_abc123");
+    expect(tokens[0].validityStart).toBe(new Date(1726110000 * 1000).toISOString());
+    expect(tokens[0].validityEnd).toBe(new Date(1728788400 * 1000).toISOString());
+  });
+
+  it("asserts auth headers and tokenAuth compatibility header on request", async () => {
+    let capturedHeaders: Headers | undefined;
+    let capturedBody: Uint8Array | undefined;
+
+    const mockFetch: typeof globalThis.fetch = async (input, init) => {
+      capturedHeaders = new Headers(init?.headers);
+      if (init?.body instanceof Uint8Array) {
+        capturedBody = init.body;
+      }
+      const emptyTrailer = new TextEncoder().encode("grpc-status:0\r\ngrpc-message:\r\n");
+      const envelope = new Uint8Array(5 + emptyTrailer.length);
+      envelope[0] = 0x80;
+      new DataView(envelope.buffer).setUint32(1, emptyTrailer.length, false);
+      envelope.set(emptyTrailer, 5);
+
+      return new Response(envelope, {
+        status: 200,
+        headers: { "content-type": "application/grpc-web+proto" },
+      });
+    };
+
+    await getGrokRemainingResets({
+      accessToken: "mock-access-token-12345",
+      fetchFn: mockFetch,
+    });
+
+    expect(capturedHeaders?.get("authorization")).toBe("Bearer mock-access-token-12345");
+    expect(capturedHeaders?.get("x-xai-token-auth")).toBe("xai-grok-cli");
+    expect(capturedHeaders?.get("x-grpc-web")).toBe("1");
+    expect(capturedHeaders?.get("content-type")).toBe("application/grpc-web+proto");
+    expect(capturedBody).toBeDefined();
+    expect(capturedBody?.[0]).toBe(0x00); // gRPC-Web data frame prefix
+  });
+
+  it("surfaces grpc-status 3 error on invalid token redemption", async () => {
+    const mockFetch: typeof globalThis.fetch = async () => {
+      const trailer = new TextEncoder().encode("grpc-status:3\r\ngrpc-message:redeem_reset()%2C%20Invalid%20token_id\r\n");
+      const envelope = new Uint8Array(5 + trailer.length);
+      envelope[0] = 0x80;
+      new DataView(envelope.buffer).setUint32(1, trailer.length, false);
+      envelope.set(trailer, 5);
+
+      return new Response(envelope, {
+        status: 200,
+        headers: { "content-type": "application/grpc-web+proto" },
+      });
+    };
+
+    let thrown: unknown;
+    try {
+      await redeemGrokResetCoupon({
+        accessToken: "test-token",
+        tokenId: "invalid_id_999",
+        fetchFn: mockFetch,
+      });
+    } catch (err) {
+      thrown = err;
+    }
+
+    expect(thrown).toBeInstanceOf(GrpcWebError);
+    const grpcErr = thrown as GrpcWebError;
+    expect(grpcErr.status).toBe(3);
+    expect(grpcErr.statusMessage).toContain("Invalid token_id");
+  });
+
+  it("handles crash-safe ledger open and idempotent replay", () => {
+    const ledgerPath = grokCouponJournalPath(tempDir);
+
+    const first = openGrokResetCouponOperation({
+      accountId: "acc-123",
+      tokenId: "tok-456",
+      operationId: "op-uuid-1",
+    }, undefined, ledgerPath);
+    expect(first.kind).toBe("execute");
+
+    recordGrokResetCouponSettlement({
+      operationId: "op-uuid-1",
+      tokenId: "tok-456",
+      code: "redeemed",
+      status: "success",
+    }, undefined, ledgerPath);
+
+    // Re-opening the same settled operationId replays the durable outcome
+    const replay = openGrokResetCouponOperation({
+      accountId: "acc-123",
+      tokenId: "tok-456",
+      operationId: "op-uuid-1",
+    }, undefined, ledgerPath);
+    expect(replay.kind).toBe("replay");
+    expect(replay.code).toBe("redeemed");
+    expect(replay.settledAt).toBeDefined();
+  });
+
+  it("refreshes token on 401 when integrated with refresh provider stub", async () => {
+    let callCount = 0;
+    let tokenUsed = "";
+
+    const mockFetch: typeof globalThis.fetch = async (input, init) => {
+      callCount++;
+      const headers = new Headers(init?.headers);
+      tokenUsed = headers.get("authorization") || "";
+
+      if (callCount === 1) {
+        return new Response("Unauthorized", { status: 401 });
+      }
+
+      const emptyTrailer = new TextEncoder().encode("grpc-status:0\r\n");
+      const envelope = new Uint8Array(5 + emptyTrailer.length);
+      envelope[0] = 0x80;
+      new DataView(envelope.buffer).setUint32(1, emptyTrailer.length, false);
+      envelope.set(emptyTrailer, 5);
+
+      return new Response(envelope, {
+        status: 200,
+        headers: { "content-type": "application/grpc-web+proto" },
+      });
+    };
+
+    // Retry harness mimicking getValidAccessSnapshotForAccount wrapper
+    let activeToken = "expired-token";
+    const executeWithRetry = async () => {
+      try {
+        return await getGrokRemainingResets({ accessToken: activeToken, fetchFn: mockFetch });
+      } catch (err: any) {
+        if (err.message.includes("401")) {
+          activeToken = "refreshed-fresh-token";
+          return await getGrokRemainingResets({ accessToken: activeToken, fetchFn: mockFetch });
+        }
+        throw err;
+      }
+    };
+
+    const res = await executeWithRetry();
+    expect(res).toEqual({ tokens: [] });
+    expect(callCount).toBe(2);
+    expect(tokenUsed).toBe("Bearer refreshed-fresh-token");
+  });
+});
+```
+
+#### Acceptance Criteria & Verifier
+- **Acceptance Criteria:** All 6 test scenarios execute and pass without network connectivity or timeouts.
+- **Verifier Command:**
+  ```bash
+  bun test tests/providers/xai/grok-reset-coupons.test.ts
+  ```
+
+---
+
+## 5. Verification Commands Summary
+
+| Action | Target | Command |
+|:---|:---|:---|
+| Test Unit Suite | `tests/providers/xai/grok-reset-coupons.test.ts` | `bun test tests/providers/xai/grok-reset-coupons.test.ts` |
+| Test Layout Check | `scripts/test-layout/layout.json` & fixture | `bun test tests/test-layout.test.ts tests/test-layout-tooling.test.ts` |
+| Full Provider Suite | `tests/providers/xai/` | `bun test tests/providers/xai/` |
diff --git a/devlog/_plan/260912_grok_reset_coupons/020_phase2_surfaces.md b/devlog/_plan/260912_grok_reset_coupons/020_phase2_surfaces.md
new file mode 100644
index 0000000000..6216985df7
--- /dev/null
+++ b/devlog/_plan/260912_grok_reset_coupons/020_phase2_surfaces.md
@@ -0,0 +1,547 @@
+# PRD: Grok Reset Coupons — Phase 2 Management API & CLI Surfaces
+
+This diff-level PRD specifies Phase 2 of the Grok reset coupon support within OpenCodex. It covers the management API routes (`GET /api/grok/reset-coupons` and `POST /api/grok/reset-coupons/consume`), lazy dispatch mounting in `src/server/management-api.ts`, route table registration in `src/server/management/route-registry.ts`, CLI subcommands in `src/cli/account-auth.ts`, `src/cli/account.ts`, and `src/cli/registry.ts`, and the test suite registration in `tests/providers/xai/grok-reset-coupons.test.ts` across `scripts/test-layout/layout.json` and `tests/fixtures/test-layout-expected.json`.
+
+---
+
+## 010 Context & Architectural Decisions
+
+### Accepted Decisions Summary
+- **D1 (Domain Implementation):** Client encapsulated in `src/grok/grpc-web.ts`, coupon inspection/redemption in `src/grok/reset-coupons.ts`, and durable operation journaling in `src/grok/reset-coupon-ledger.ts`.
+- **D3 (Management Endpoints & Routing):** Endpoints mounted under `/api/grok/reset-coupons` (GET) and `/api/grok/reset-coupons/consume` (POST) in `src/server/management/grok-coupon-routes.ts`. Handled via on-demand lazy import `handleGrokCouponRoutesOnDemand` in `src/server/management-api.ts` to preserve startup latency and maintain the core-lab boundary invariant.
+- **D4 (CLI Interface):** Subcommand `grok-reset-coupons` in `src/cli/account-auth.ts`, routed through `src/cli/account.ts` and registered in `src/cli/registry.ts`. Mirroring `resetCredits()`: `--consume` strictly mandates `--yes`; `--operation-id` validates against UUIDv4 via `isCodexResetCreditOperationId`; supports `--token-id` selection.
+- **D5 (Testing & Layout Verification):** Test suite in `tests/providers/xai/grok-reset-coupons.test.ts` mapped to category `"providers/xai"` in `scripts/test-layout/layout.json` and `tests/fixtures/test-layout-expected.json`.
+
+### Verified Upstream & Codebase Seams
+- **Bearer Token Resolution:** `src/oauth/index.ts:613` (`getValidAccessSnapshotForAccount("xai", accountId)`) with token refresh through `src/oauth/xai.ts:369` (`refreshXaiToken`).
+- **Header Constants:** `src/providers/xai-transport.ts:28-56` (`tokenAuth` header `"x-xai-token-auth": "xai-grok-cli"`).
+- **Operation Journaling & Deduplication:** UUIDv4 validation using `isCodexResetCreditOperationId` from `src/codex/reset-credit-recovery.ts:40`. Durable journaling in `src/grok/reset-coupon-ledger.ts` writes intent prior to upstream fetch and replays cached settlement when the same `operationId` is presented.
+
+---
+
+## 020 File Modifications & Exact Diffs
+
+### 1. NEW File: `src/server/management/grok-coupon-routes.ts`
+
+```typescript
+/**
+ * Management API handlers for Grok quota reset coupons.
+ *
+ * Exposes inspection and consumption of Grok billing reset coupons via gRPC-Web
+ * to Grok ConsumerUiSvc upstream endpoints.
+ *
+ * Inherits management authentication from requireManagementAuth in management-api.ts.
+ * Lazy-loaded by handleGrokCouponRoutesOnDemand to keep startup fast and honor the
+ * core-lab boundary contract.
+ */
+
+import { jsonResponse } from "../auth-cors";
+import type { ManagementContext } from "./context";
+import { isCodexResetCreditOperationId } from "../../codex/reset-credit-recovery";
+import { getValidAccessSnapshotForAccount } from "../../oauth";
+import { listAccounts, captureOAuthAccountSelection } from "../../oauth/store";
+import {
+  getGrokRemainingResets,
+  redeemGrokResetCoupon,
+  type GrokResetCoupon,
+} from "../../grok/reset-coupons";
+import {
+  openGrokResetCouponOperation,
+  recordGrokResetCouponSettlement,
+  type GrokResetCouponOperationRecord,
+} from "../../grok/reset-coupon-ledger";
+
+export interface GrokResetCouponsResponse {
+  accountId: string;
+  tokens: Array<{
+    tokenId: string;
+    validityStart: string;
+    validityEnd: string;
+  }>;
+  remaining: number;
+}
+
+export interface GrokConsumeCouponRequestBody {
+  accountId?: string;
+  tokenId?: string;
+  operationId?: string;
+}
+
+function resolveTargetAccountId(requestedAccountId?: string): string {
+  if (requestedAccountId && requestedAccountId.trim() !== "") {
+    return requestedAccountId.trim();
+  }
+  const selection = captureOAuthAccountSelection("xai");
+  if (selection?.accountId) {
+    return selection.accountId;
+  }
+  const accounts = listAccounts("xai");
+  if (accounts.length > 0) {
+    return accounts[0].id;
+  }
+  throw new Error("No xAI account found or active");
+}
+
+export async function handleGrokCouponRoutes(ctx: ManagementContext): Promise<Response | null> {
+  const { url, req, config } = ctx;
+  const { pathname } = url;
+
+  if (pathname === "/api/grok/reset-coupons") {
+    if (req.method !== "GET") {
+      return jsonResponse({ error: "Method not allowed" }, 405, req, config);
+    }
+
+    const queryAccountId = url.searchParams.get("accountId") ?? undefined;
+    let accountId: string;
+    try {
+      accountId = resolveTargetAccountId(queryAccountId);
+    } catch (err) {
+      return jsonResponse(
+        { error: { code: "no_account", message: err instanceof Error ? err.message : String(err) } },
+        400,
+        req,
+        config,
+      );
+    }
+
+    let tokenSnapshot;
+    try {
+      tokenSnapshot = await getValidAccessSnapshotForAccount("xai", accountId, { requireUsableAccount: true });
+    } catch (err) {
+      return jsonResponse(
+        { error: { code: "auth_failed", message: "Failed to resolve valid xAI credentials for account" } },
+        401,
+        req,
+        config,
+      );
+    }
+
+    try {
+      const remainingResult = await getGrokRemainingResets({
+        accessToken: tokenSnapshot.accessToken,
+      });
+
+      const payload: GrokResetCouponsResponse = {
+        accountId,
+        tokens: remainingResult.tokens.map((t) => ({
+          tokenId: t.tokenId,
+          validityStart: t.validityStart,
+          validityEnd: t.validityEnd,
+        })),
+        remaining: remainingResult.tokens.length,
+      };
+
+      return jsonResponse(payload, 200, req, config);
+    } catch (err) {
+      return jsonResponse(
+        { error: { code: "upstream_error", message: err instanceof Error ? err.message : String(err) } },
+        502,
+        req,
+        config,
+      );
+    }
+  }
+
+  if (pathname === "/api/grok/reset-coupons/consume") {
+    if (req.method !== "POST") {
+      return jsonResponse({ error: "Method not allowed" }, 405, req, config);
+    }
+
+    let body: GrokConsumeCouponRequestBody;
+    try {
+      body = (await req.json()) as GrokConsumeCouponRequestBody;
+    } catch {
+      return jsonResponse({ error: { code: "invalid_json", message: "Invalid JSON body" } }, 400, req, config);
+    }
+
+    const { accountId: rawAccountId, tokenId: requestedTokenId, operationId } = body;
+
+    if (operationId !== undefined && !isCodexResetCreditOperationId(operationId)) {
+      return jsonResponse(
+        { error: { code: "invalid_operation_id", message: "operationId must be a valid UUIDv4" } },
+        400,
+        req,
+        config,
+      );
+    }
+
+    let accountId: string;
+    try {
+      accountId = resolveTargetAccountId(rawAccountId);
+    } catch (err) {
+      return jsonResponse(
+        { error: { code: "no_account", message: err instanceof Error ? err.message : String(err) } },
+        400,
+        req,
+        config,
+      );
+    }
+
+    let tokenSnapshot;
+    try {
+      tokenSnapshot = await getValidAccessSnapshotForAccount("xai", accountId, { requireUsableAccount: true });
+    } catch (err) {
+      return jsonResponse(
+        { error: { code: "auth_failed", message: "Failed to resolve valid xAI credentials for account" } },
+        401,
+        req,
+        config,
+      );
+    }
+
+    // Journaling and Idempotency settlement check
+    const effectiveOpId = operationId ?? crypto.randomUUID();
+    const opRecord = openGrokResetCouponOperation({
+      accountId,
+      tokenId: requestedTokenId,
+      operationId: effectiveOpId,
+    });
+
+    if (opRecord.kind === "replay") {
+      return jsonResponse(
+        {
+          code: opRecord.code,
+          replayed: true,
+          tokenId: opRecord.tokenId,
+          settledAt: opRecord.settledAt,
+        },
+        200,
+        req,
+        config,
+      );
+    }
+
+    if (opRecord.kind === "identity-mismatch") {
+      return jsonResponse(
+        {
+          error: {
+            code: "operation_id_owned_by_another_account",
+            message: "Operation ID was previously registered with a different account or token",
+          },
+        },
+        409,
+        req,
+        config,
+      );
+    }
+
+    if (opRecord.kind !== "execute") {
+      return jsonResponse(
+        {
+          error: {
+            code: opRecord.kind,
+            message: "Coupon ledger capacity or unavailable failure",
+          },
+        },
+        503,
+        req,
+        config,
+      );
+    }
+
+    let resolvedTokenId = requestedTokenId;
+    if (!resolvedTokenId) {
+      try {
+        const remaining = await getGrokRemainingResets({ accessToken: tokenSnapshot.accessToken });
+        if (!remaining.tokens || remaining.tokens.length === 0) {
+          recordGrokResetCouponSettlement({
+            operationId: effectiveOpId,
+            code: "no_coupons_available",
+            status: "failed",
+          });
+          return jsonResponse(
+            { error: { code: "no_coupons_available", message: "No reset coupons available to redeem" } },
+            400,
+            req,
+            config,
+          );
+        }
+        resolvedTokenId = remaining.tokens[0].tokenId;
+      } catch (err) {
+        return jsonResponse(
+          { error: { code: "fetch_resets_failed", message: err instanceof Error ? err.message : String(err) } },
+          502,
+          req,
+          config,
+        );
+      }
+    }
+
+    try {
+      const redeemResult = await redeemGrokResetCoupon({
+        accessToken: tokenSnapshot.accessToken,
+        tokenId: resolvedTokenId,
+      });
+
+      recordGrokResetCouponSettlement({
+        operationId: effectiveOpId,
+        tokenId: resolvedTokenId,
+        code: "redeemed",
+        status: "success",
+      });
+
+      return jsonResponse(
+        {
+          success: true,
+          code: "redeemed",
+          replayed: false,
+          tokenId: resolvedTokenId,
+          accountId,
+          operationId: effectiveOpId,
+        },
+        200,
+        req,
+        config,
+      );
+    } catch (err) {
+      recordGrokResetCouponSettlement({
+        operationId: effectiveOpId,
+        tokenId: resolvedTokenId,
+        code: "redeem_failed",
+        status: "failed",
+      });
+      return jsonResponse(
+        { error: { code: "redeem_failed", message: err instanceof Error ? err.message : String(err) } },
+        502,
+        req,
+        config,
+      );
+    }
+  }
+
+  return null;
+}
+```
+
+---
+
+### 2. MODIFY File: `src/server/management/route-registry.ts`
+
+**Location:** Insert between line 133 (`POST /api/grok/apply`) and line 134 (`PUT /api/claude-code`).
+**Exact Diff:**
+
+```diff
+--- a/src/server/management/route-registry.ts
++++ b/src/server/management/route-registry.ts
+@@ -131,6 +131,8 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
+  { method: "GET", path: "/api/v2", module: "server/management/agent-settings-routes", mutates: false },
+  { method: "POST", path: "/api/claude-desktop/apply", module: "server/management/agent-settings-routes", mutates: true },
+  { method: "POST", path: "/api/grok/apply", module: "server/management/agent-settings-routes", mutates: true },
++  { method: "GET", path: "/api/grok/reset-coupons", module: "server/management/grok-coupon-routes", mutates: false },
++  { method: "POST", path: "/api/grok/reset-coupons/consume", module: "server/management/grok-coupon-routes", mutates: true },
+  { method: "PUT", path: "/api/claude-code", module: "server/management/agent-settings-routes", mutates: true },
+  { method: "PUT", path: "/api/claude-desktop", module: "server/management/agent-settings-routes", mutates: true },
+  { method: "PUT", path: "/api/codex-auth/features/default-mode-request-user-input", module: "server/management/agent-settings-routes", mutates: true },
+```
+
+---
+
+### 3. MODIFY File: `src/server/management-api.ts`
+
+**Location:** Around line 144 (after `handleQuotaResetRoutesOnDemand`) and line 243 (quota handler dispatched at 243, in the route dispatch chain).
+**Exact Diff:**
+
+```diff
+--- a/src/server/management-api.ts
++++ b/src/server/management-api.ts
+@@ -142,6 +142,12 @@ async function handleQuotaResetRoutesOnDemand(ctx: ManagementContext): Promise<R
+   const { handleQuotaResetRoutes } = await import("./management/quota-reset-routes");
+   return handleQuotaResetRoutes(ctx);
+ }
++
++async function handleGrokCouponRoutesOnDemand(ctx: ManagementContext): Promise<Response | null> {
++  if (!pathInManagementNamespace(ctx.url.pathname, "/api/grok/reset-coupons", true)) return null;
++  const { handleGrokCouponRoutes } = await import("./management/grok-coupon-routes");
++  return handleGrokCouponRoutes(ctx);
++}
+ 
+ export async function handleManagementAPI(
+   req: Request,
+@@ -242,4 +248,5 @@ export async function handleManagementAPI(
+    ??     (await handleRequestHistoryRoutes(ctx))
+    ??     (await handleQuotaResetRoutesOnDemand(ctx))
++    ??     (await handleGrokCouponRoutesOnDemand(ctx))
+    ??     (await handleRoutingAnalyticsRoutes(ctx))
+    ??     (await handleRoutingProfileRoutesOnDemand(ctx))
+```
+
+---
+
+### 4. MODIFY File: `src/cli/account-auth.ts`
+
+**Location:** Line 39 in `USAGE`, function `grokResetCoupons()` after line 302, and line 309 in `handleAccountAuthCommand()`.
+**Exact Diff:**
+
+```diff
+--- a/src/cli/account-auth.ts
++++ b/src/cli/account-auth.ts
+@@ -38,6 +38,7 @@ const USAGE = `Usage:
+   ocx account code <provider> [--flow <flow-id>] [--json]   (reads the code from stdin)
+   ocx account cancel <provider> [--flow <flow-id>] [--json]
+   ocx account reset-credits <account-id|main> [--consume --yes [--operation-id <uuid>]] [--json]
++  ocx account grok-reset-coupons [<account-id>] [--consume --yes [--token-id <token-id>] [--operation-id <uuid>]] [--json]
+ 
+ --device runs the OpenAI device-code login instead of the browser callback: use
+ it when the proxy has no browser or nothing can reach localhost:1455, such as a
+@@ -301,6 +302,37 @@ async function resetCredits(argv: string[], deps: RuntimeApiDeps): Promise<void>
+   printData(result, wantsJson);
+ }
+ 
++async function grokResetCoupons(argv: string[], deps: RuntimeApiDeps): Promise<void> {
++  const args = [...argv];
++  const rawId = args.shift()?.trim();
++  const wantsJson = takeFlag(args, "--json");
++  const consume = takeFlag(args, "--consume");
++  const yes = takeFlag(args, "--yes");
++  const tokenId = takeOption(args, "--token-id");
++  const operationId = takeOption(args, "--operation-id");
++
++  if (consume && !yes) throw new CliUsageError("consuming a Grok reset coupon requires --yes", USAGE);
++  if (operationId !== undefined && !consume) {
++    throw new CliUsageError("--operation-id requires --consume", USAGE);
++  }
++  if (tokenId !== undefined && !consume) {
++    throw new CliUsageError("--token-id requires --consume", USAGE);
++  }
++  if (operationId !== undefined && !isCodexResetCreditOperationId(operationId)) {
++    throw new CliUsageError("--operation-id must be a UUIDv4", USAGE);
++  }
++  rejectArgs(args, USAGE);
++
++  const accountId = rawId ? (rawId === "main" ? "__main__" : rawId) : undefined;
++  const result = consume
++    ? await runtimeRequest("/api/grok/reset-coupons/consume", {
++      method: "POST",
++      body: JSON.stringify({ accountId, tokenId, ...(operationId === undefined ? {} : { operationId }) }),
++    }, deps)
++    : await runtimeRequest(`/api/grok/reset-coupons${accountId ? `?accountId=${encodeURIComponent(accountId)}` : ""}`, {}, deps);
++  printData(result, wantsJson);
++}
++
+ export async function handleAccountAuthCommand(sub: string, argv: string[], deps: RuntimeApiDeps = {}): Promise<number | null> {
+   let action: (() => Promise<void>) | undefined;
+   if (sub === "login" || sub === "reauth") action = () => login(sub === "reauth" ? [...argv, "--reauth"] : argv, deps);
+   else if (sub === "code") action = () => code(argv, deps);
+   else if (sub === "cancel") action = () => cancel(argv, deps);
+   else if (sub === "reset-credits") action = () => resetCredits(argv, deps);
++  else if (sub === "grok-reset-coupons") action = () => grokResetCoupons(argv, deps);
+   if (!action) return null;
+   return runCliAction(action);
+ }
+```
+
+---
+
+### 5. MODIFY File: `src/cli/account.ts`
+
+**Location:** Line 62 in `ACCOUNT_USAGE` and line 358 in subcommands list.
+**Exact Diff:**
+
+```diff
+--- a/src/cli/account.ts
++++ b/src/cli/account.ts
+@@ -60,6 +60,7 @@ Usage:
+   ocx account code <provider> [--flow <flow-id>] [--json]   (reads the code from stdin)
+   ocx account cancel <provider> [--flow <flow-id>] [--json]
+   ocx account reset-credits <account-id|main> [--consume --yes] [--json]
++  ocx account grok-reset-coupons [<account-id>] [--consume --yes] [--token-id <token-id>] [--json]
+   ocx account main <doctor|list|register|add|switch|recover> ...
+ 
+ List and switch provider accounts and API-key pools (masked output only).
+@@ -355,7 +356,7 @@ export async function handleAccountCommand(argv: string[], deps: RuntimeApiDeps
+       const { cmdNativeMainAccount } = await import("./account-main");
+       return await cmdNativeMainAccount(rest, deps);
+     }
+-    if (["login", "reauth", "code", "cancel", "reset-credits"].includes(sub ?? "")) {
++    if (["login", "reauth", "code", "cancel", "reset-credits", "grok-reset-coupons"].includes(sub ?? "")) {
+       const { handleAccountAuthCommand } = await import("./account-auth");
+       return await handleAccountAuthCommand(sub!, rest, deps) ?? 1;
+     }
+```
+
+---
+
+### 6. MODIFY File: `src/cli/registry.ts`
+
+**Location:** Line 224 (`usage`) and line 236 (`details`).
+**Exact Diff:**
+
+```diff
+--- a/src/cli/registry.ts
++++ b/src/cli/registry.ts
+@@ -221,7 +221,7 @@ export const ROOT_COMMANDS: readonly CommandSpec[] = [
+   },
+   {
+     name: "account",
+-    usage: "ocx account <list|current|use|refresh|auto-switch|priority|login|reauth|code|cancel|remove|add-key|reset-credits|main> ...",
++    usage: "ocx account <list|current|use|refresh|auto-switch|priority|login|reauth|code|cancel|remove|add-key|reset-credits|grok-reset-coupons|main> ...",
+     summary: "List and switch provider accounts and API-key pools (GUI parity).",
+     details: [
+       "list [provider]     Codex account pool, OAuth accounts and API keys (identifiers shown masked as the API returns them).",
+@@ -234,6 +234,7 @@ export const ROOT_COMMANDS: readonly CommandSpec[] = [
+       "add-key <provider> [--label <label>]  Add a key read only from piped stdin.",
+       "login/reauth/code/cancel  Run browser or manual-code auth from a headless shell.",
+       "reset-credits <id|main> [--consume --yes]  Inspect or consume Codex reset credits.",
++      "grok-reset-coupons [<id>] [--consume --yes] Inspect or redeem Grok reset coupons.",
+       "main <subcommand>     Manage the physical native Codex login separately from Pool routing.",
+       "Switching the active account takes effect immediately; running threads move on their next request, and in-flight requests keep the account they captured.",
+       "A selection-order change applies from the next unbound request and never moves a bound thread.",
+```
+
+---
+
+### 7. NEW File & Test Layout Registration
+
+#### File: `tests/providers/xai/grok-reset-coupons.test.ts`
+Tests management routes and CLI operations:
+- Mocking upstream `GetRemainingResets` (empty request body -> returns repeated tokens).
+- Mocking upstream `RedeemReset` (proto message with `tokenId` string field 1).
+- Validating UUIDv4 rejection on invalid `--operation-id`.
+- Validating `--yes` requirement when `--consume` is set.
+- Replay test: verifying identical `operationId` yields `{ replayed: true }` without second upstream fetch.
+
+#### MODIFY File: `scripts/test-layout/layout.json`
+Insert into the explicit map around line 701:
+
+```diff
+--- a/scripts/test-layout/layout.json
++++ b/scripts/test-layout/layout.json
+@@ -699,6 +699,7 @@
+     "grok-models-effort-list.test.ts": "providers/xai",
+     "grok-orphan-adoption.test.ts": "providers/xai",
++    "grok-reset-coupons.test.ts": "providers/xai",
+     "grok-selection.test.ts": "providers/xai",
+     "grok-status.test.ts": "providers/xai",
+```
+
+#### MODIFY File: `tests/fixtures/test-layout-expected.json`
+Insert alphabetically:
+
+```diff
+--- a/tests/fixtures/test-layout-expected.json
++++ b/tests/fixtures/test-layout-expected.json
+@@ -532,6 +532,7 @@
+   "grok-management-api.test.ts": "providers/xai",
+   "grok-models-effort-list.test.ts": "providers/xai",
+   "grok-orphan-adoption.test.ts": "providers/xai",
++  "grok-reset-coupons.test.ts": "providers/xai",
+   "grok-selection.test.ts": "providers/xai",
+   "grok-status.test.ts": "providers/xai",
+   "grok-sync.test.ts": "providers/xai",
+```
+
+---
+
+## 030 Acceptance Criteria & Verifier Commands
+
+1. **Route Dispatch Invariant:**
+   - Command: `bun test tests/lab/core-lab-boundary.test.ts`
+   - Verification: Confirming `src/server/management-api.ts` does not statically import `grok-coupon-routes.ts`.
+2. **Test Layout Integrity:**
+   - Command: `bun test tests/test-layout.test.ts tests/test-layout-tooling.test.ts`
+   - Verification: Validates `scripts/test-layout/layout.json` matches test directories and `test-layout-expected.json`.
+3. **CLI Usage & Flag Enforcements:**
+   - Command: `ocx account grok-reset-coupons --consume` (without `--yes`) exits with code 1 and error message `consuming a Grok reset coupon requires --yes`.
+   - Command: `ocx account grok-reset-coupons --operation-id invalid-uuid --consume --yes` exits with code 1 and error message `--operation-id must be a UUIDv4`.
+4. **Idempotency & Journaling Execution:**
+   - Test: `bun test tests/providers/xai/grok-reset-coupons.test.ts` passes all read, consume, validation, and replay assertions.
diff --git a/devlog/_plan/260912_grok_reset_coupons/030_phase3_delivery.md b/devlog/_plan/260912_grok_reset_coupons/030_phase3_delivery.md
new file mode 100644
index 0000000000..a89db8f8ee
--- /dev/null
+++ b/devlog/_plan/260912_grok_reset_coupons/030_phase3_delivery.md
@@ -0,0 +1,211 @@
+# PRD: Grok Reset Coupons — Phase 3 Delivery, Documentation & Release Runbook
+
+This document details Phase 3 of the Grok reset coupons feature: documentation site updates across the relevant page families, devlog lifecycle transition to `devlog/_fin`, pre-commit verification runbooks, and GitHub PR delivery protocols targeting the `dev` branch.
+
+---
+
+## 010 Documentation Site Updates
+
+The Grok reset coupons capability introduces both a new CLI command under `ocx account` and new Management API endpoints. These must be documented within the existing documentation site structure under `docs-site/src/content/docs/`.
+
+### 1. File: `docs-site/src/content/docs/reference/cli/providers-accounts.md`
+
+#### Section: `## Accounts and key pools` (heading at providers-accounts.md:137) -> `### ocx account <subcommand>`
+- **Line Anchor:** After line 221 (`reset-credits <id|main>`).
+- **Update Content:** Add description of `grok-reset-coupons`:
+  ```markdown
+  grok-reset-coupons [<id>] [--consume --yes] [--token-id <token-id>] [--operation-id <uuid>]  Inspect or redeem Grok reset coupons.
+  ```
+
+#### Section: Detailed Subcommand Entry (after line 457; backtick-fenced heading pattern `### \`ocx account reset-credits <id|main> [--consume --yes]\`` at line 446; the entry must also be added to the `Usage:` enumeration inside the code block at line 210 and the usage list at line 221)
+- **Update Content:** Add comprehensive usage instructions mirroring `reset-credits`:
+  ```markdown
+  ### `ocx account grok-reset-coupons [<account-id>] [--consume --yes [--token-id <id>] [--operation-id <uuid>]] [--json]`
+
+  Inspects remaining reset coupons or redeems one for an xAI / Grok account.
+
+  When invoked without `--consume`, returns the available coupon tokens and validity windows:
+
+  ```bash
+  ocx account grok-reset-coupons
+  ocx account grok-reset-coupons acc_xai_01 --json
+  ```
+
+  Redeeming a reset coupon mutates billing state and permanently exhausts one coupon token. `--consume` strictly requires `--yes`:
+
+  ```bash
+  ocx account grok-reset-coupons --consume --yes
+  ocx account grok-reset-coupons --consume --yes --token-id <token-id>
+  ```
+
+  Pass `--operation-id <uuid>` (must be a valid UUIDv4) to guarantee idempotent settlement. If the network drops or the command is retried, identical operation IDs replay the durably recorded outcome instead of consuming a second coupon.
+  ```
+
+---
+
+### 2. File: `docs-site/src/content/docs/reference/management-api.md`
+
+#### Section: Endpoint Table — under `### Agent and client settings` (line 69); the existing `/api/grok` rows live at lines 78-80 and the new rows stay adjacent to them (the dedicated `### Providers` section at line 343 is NOT the target)
+- **Update Content:** Register both HTTP control plane endpoints:
+  ```markdown
+  | `GET /api/grok/reset-coupons?accountId=...` | Read remaining Grok billing reset tokens and validity windows for the active or specified xAI account | 400 missing account; 401 unauthenticated; 502 upstream gRPC-Web error |
+  | `POST /api/grok/reset-coupons/consume` | Redeem an eligible reset coupon. Body `{ accountId?, tokenId?, operationId? }`. Optional `operationId` (UUIDv4) makes redemption idempotent: repeating the same ID replays the durable result without double-redemption. | 400 invalid JSON/UUID; 401 unauthenticated; 409 `identity_mismatch`; 502 upstream error; 503 ledger capacity |
+  ```
+
+---
+
+### 3. File: `structure/providers/xai-grok.md` (structure SoT for the xAI grok provider)
+
+#### Section: append under `## xAI Grok hardening (official Grok Build contract parity)` (the file's only section heading; gate with `bun run structure:check`)
+- **Update Content:** Document the gRPC-Web transport and reset coupon mechanics:
+  ```markdown
+  ### Grok Reset Coupons (Billing API Parity)
+  - **Upstream RPCs:** `prod_mc_billing.ConsumerUiSvc/GetRemainingResets` (inspection) and `prod_mc_billing.ConsumerUiSvc/RedeemReset` (redemption).
+  - **Transport:** Binary gRPC-Web over HTTP/1.1 or HTTP/2 with 5-byte frame envelope (`0x00` data / `0x80` trailers) and protobuf wire format. Plain JSON is rejected with empty responses upstream.
+  - **Authentication:** `Authorization: Bearer <xai OIDC access token>` + `X-XAI-Token-Auth: xai-grok-cli`. No cookies required.
+  - **Safety & Idempotency:** Managed via `src/grok/reset-coupon-ledger.ts` using UUIDv4 operation tracking before upstream dispatch to prevent duplicate consumption during network flakes.
+  ```
+
+---
+
+## 020 Devlog Lifecycle & Promotion Note
+
+Upon landing all Phase 1 and Phase 2 changes on `dev`, promote the planning directory to finished status:
+
+- **Source:** `devlog/_plan/260912_grok_reset_coupons/`
+- **Destination:** `devlog/_fin/260912_grok_reset_coupons/`
+- **Action:** Move the directory and add `000_fin_summary.md` documenting:
+  1. Live verification against `grok.com/prod_mc_billing.ConsumerUiSvc`.
+  2. gRPC-Web binary client and framing implementation.
+  3. CLI parity with `ocx account grok-reset-coupons`.
+  4. Test suite validation under `tests/providers/xai/grok-reset-coupons.test.ts`.
+
+---
+
+## 025 Locale Sync Scope (docs-sync rule)
+
+Both documentation targets exist in **seven translated locales**: `fr`, `ja`, `ko`, `ru`, `tr`, `zh-cn`, `zh-tw`
+(verified by direct file-existence check this session). Per the repository docs-sync rule, every update made to
+`docs-site/src/content/docs/reference/cli/providers-accounts.md` and
+`docs-site/src/content/docs/reference/management-api.md` must be applied to all seven locale variants of both files:
+same sections (Usage enumeration line, usage list line, detailed subcommand entry; endpoint matrix rows), translated
+prose kept consistent with each locale's existing register. The guide page `guides/grok-build.md` (root + locales)
+gains a short "Reset coupons" pointer only if its current content already covers account quota surfaces.
+
+---
+
+## 030 Verification Runbook
+
+Before opening the GitHub Pull Request, run the complete verification suite locally:
+
+```bash
+# 1. Typecheck entire workspace
+bun run typecheck
+
+# 2. Test layout validation (ensures layout.json matches expected fixtures)
+bun test tests/test-layout.test.ts tests/test-layout-tooling.test.ts
+
+# 3. Core-lab boundary test (ensures no eager imports in management-api.ts)
+bun test tests/lab/core-lab-boundary.test.ts
+
+# 4. Domain & management test suite for Grok reset coupons
+bun test tests/providers/xai/grok-reset-coupons.test.ts
+
+# 5. Full test suite execution
+bun run test
+
+# 6. Privacy and secret leakage scanner
+bun run privacy:scan
+
+# 7. Structure SSOT gate (structure/providers/xai-grok.md)
+bun run structure:check
+```
+
+
+All commands must exit `0` cleanly with zero type errors, zero layout mismatches, and zero secrets detected.
+
+---
+
+## 040 GitHub Delivery Runbook
+
+### 1. Issue Creation: Feature Request
+Create an issue using `.github/ISSUE_TEMPLATE/feature_request.yml`. Must strictly include the exact section headings:
+
+```markdown
+### Area
+Provider adapters
+
+### What are you trying to accomplish?
+Allow operators and CLI users to inspect and redeem Grok billing reset coupons directly through OpenCodex. When an xAI / Grok account reaches rate limits or quota boundaries, eligible reset tokens can be inspected and redeemed without leaving the terminal or dashboard.
+
+### What prevents this today?
+Currently, OpenCodex only provides quota reset credit inspection and consumption for Codex/ChatGPT accounts (`/api/codex-auth/reset-credits` and `ocx account reset-credits`). Grok reset coupons use gRPC-Web binary framing against `prod_mc_billing.ConsumerUiSvc` and have no management API or CLI interface.
+
+### What should OpenCodex do?
+1. Expose `GET /api/grok/reset-coupons` to inspect available reset tokens and validity windows.
+2. Expose `POST /api/grok/reset-coupons/consume` to redeem coupons with durable UUIDv4 operation idempotency.
+3. Provide `ocx account grok-reset-coupons [--consume --yes]` CLI command matching the behavior and safety flags of `reset-credits`.
+
+### Example usage or interface
+```bash
+# Inspect available Grok reset tokens
+ocx account grok-reset-coupons
+
+# Redeem coupon with confirmation and idempotency
+ocx account grok-reset-coupons --consume --yes --operation-id 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
+```
+
+### Alternatives or workarounds
+Manually inspecting and redeeming coupons in a web browser using devtools network payloads.
+
+### Additional context
+Verified against live `grok.com` endpoints:
+- `prod_mc_billing.ConsumerUiSvc/GetRemainingResets`
+- `prod_mc_billing.ConsumerUiSvc/RedeemReset`
+Requires gRPC-Web binary framing (`application/grpc-web+proto`) with `X-XAI-Token-Auth: xai-grok-cli`.
+
+### Checks
+- [x] I searched existing issues and documentation.
+- [x] This request describes a concrete OpenCodex workflow rather than merely naming a desired technology.
+- [x] I removed secrets and personal data.
+```
+
+---
+
+### 2. Pull Request: Submission & Template
+Submit PR using `.github/PULL_REQUEST_TEMPLATE.md` targeting branch **`dev`** (NEVER target `main` directly).
+
+```markdown
+## Summary
+
+- Adds Grok billing reset coupon inspection and redemption support via gRPC-Web upstream client.
+- Implements `GET /api/grok/reset-coupons` and `POST /api/grok/reset-coupons/consume` with lazy on-demand route loading in `src/server/management-api.ts`.
+- Adds `ocx account grok-reset-coupons` CLI command mirroring `reset-credits` with required `--yes` on `--consume` and UUIDv4 `--operation-id` journaling.
+- Adds test coverage in `tests/providers/xai/grok-reset-coupons.test.ts` and updates test layout registrations.
+
+Closes #<ISSUE_NUMBER>
+
+## Verification
+
+- `bun run typecheck` passed cleanly.
+- `bun test tests/test-layout.test.ts tests/test-layout-tooling.test.ts` verified test suite mappings.
+- `bun test tests/lab/core-lab-boundary.test.ts` passed (no lazy import leaks).
+- `bun run structure:check` passed (structure/providers/xai-grok.md anchor).
+- `bun test tests/providers/xai/grok-reset-coupons.test.ts` passed all read, redeem, and replay cases.
+- `bun run privacy:scan` passed with no secrets detected.
+
+## Checklist
+
+- [x] Scope stays focused and avoids unrelated cleanup.
+- [x] Docs or release notes were updated when needed.
+- [x] Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.
+```
+
+---
+
+### 3. Maintainer Landing & Issue Closure Policies
+
+- **Target Branch:** PR must target `dev`. OpenCodex CI triggers on PRs against `dev`.
+- **Exact-Head CI Requirement:** Maintainers require all CI checks on the exact tip of the PR branch to pass green before merging.
+- **Merge Policy:** Merges into `dev` are performed by maintainers using squash-and-merge or rebase per project conventions.
+- **Manual Issue Closure Note:** Because GitHub only auto-closes issues referenced in commit messages (`Closes #N`) when merged into the repository default branch (`main`), merging into `dev` does **not** automatically close the issue. Maintainers or authors must manually close the issue after verifying the commit has landed on `dev`.
diff --git a/devlog/_plan/260912_history_containment/000_plan.md b/devlog/_plan/260912_history_containment/000_plan.md
new file mode 100644
index 0000000000..2c88e794d7
--- /dev/null
+++ b/devlog/_plan/260912_history_containment/000_plan.md
@@ -0,0 +1,28 @@
+# History containment and continuation review
+
+This unit carries the paginated-history refusal from #4313 onto current dev, evaluates #4086 and #3663 as separate product slices, and keeps unresolved #4311/#3522 acceptance explicit.
+
+Loop: satisfy-spec HOTL. Trigger: delegated history lane. Scope: this worktree, three source PRs, two issues. No local product tests/build/typecheck/install; no merge, native stack, release, service/config changes, native ordinal allocation or damaged-history rewriting. Git/gh credentials already available are the only external scope. No user time/token/agent cap.
+
+Verification: source/diff review now; final cumulative tip GitHub hosted CI later. Local suites NOT RUN. `git diff --check` checks patch whitespace only, not runtime behavior. Stop: reviewable carry PRs and final-tip hosted evidence plus explicit unresolved acceptance, or actual capability failure recorded without fabricated approval.
+
+Evidence: .tmp/history-lane/ and this unit. Security drafts stay in scratch. Escalation: actual tool denials/access failures are recorded; independent work continues. Main implements; read-only reviewers cannot change source. Architect native role is absent from the exposed schema; no registration/config changes authorized or attempted. The user explicitly authorizes supported inherited-model independent design review and reflection plus a separate A reviewer; both are dispatched without claiming a native architect role.
+
+## Work phases
+
+0. Docs-only roadmap, lock the source-pinned diff designs below.
+1. Containment carry #4313: rollout guards, injection compensation, focused regression source, eight locale guides and owning structure docs.
+2. Continuation slice #4086 disposition/carry: custom-tool replay guard and HTTP/WebSocket regressions. Independent of containment; branch from dev if adopted.
+3. Experimental relay #3663 disposition: security/owner review and injection overlap. A carry is conditional on justified safe amendments; new unpublished security details remain scratch. If not acceptable, preserve exact blockers for parent rather than silently dropping the slice.
+4. #3522 evidence disposition and final hosted CI verification/repair. Diagnostics #3790 already landed; no generic diagnostic rewrite. Same-process Windows recovery remains unproven absent genuine evidence.
+
+## Acceptance
+
+#4311 containment only: ordinal/history_mode records and migratable stores refuse external relabel; config/profile/journal preserved on refusal and compensation failure remains visible. Legacy writes preserve descriptor identity. Native writer support and damaged recovery remain open.
+#4086: replay miss on selected stateless/lowered-custom destination returns previous_response_not_found before dispatch; replayed complete history remains paired and reasoning preserved. Native continuation semantics stay intact.
+#3663: authenticated owner-bound relay must not mix credentials/accounts; explicit feature gating and existing injection refusal coexist. Maintainer security approval is a separate merge gate.
+#3522: current issue comments govern; healthy separate-process probes do not prove same-process recovery.
+
+## Delivery topology
+
+Use ordinary independent dev PRs for unrelated slices. Only a later repair of one slice depends on its own carry. Shared file edits do not by themselves imply dependency. Parent alone merges. Preserve source authors using Co-authored-by trailers. Readiness remains draft until final hosted and review evidence is recorded.
diff --git a/devlog/_plan/260912_history_containment/010_containment.md b/devlog/_plan/260912_history_containment/010_containment.md
new file mode 100644
index 0000000000..2c39a583eb
--- /dev/null
+++ b/devlog/_plan/260912_history_containment/010_containment.md
@@ -0,0 +1,1155 @@
+# Containment source-pinned change design
+
+Source: PR #4313 at 676b97ff1314b24f5da9949732bfad45809f2eae. Initial carry uses the following public diff, revalidated against current dev at phase P. Every diff header is the exact NEW/MODIFY file map. Main resolves conflicts against current owners; no wholesale replacement from a stale head.
+
+Before: current merge-base behavior in removed lines. After: added lines below. Tests are authored but NOT RUN locally; final-tip hosted CI observes these files. No new dependency or persisted schema is introduced by containment/continuation; relay owner state remains bounded/process-local and needs separate security review.
+
+Activation: synthetic ordinal-bearing session_meta; history_mode DB columns including legacy rows; migration between preflight and artifact completion; config restoration failure; rollout replacement before first-line patch/append. Observe refusal, byte-identical preimages and no DB provider transition. Containment tier is runtime validation; executing surface history-provider/inject; native concurrent writer can bypass cross-process scheduling checks; residual race remains; wording is defensive containment, final native-writer lock: none.
+
+Current-dev adaptation: source/tests/locale hunks are applied as scoped diffs; eight structure additions are appended to their current owning docs without replacing existing sections. `git apply --check --exclude=structure/*` validates patch shape only. This is not a product test.
+
+```diff
+diff --git a/docs-site/src/content/docs/fr/guides/codex-integration.md b/docs-site/src/content/docs/fr/guides/codex-integration.md
+index e8a4deae4f..68af97b7b4 100644
+--- a/docs-site/src/content/docs/fr/guides/codex-integration.md
++++ b/docs-site/src/content/docs/fr/guides/codex-integration.md
+@@ -416,3 +416,9 @@ ocx restore back # point plain Codex at the running proxy again
+ Lorsque opencodex s'exécute comme [service d'arrière-plan géré](/fr/reference/cli/lifecycle/#ocx-service-installrepairstartstopstatusuninstallremove), il définit
+ `OCX_SERVICE=1` afin qu'un redémarrage déclenché par le service ne modifie **pas** sans cesse la configuration
+ Codex. Seule l'exécution explicite de `ocx stop` ou `ocx service stop` restaure Codex natif.
++
++## Refus de sécurité pour l’historique paginé
++
++Une transition de fournisseur peut renvoyer `history_paginated_requires_native_writer` si le stockage concerné prend en charge la pagination, même pour ses lignes legacy. OpenCodex conserve configuration, profil, catalogue, historique et preuves de restauration au lieu d’attribuer des numéros hors de Codex. Les sorties sans transition, comme la préservation d’un fournisseur externe, restent disponibles.
++
++Ne supprimez pas un fournisseur encore référencé, ne répétez pas `ocx sync` ou une restauration legacy et ne réécrivez pas un historique actif. Conservez les fichiers, fermez la conversation avant toute récupération et signalez l’erreur exacte et les versions sans publier de données privées. Utilisez un correctif vérifié coordonné avec le processus natif d’écriture. Une sauvegarde ou le succès d’un script ne prouve pas le rétablissement de l’affichage : vérifiez la conversation après réouverture de Codex.
+diff --git a/docs-site/src/content/docs/guides/codex-integration.md b/docs-site/src/content/docs/guides/codex-integration.md
+index a99b880fc1..f36d7b0a70 100644
+--- a/docs-site/src/content/docs/guides/codex-integration.md
++++ b/docs-site/src/content/docs/guides/codex-integration.md
+@@ -772,3 +772,9 @@ injection. Explicit external-provider opt-out behavior is unchanged.
+ In **Subagents → Delegation settings**, edit the ordered fallback chain and its availability polling interval (5000–600000 ms), then save it separately from the featured roster. A configured target that is no longer advertised remains in the chain until you remove it. The roster and fallback chain are separate settings; this editor does not make the roster replace the fallback policy.
+
+ When a routed preferred model may receive V2 work from a native ChatGPT parent, the panel explains the upstream encrypted-task limitation. Readable tasks from routed parents are unaffected. The guidance uses `/api/v2` mode and native V1 pin state; the current API does not expose recovery activation or request-specific eligibility, so the panel reports those as unknown. V1/plaintext-compatible delegation remains an alternative. Experimental V2 recovery, where eligible and explicitly enabled, adds quota usage, latency, backend dependence and possible fidelity loss; it does not repair the upstream protocol. See [sub-agent surfaces](/guides/sub-agent-surface/) and [the upstream limitation](https://github.com/lidge-jun/opencodex/issues/92).
++
++## Paginated history safety refusal
++
++When an affected history store supports paginated records, a provider transition may return `history_paginated_requires_native_writer`. OpenCodex preserves the current configuration, profile, catalog, rollout and restore provenance instead of assigning ordinals outside Codex. This includes legacy rows in a migration-capable store. No-transition exits, such as preserving an external provider, remain available.
++
++Do not delete a provider definition still referenced by a conversation, repeatedly run `ocx sync` or legacy recovery, or rewrite an active rollout to work around this refusal. Keep the current files, close the affected conversation before any recovery, and report the exact error and versions without uploading private history. Use a verified fix with native-writer coordination; a backup or a successful script alone does not prove the conversation is visible again. Check the restored conversation in Codex after reopening.
+diff --git a/docs-site/src/content/docs/ja/guides/codex-integration.md b/docs-site/src/content/docs/ja/guides/codex-integration.md
+index 4ce54074d3..9fb892e763 100644
+--- a/docs-site/src/content/docs/ja/guides/codex-integration.md
++++ b/docs-site/src/content/docs/ja/guides/codex-integration.md
+@@ -280,3 +280,9 @@ ocx restore back # point plain Codex at the running proxy again
+ ```
+
+ opencodex が管理対象 [バックグラウンドサービス](/reference/cli/#ocx-service) として実行される場合、`OCX_SERVICE=1` が設定されるため、サービス主導の再起動によって Codex 設定がスラッシングされなくなります。明示的な `ocx stop` / `ocx service stop` のみがネイティブ Codex を復元します。
++
++## ページ分割履歴の保護による拒否
++
++対象の履歴ストアがページ分割をサポートする場合、プロバイダー変更は `history_paginated_requires_native_writer` で拒否されることがあります。Codex の外で番号を割り当てず、設定、プロファイル、カタログ、履歴ファイル、復元情報を保持します。移行可能なストアの legacy 行も対象です。外部プロバイダーを保持するだけの経路は利用できます。
++
++会話が参照するプロバイダー定義を削除したり、`ocx sync` や旧式の復元を繰り返したり、使用中の履歴を書き換えたりしないでください。ファイルを保持し、復元前に対象の会話を閉じ、個人の履歴を公開せず正確なエラーとバージョンを報告してください。ネイティブの書き込み処理と連携する検証済みの修正が必要です。バックアップやスクリプトの成功だけでは表示の復元は証明されません。再度開いた Codex で確認してください。
+diff --git a/docs-site/src/content/docs/ko/guides/codex-integration.md b/docs-site/src/content/docs/ko/guides/codex-integration.md
+index 584e77adb0..7ae5a2aa09 100644
+--- a/docs-site/src/content/docs/ko/guides/codex-integration.md
++++ b/docs-site/src/content/docs/ko/guides/codex-integration.md
+@@ -291,3 +291,9 @@ ocx restore back # point plain Codex at the running proxy again
+ ```
+
+ opencodex가 managed [background service](/reference/cli/#ocx-service)로 실행될 때는 `OCX_SERVICE=1`을 설정하므로 service-driven restart가 Codex config를 흔들지 **않습니다**. 네이티브 Codex를 복원하는 것은 명시적인 `ocx stop` / `ocx service stop`뿐입니다.
++
++## 페이지 분할 기록 보호에 따른 거부
++
++영향받는 기록 저장소가 페이지 분할을 지원하면 프로바이더 전환이 `history_paginated_requires_native_writer`로 거부될 수 있습니다. OpenCodex는 Codex 밖에서 순번을 지정하는 대신 현재 설정, 프로필, 카탈로그, 대화 원본과 복원 근거를 보존합니다. 변환 가능한 저장소의 `legacy` 행도 포함됩니다. 외부 프로바이더 보존처럼 전환을 하지 않는 경로는 계속 사용할 수 있습니다.
++
++대화가 참조하는 프로바이더 정의를 삭제하거나, `ocx sync`·레거시 복구를 반복하거나, 실행 중인 대화 원본을 고쳐 우회하지 마세요. 현재 파일을 보존하고 복구 전에 해당 대화를 닫은 뒤, 개인 대화 내용을 올리지 말고 정확한 오류와 버전을 보고하세요. 네이티브 기록 작성자와 조정하는 검증된 수정이 필요합니다. 백업이나 스크립트 성공만으로 표시 복구가 증명되지는 않으므로 Codex를 다시 열어 확인하세요.
+diff --git a/docs-site/src/content/docs/ru/guides/codex-integration.md b/docs-site/src/content/docs/ru/guides/codex-integration.md
+index e695830370..f23b7543a4 100644
+--- a/docs-site/src/content/docs/ru/guides/codex-integration.md
++++ b/docs-site/src/content/docs/ru/guides/codex-integration.md
+@@ -409,3 +409,9 @@ ocx restore back # point plain Codex at the running proxy again
+ Когда opencodex работает как управляемая [фоновая служба](/reference/cli/#ocx-service), он
+ устанавливает `OCX_SERVICE=1`, чтобы service-driven restart **не** дёргал конфигурацию Codex —
+ только явный `ocx stop` / `ocx service stop` восстанавливает нативный Codex.
++
++## Защитный отказ для постраничной истории
++
++Если затронутое хранилище поддерживает постраничную историю, смена провайдера может вернуть `history_paginated_requires_native_writer`, в том числе для строк legacy. OpenCodex сохраняет конфигурацию, профиль, каталог, историю и данные восстановления, не назначая номера вне Codex. Пути без смены провайдера, например сохранение внешнего провайдера, остаются доступны.
++
++Не удаляйте используемое разговором определение провайдера, не повторяйте `ocx sync` или legacy-восстановление и не переписывайте активную историю. Сохраните файлы, закройте разговор перед восстановлением и сообщите точную ошибку и версии без публикации личной истории. Требуется проверенное исправление с согласованием с нативным процессом записи. Наличие резервной копии или успешный скрипт не доказывает восстановление отображения: проверьте разговор после повторного открытия Codex.
+diff --git a/docs-site/src/content/docs/tr/guides/codex-integration.md b/docs-site/src/content/docs/tr/guides/codex-integration.md
+index 23b9b87f2e..501f05d8c9 100644
+--- a/docs-site/src/content/docs/tr/guides/codex-integration.md
++++ b/docs-site/src/content/docs/tr/guides/codex-integration.md
+@@ -467,3 +467,9 @@ opencodex yönetilen bir [arka plan servisi](/tr/reference/cli/#ocx-service)
+ olarak çalıştığında `OCX_SERVICE=1` ayarlar, böylece servis odaklı bir yeniden
+ başlatma Codex yapılandırmasını **bozmaz** — yalnızca açık bir `ocx stop` / `ocx
+ service stop` yerel Codex'i geri yükler.
++
++## Sayfalanmış geçmiş için güvenlik reddi
++
++Etkilenen geçmiş deposu sayfalamayı destekliyorsa sağlayıcı değişimi `history_paginated_requires_native_writer` döndürebilir; legacy satırlar da buna dahildir. OpenCodex, Codex dışında sıra numarası atamak yerine yapılandırmayı, profili, kataloğu, geçmişi ve geri yükleme kanıtlarını korur. Harici sağlayıcıyı korumak gibi değişim yapmayan yollar kullanılabilir.
++
++Konuşmanın kullandığı sağlayıcı tanımını silmeyin, `ocx sync` veya legacy kurtarmayı tekrarlamayın ve etkin geçmişi yeniden yazmayın. Dosyaları koruyun, kurtarmadan önce konuşmayı kapatın ve özel geçmişi yayımlamadan tam hatayı ve sürümleri bildirin. Yerel yazıcıyla koordineli, doğrulanmış bir düzeltme gerekir. Yedek veya başarılı betik görüntünün düzeldiğini kanıtlamaz; Codex’i yeniden açıp konuşmayı kontrol edin.
+diff --git a/docs-site/src/content/docs/zh-cn/guides/codex-integration.md b/docs-site/src/content/docs/zh-cn/guides/codex-integration.md
+index 71d2b81473..37c12243f8 100644
+--- a/docs-site/src/content/docs/zh-cn/guides/codex-integration.md
++++ b/docs-site/src/content/docs/zh-cn/guides/codex-integration.md
+@@ -353,3 +353,9 @@ ocx restore back # point plain Codex at the running proxy again
+ 当 opencodex 作为受管的 [background service](/reference/cli/#ocx-service) 运行时，它会设置
+ `OCX_SERVICE=1`，这样由服务驱动的重启**不会**反复改写 Codex config——只有显式的
+ `ocx stop` / `ocx service stop` 才会恢复原生 Codex。
++
++## 分页历史记录安全拒绝
++
++如果受影响的历史存储支持分页，提供商切换可能返回 `history_paginated_requires_native_writer`。OpenCodex 会保留当前配置、配置档、模型目录、历史文件及恢复依据，而不是在 Codex 之外分配序号；可迁移存储中的 legacy 记录也受保护。仅保留外部提供商而不执行切换的路径仍然可用。
++
++不要删除会话仍在引用的提供商定义、反复运行 `ocx sync` 或旧版恢复，也不要改写正在使用的历史文件来绕过拒绝。保留文件，在恢复前关闭相关会话，并只报告准确的错误和版本，不要公开私人历史。需要与原生写入器协调的已验证修复。备份或脚本成功并不能证明显示已恢复；重新打开 Codex 后检查会话。
+diff --git a/docs-site/src/content/docs/zh-tw/guides/codex-integration.md b/docs-site/src/content/docs/zh-tw/guides/codex-integration.md
+index c9f8090987..c24cd53d09 100644
+--- a/docs-site/src/content/docs/zh-tw/guides/codex-integration.md
++++ b/docs-site/src/content/docs/zh-tw/guides/codex-integration.md
+@@ -360,3 +360,9 @@ ocx restore back # 讓普通 Codex 再次指向仍在執行的 proxy
+ 當 opencodex 作為受管的 [背景服務](/zh-tw/reference/cli/#ocx-service) 執行時，會設定 `OCX_SERVICE=1`，
+ 因此 service 驅動的 restart **不會**反覆改寫 Codex 設定；只有明確執行 `ocx stop` 或
+ `ocx service stop` 才會恢復原生 Codex。
++
++## 分頁歷史記錄安全拒絕
++
++如果受影響的歷史儲存區支援分頁，提供者切換可能傳回 `history_paginated_requires_native_writer`。OpenCodex 會保留目前設定、設定檔、模型目錄、歷史檔案及復原依據，而不在 Codex 之外分配序號；可遷移儲存區中的 legacy 記錄也受保護。不執行切換、僅保留外部提供者的路徑仍可使用。
++
++請勿刪除對話仍參照的提供者定義、反覆執行 `ocx sync` 或舊版復原，也不要改寫使用中的歷史檔案來繞過拒絕。保留檔案，復原前關閉相關對話，只回報確切錯誤與版本，不要公開私人歷史。需要與原生寫入器協調的已驗證修正。備份或指令碼成功不能證明顯示已復原；重新開啟 Codex 後確認對話。
+diff --git a/src/codex/history-provider.ts b/src/codex/history-provider.ts
+index d7f1832e8f..e121d7007d 100644
+--- a/src/codex/history-provider.ts
++++ b/src/codex/history-provider.ts
+@@ -1,5 +1,5 @@
+ import { createHash } from "node:crypto";
+-import { closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, statSync, unlinkSync, writeSync } from "node:fs";
++import { closeSync, constants, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, statSync, unlinkSync, writeSync } from "node:fs";
+ import { dirname, join, resolve } from "node:path";
+ import { zstdDecompressSync } from "node:zlib";
+ import { Database } from "bun:sqlite";
+@@ -75,14 +75,21 @@ function openStateDb(stateDbPath: string): Database {
+  * rollout's updated_at), and forcing it backwards could hide a real edit from list ordering.
+  */
+ function appendRolloutLine(path: string, line: string): Buffer {
+-  const fd = openSync(path, "a");
++  assertLegacyHistoryRecord(line);
++  // No O_CREAT: a disappeared target is not an invitation to recreate history.
++  const fd = openSync(path, constants.O_RDWR | constants.O_APPEND);
+   const buf = Buffer.from(line.endsWith("\n") ? line : `${line}\n`, "utf8");
+   try {
++    assertLegacyHistoryWritable(path, fd);
++    historyAppendHooks?.beforeWrite?.(path);
++    assertHistoryDescriptorIdentity(path, fd);
+     let offset = 0;
+     while (offset < buf.length) {
+       offset += writeSync(fd, buf, offset, buf.length - offset, null);
+     }
+     try { fsyncSync(fd); } catch { /* best-effort durability */ }
++    historyAppendHooks?.afterWrite?.(path);
++    assertHistoryDescriptorIdentity(path, fd);
+   } finally {
+     closeSync(fd);
+   }
+@@ -186,21 +193,38 @@ function readFirstLineProviderValue(path: string, expectedId: string): string |
+   }
+ }
+
+-function patchFirstLineProviderInPlace(path: string, expectedId: string, provider: string): FirstLineProviderResult {
+-  if (!existsSync(path)) return "unsafe";
++function patchFirstLineProviderInPlace(
++  path: string, expectedId: string, provider: string,
++  expectedIdentity: { dev: number | bigint; ino: number | bigint },
++): FirstLineProviderResult {
++  historyAppendHooks?.beforeFirstLineOpen?.(path);
+   const fd = openSync(path, "r+");
+   try {
++    const assertIdentity = (): void => {
++      assertHistoryDescriptorIdentity(path, fd);
++      const held = fstatSync(fd);
++      if (held.dev !== expectedIdentity.dev || held.ino !== expectedIdentity.ino) {
++        throw new CodexHistoryIntegrityError("history_rollout_identity_changed");
++      }
++    };
++    assertIdentity();
++    assertLegacyHistoryWritable(path, fd);
+     const firstLine = readFirstRolloutLine(fd);
+     if (firstLine === null) return "unsafe";
+     const plan = planFirstLineProvider(firstLine, expectedId, provider);
+     if (plan.state === "unsafe") return "unsafe";
+     if (plan.state === "current") return "current";
+     const out = Buffer.from(plan.patchedLine, "utf8");
++    historyAppendHooks?.beforeFirstLineWrite?.(path);
++    assertIdentity();
++    assertLegacyHistoryWritable(path, fd);
+     let offset = 0;
+     while (offset < out.length) {
+       offset += writeSync(fd, out, offset, out.length - offset, offset);
+     }
+     try { fsyncSync(fd); } catch { /* best-effort durability */ }
++    historyAppendHooks?.afterFirstLineWrite?.(path);
++    assertIdentity();
+     return "patched";
+   } finally {
+     closeSync(fd);
+@@ -221,6 +245,101 @@ class CodexHistoryIntegrityError extends Error {
+   }
+ }
+
++/** Paginated ordinals and projection offsets belong to Codex's live writer.
++ * O_APPEND does not allocate an ordinal or update that writer's in-memory cursor.
++ * Refuse before changing the DB, manifest, or first-line provider; never guess N+1.
++ */
++function assertLegacyHistoryRecord(line: string): void {
++  let value: unknown;
++  try { value = JSON.parse(line); } catch { throw new CodexHistoryIntegrityError("history_rollout_record_invalid"); }
++  if (value === null || typeof value !== "object" || Array.isArray(value)) {
++    throw new CodexHistoryIntegrityError("history_rollout_record_invalid");
++  }
++  const record = value as Record<string, unknown>;
++  const payload = record.payload;
++  if (Object.hasOwn(record, "ordinal") || (payload !== null && typeof payload === "object" && (payload as Record<string, unknown>).history_mode === "paginated")) {
++    throw new CodexHistoryIntegrityError("history_paginated_requires_native_writer");
++  }
++}
++
++function assertHistoryDescriptorIdentity(path: string, fd: number): void {
++  const held = fstatSync(fd);
++  let current: ReturnType<typeof lstatSync>;
++  try { current = lstatSync(path); } catch { throw new CodexHistoryIntegrityError("history_rollout_identity_changed"); }
++  if (!current.isFile() || current.isSymbolicLink() || current.dev !== held.dev || current.ino !== held.ino) {
++    throw new CodexHistoryIntegrityError("history_rollout_identity_changed");
++  }
++}
++
++let historyAppendHooks: {
++  beforeWrite?: (path: string) => void;
++  afterWrite?: (path: string) => void;
++  beforeFirstLineOpen?: (path: string) => void;
++  beforeFirstLineWrite?: (path: string) => void;
++  afterFirstLineWrite?: (path: string) => void;
++} | undefined;
++export function setHistoryAppendHooksForTests(hooks: typeof historyAppendHooks): void { historyAppendHooks = hooks; }
++
++function assertLegacyHistoryWritable(path: string, heldFd?: number): void {
++  if (!path || !existsSync(path)) return;
++  const fd = heldFd ?? openSync(path, "r");
++  try {
++    assertHistoryDescriptorIdentity(path, fd);
++    const first = readFirstRolloutLine(fd);
++    if (!first) throw new CodexHistoryIntegrityError("history_rollout_record_invalid");
++    assertLegacyHistoryRecord(first);
++  } finally {
++    if (heldFd === undefined) closeSync(fd);
++  }
++}
++
++/** A store with history_mode can migrate legacy rows while Codex is running.
++ * Refuse the entire external mutation, not only rows already marked paginated.
++ */
++function assertLegacyHistoryStore(db: Database): void {
++  const columns = db.query<{ name: string }, []>("PRAGMA table_info(threads)").all();
++  if (columns.some(column => column.name === "history_mode")) {
++    throw new CodexHistoryIntegrityError("history_paginated_requires_native_writer");
++  }
++}
++
++/** Read-only preflight before the injector changes provider definitions.
++ * Native paginated history cannot participate in the legacy relabel protocol.
++ * Returning a refusal preserves the existing config as well as the rollout.
++ */
++export function preflightCodexHistoryInjection(
++  providerTableMode: boolean,
++  resumeHistory: boolean,
++  stateDbPath?: string,
++): string | null {
++  let db: Database | undefined;
++  try {
++    const resolvedPath = stateDbPath ?? resolveCodexStateDbPath();
++    if (!existsSync(resolvedPath)) return null;
++    db = new Database(resolvedPath, { readonly: true });
++    const columns = db.query<{ name: string }, []>("PRAGMA table_info(threads)").all();
++    const paginatedColumn = columns.some(column => column.name === "history_mode");
++    const rows = db.query<{ rollout_path: string; history_mode: string | null }, []>(`
++      SELECT rollout_path, ${paginatedColumn ? "history_mode" : "NULL AS history_mode"}
++      FROM threads
++      WHERE ${providerTableMode
++        ? resumeHistory ? "model_provider IN ('openai', 'opencodex')" : "0"
++        : "model_provider = 'opencodex'"}
++    `).all();
++    for (const row of rows) {
++      if (paginatedColumn || row.history_mode === "paginated") return "history_paginated_requires_native_writer";
++      assertLegacyHistoryWritable(row.rollout_path);
++    }
++    return null;
++  } catch (error) {
++    return error instanceof CodexHistoryIntegrityError
++      ? error.message
++      : "history_injection_preflight_unavailable";
++  } finally {
++    db?.close();
++  }
++}
++
+ function integrityFailureResult(error: CodexHistoryIntegrityError): CodexHistorySyncResult {
+   return {
+     rows: error.progress.rows,
+@@ -1026,6 +1145,7 @@ function updateSessionMeta(
+   } = {},
+ ): SessionMetaUpdateResult {
+   if (!path || !existsSync(path)) return { changed: false, durableProvider: false };
++  const validatedIdentity = lstatSync(path);
+   if (options.expectedFileIdentity !== undefined
+     && historyFileIdentity(path) !== options.expectedFileIdentity) {
+     return { changed: false, durableProvider: false, conflict: true };
+@@ -1040,6 +1160,11 @@ function updateSessionMeta(
+   if (!latest) return { changed: false, durableProvider: false };
+   const record = latest.record;
+
++  assertLegacyHistoryWritable(path);
++  if (Object.hasOwn(record, "ordinal") || record.payload.history_mode === "paginated") {
++    throw new CodexHistoryIntegrityError("history_paginated_requires_native_writer");
++  }
++
+   const latestProvider = typeof record.payload.model_provider === "string" && record.payload.model_provider
+     ? record.payload.model_provider
+     : "openai";
+@@ -1094,8 +1219,9 @@ function updateSessionMeta(
+     let firstLine: FirstLineProviderResult = "current";
+     if (patch.provider !== undefined) {
+       try {
+-        firstLine = patchFirstLineProviderInPlace(path, expectedId, patch.provider);
+-      } catch {
++        firstLine = patchFirstLineProviderInPlace(path, expectedId, patch.provider, validatedIdentity);
++      } catch (error) {
++        if (error instanceof CodexHistoryIntegrityError) throw error;
+         firstLine = "unsafe";
+       }
+     }
+@@ -1122,8 +1248,9 @@ function updateSessionMeta(
+   let firstLine: FirstLineProviderResult = "current";
+   if (patch.provider !== undefined) {
+     try {
+-      firstLine = patchFirstLineProviderInPlace(path, expectedId, patch.provider);
+-    } catch {
++      firstLine = patchFirstLineProviderInPlace(path, expectedId, patch.provider, validatedIdentity);
++    } catch (error) {
++      if (error instanceof CodexHistoryIntegrityError) throw error;
+       firstLine = "unsafe";
+     }
+     if (options.requireDurableProvider && firstLine === "unsafe") {
+@@ -1151,6 +1278,8 @@ function relabelAllRoutedHistoryToOpenai(db: Database): { rows: number; files: n
+     `)
+     .all();
+
++  if (rows.length > 0) assertLegacyHistoryStore(db);
++  for (const row of rows) assertLegacyHistoryWritable(row.rollout_path);
+   let files = 0;
+   for (const row of rows) {
+     try {
+@@ -1158,8 +1287,8 @@ function relabelAllRoutedHistoryToOpenai(db: Database): { rows: number; files: n
+         provider: "openai",
+         source: row.source === "exec" ? "cli" : undefined,
+       }).changed) files++;
+-    } catch {
+-      /* explicit legacy recovery still relabels the DB when an old rollout is missing */
++    } catch (error) {
++      if ((error as NodeJS.ErrnoException)?.code !== "ENOENT") throw error;
+     }
+   }
+
+@@ -1302,6 +1431,8 @@ function syncCodexHistoryProviderUnsafe(provider: CodexHistoryProvider, stateDbP
+       `)
+       .all();
+
++    if (openaiRows.length + execRows.length > 0) assertLegacyHistoryStore(db);
++    for (const row of [...openaiRows, ...execRows]) assertLegacyHistoryWritable(row.rollout_path);
+     const manifest = readBackup(backupPath, stateDbPath).manifest;
+     for (const row of [...openaiRows, ...execRows]) rememberOriginal(manifest, row);
+     writeBackup(backupPath, manifest, stateDbPath);
+@@ -1367,15 +1498,15 @@ function syncCodexHistoryProviderUnsafe(provider: CodexHistoryProvider, stateDbP
+       for (const row of openaiRows) {
+         try {
+           if (updateSessionMeta(row.rollout_path, row.id, { provider: "opencodex" }).changed) files++;
+-        } catch {
+-          /* keep DB migration moving; the manifest still carries exact original metadata */
++        } catch (error) {
++          if ((error as NodeJS.ErrnoException)?.code !== "ENOENT") throw error;
+         }
+       }
+       for (const row of execRows) {
+         try {
+           if (updateSessionMeta(row.rollout_path, row.id, { source: "cli" }).changed) files++;
+-        } catch {
+-          /* keep DB migration moving; the manifest still carries exact original metadata */
++        } catch (error) {
++          if ((error as NodeJS.ErrnoException)?.code !== "ENOENT") throw error;
+         }
+       }
+     });
+@@ -1409,9 +1540,12 @@ function restoreCodexHistoryProvider(stateDbPath: string, backupPath: string): C
+   const manifest = backup.manifest;
+   const entries = Object.values(manifest.entries);
+
++  for (const entry of entries) assertLegacyHistoryWritable(entry.rolloutPath);
++
+   const db = openStateDb(stateDbPath);
+   try {
+     if (entries.length === 0) return { rows: 0, files: 0 };
++    assertLegacyHistoryStore(db);
+
+     // Validate the whole manifest-to-database target set before touching a rollout. Only the
+     // OpenCodex post-image (or an already-restored target from an interrupted retry) is owned by
+@@ -1547,6 +1681,7 @@ function restoreCodexHistoryProvider(stateDbPath: string, backupPath: string): C
+
+ export function restoreLegacyOpenaiHistory(stateDbPath = resolveCodexStateDbPath()): CodexHistorySyncResult {
+   if (!existsSync(stateDbPath)) return { rows: 0, files: 0 };
++  try {
+   const retried = withHistoryRetryResult(() => {
+     const db = openStateDb(stateDbPath);
+     try {
+@@ -1556,6 +1691,10 @@ export function restoreLegacyOpenaiHistory(stateDbPath = resolveCodexStateDbPath
+     }
+   });
+   return retried.ok ? retried.value : { rows: 0, files: 0, failed: true, failureReason: retried.reason };
++  } catch (error) {
++    if (error instanceof CodexHistoryIntegrityError) return integrityFailureResult(error);
++    throw error;
++  }
+ }
+
+ /**
+diff --git a/src/codex/inject.ts b/src/codex/inject.ts
+index 12ae087ac4..65661963fb 100644
+--- a/src/codex/inject.ts
++++ b/src/codex/inject.ts
+@@ -46,7 +46,7 @@ import {
+ } from "./journal";
+ import { withCatalogWriteSerialization } from "./catalog-write-serialization";
+ import { restoreCodexCatalogWithPermit } from "./catalog/sync";
+-import { syncCodexHistoryProvider, type CodexHistoryFailureReason } from "./history-provider";
++import { preflightCodexHistoryInjection, syncCodexHistoryProvider, type CodexHistoryFailureReason } from "./history-provider";
+ import {
+   describeHistoryJobFailure,
+   deriveCodexHistoryOperation,
+@@ -75,6 +75,7 @@ import {
+   parseTomlString,
+   readRootTomlString,
+   resolveCodexConfigPath,
++  resolveCodexStateDbPath,
+   tomlString,
+ } from "./paths";
+ import { resolveEffectiveProjectModelProvider } from "./project-config-warnings";
+@@ -899,10 +900,37 @@ export interface CodexInjectResult {
+   nativeSubagentDefaultsWarning?: string;
+ }
+
++class CodexHistoryPreflightRefusal extends Error {}
++class CodexRestoreRefusal extends Error {}
++let historyArtifactStageForTests: ((stage: string) => void) | undefined;
++export function setHistoryArtifactStageForTests(hook: typeof historyArtifactStageForTests): void {
++  historyArtifactStageForTests = hook;
++}
++let beforeRestoreConfigForTests: ((kind: string) => void) | undefined;
++export function setBeforeRestoreConfigForTests(hook: typeof beforeRestoreConfigForTests): void {
++  beforeRestoreConfigForTests = hook;
++}
++let beforeHistoryArtifactCommitForTests: ((kind: string) => void) | undefined;
++export function setBeforeHistoryArtifactCommitForTests(hook: typeof beforeHistoryArtifactCommitForTests): void {
++  beforeHistoryArtifactCommitForTests = hook;
++}
++
+ export async function injectCodexConfig(
+   port: number,
+   config?: OcxConfig,
+   options: InjectCodexOptions = {},
++): Promise<CodexInjectResult> {
++  try { return await injectCodexConfigImpl(port, config, options); }
++  catch (error) {
++    if (error instanceof CodexHistoryPreflightRefusal) return { success: false, message: `Codex config injection refused: ${error.message}. Existing configuration and history were preserved.` };
++    throw error;
++  }
++}
++
++async function injectCodexConfigImpl(
++  port: number,
++  config?: OcxConfig,
++  options: InjectCodexOptions = {},
+ ): Promise<CodexInjectResult> {
+   // Point Codex at the unauthenticated loopback listener when it is enabled (#1102).
+   //
+@@ -929,6 +957,10 @@ export async function injectCodexConfig(
+   }
+
+   const rawContent = readFileSync(CODEX_CONFIG_PATH, "utf-8");
++  const preflightTableMode = usesProviderTable(routingTarget);
++  const compactionOnly = routingTarget.clientCompaction === true
++    && routingTarget.desktopAuthless !== true
++    && routingTarget.requiresAdmissionToken !== true;
+   const activeProvider = externalCodexModelProvider(rawContent);
+   if (activeProvider) {
+     // A launcher may have journaled before the provider manager took ownership. Never let shutdown
+@@ -1138,6 +1170,29 @@ export async function injectCodexConfig(
+   );
+   content = applyEol(content, eol);
+
++  // Resolve storage from the normalized candidate. Owned duplicate catalog keys
++  // are repairable above and must not make this read-only preflight throw.
++  const historyPreflight = (): string | null => {
++    try {
++      return preflightCodexHistoryInjection(
++        preflightTableMode,
++        config?.syncResumeHistory !== false && !compactionOnly,
++        resolveCodexStateDbPath({ readConfig: () => content }),
++      );
++    } catch {
++      return "history_injection_preflight_unavailable";
++    }
++  };
++  const historyPreflightError = historyPreflight();
++  if (historyPreflightError) {
++    return {
++      success: false,
++      message: `Codex config injection refused: ${historyPreflightError}. `
++        + "Existing provider definitions and conversation files were preserved. "
++        + "Paginated history requires native-writer coordination; do not run legacy recovery or retry this transition blindly.",
++    };
++  }
++
+   /*
+    * The witness, built from the FINAL bytes. Everything it hashes is either the
+    * output about to be written or evidence that can be re-read under the lock;
+@@ -1228,6 +1283,12 @@ export async function injectCodexConfig(
+   }
+
+   const applyNativeArtifacts = (): void => {
++    beforeHistoryArtifactCommitForTests?.(eligibility.kind);
++    const historyError = historyPreflight();
++    if (historyError) throw new CodexHistoryPreflightRefusal(historyError);
++    const preImages = captureCodexPreImages();
++    try {
++    historyArtifactStageForTests?.("after-preflight");
+     writeJournal({
+       currentStateIsNative: journalBaselineIsNative(),
+       configContent: baselineContent,
+@@ -1237,6 +1298,7 @@ export async function injectCodexConfig(
+     // must not gain the new injection's hash and later overwrite preserved user edits.
+     if (hasUnverifiedJournalBaseline(baselineContent, readCurrentProfile())) throw new Error(unverifiedJournalMessage);
+     atomicWriteFile(CODEX_CONFIG_PATH, content);
++    historyArtifactStageForTests?.("after-config");
+     atomicWriteFile(CODEX_PROFILE_PATH, profileContent);
+     markJournalInjectedState(content, profileContent, {
+       // A root override is ours whenever we wrote one and no user-owned value won. That is
+@@ -1257,6 +1319,16 @@ export async function injectCodexConfig(
+       // already points at that path and therefore needs no textual rewrite.
+       injectedCatalogPath: catalogPath,
+     });
++    historyArtifactStageForTests?.("after-artifacts");
++    // Detect migration throughout the artifact transaction, not just at entry.
++    // This is compensation, not a native-writer lock or permission to append ordinals.
++    const finalHistoryError = historyPreflight();
++    if (finalHistoryError) throw new CodexHistoryPreflightRefusal(finalHistoryError);
++    } catch (error) {
++      const compensated = restoreCodexPreImages(preImages);
++      if (!compensated.complete) throw new CodexPartialWriteError(compensated.unrestored);
++      throw error;
++    }
+   };
+
+   /*
+@@ -1638,6 +1710,8 @@ function hasOpencodexRouting(content: string): boolean {
+ export function removeCodexConfig(
+   options: { preserveProfile?: boolean } = {},
+ ): { success: boolean; message: string } {
++  const historyError = preflightCodexHistoryInjection(false, false);
++  if (historyError) return { success: false, message: `Codex configuration preserved: ${historyError}. Native writer coordination is required.` };
+   if (!existsSync(CODEX_CONFIG_PATH)) {
+     if (!options.preserveProfile && existsSync(CODEX_PROFILE_PATH))
+       unlinkSync(CODEX_PROFILE_PATH);
+@@ -1838,8 +1912,21 @@ export function skippedRestoreEnvelope(success: boolean, message: string): Codex
+ }
+
+ /** The config/profile half of a native restore, reported as one artifact. */
+-function restoreCodexConfigInline(): CodexRestoreConfigResult {
++function restoreCodexConfigInline(kind = "sync"): CodexRestoreConfigResult {
++  const preImages = captureCodexPreImages();
++  const result = restoreCodexConfigInlineImpl(kind);
++  if (result.state === "failed") {
++    const compensated = restoreCodexPreImages(preImages);
++    if (!compensated.complete) throw new CodexPartialWriteError(compensated.unrestored);
++  }
++  return result;
++}
++
++function restoreCodexConfigInlineImpl(kind: string): CodexRestoreConfigResult {
+   try {
++    beforeRestoreConfigForTests?.(kind);
++    const historyError = preflightCodexHistoryInjection(false, false);
++    if (historyError) return { state: "failed", changed: false, action: "failed", message: `Codex configuration and journal preserved: ${historyError}.` };
+     const journal = restoreJournalState();
+     if (journal.unverified) {
+       return {
+@@ -1912,6 +1999,17 @@ function restoreCodexCatalogArtifact(
+  */
+ export async function restoreNativeCodexAsync(
+   options: { revalidateDesiredState?: boolean } = {},
++): Promise<CodexNativeRestoreResult> {
++  try {
++    return await restoreNativeCodexAsyncImpl(options);
++  } catch (error) {
++    if (!(error instanceof CodexRestoreRefusal)) throw error;
++    return skippedRestoreEnvelope(false, error.message);
++  }
++}
++
++async function restoreNativeCodexAsyncImpl(
++  options: { revalidateDesiredState?: boolean },
+ ): Promise<CodexNativeRestoreResult> {
+   const activeProvider = currentExternalCodexModelProvider();
+   if (activeProvider) {
+@@ -1929,8 +2027,12 @@ export async function restoreNativeCodexAsync(
+   if (options.revalidateDesiredState) {
+     const ownership = inspectNativeCodexOwnership();
+     if (ownership.ownership === "foreign") return foreignOwnershipRestoreRefusal(ownership.reason);
++    if (shouldSyncCodexOnStart(loadConfig())) return desiredEnabledRestoreSkip();
+   }
+
++  const historyError = preflightCodexHistoryInjection(false, false);
++  if (historyError) return skippedRestoreEnvelope(false, `Native restore refused: ${historyError}. Config, catalog, history and provenance were preserved.`);
++
+   const eligibility = codexWriteCoordinationEligibility({
+     coordinatorPath: () =>
+       resolveCodexCoordinatorDatabasePath(resolveEffectiveUserIdentity(), getCodexHome()),
+@@ -1980,7 +2082,9 @@ export async function restoreNativeCodexAsync(
+         const preImages = captureCodexPreImages();
+         let restored: CodexRestoreConfigResult;
+         try {
+-          restored = restoreCodexConfigInline();
++          restored = restoreCodexConfigInline(eligibility.kind);
++          // Throw inside N so the published remove transition rolls back too.
++          if (restored.state === "failed") throw new CodexRestoreRefusal(restored.message);
+         } catch (error) {
+           const compensated = restoreCodexPreImages(preImages);
+           if (!compensated.complete) throw new CodexPartialWriteError(compensated.unrestored);
+@@ -2021,9 +2125,10 @@ export async function restoreNativeCodexAsync(
+     if (options.revalidateDesiredState && shouldSyncCodexOnStart(loadConfig())) {
+       return desiredEnabledRestoreSkip();
+     }
+-    config = restoreCodexConfigInline();
++    config = restoreCodexConfigInline(eligibility.kind);
+   }
+
++  if (config.state === "failed") return skippedRestoreEnvelope(false, config.message);
+   const catalog = restoreCodexCatalogArtifact(options.revalidateDesiredState === true, journaledCatalogPath);
+   const outcome = await runCodexHistoryJob({
+     ...resolveCodexHistoryJobTarget(),
+@@ -2055,8 +2160,7 @@ export async function restoreNativeCodexAsync(
+   const base = catalog.removed > 0
+     ? `${config.message} Catalog restored to ${catalog.kept} native model(s) (dropped ${catalog.removed} proxy-routed).`
+     : config.message;
+-  const success = config.state !== "failed"
+-    && catalog.state !== "failed"
++  const success = catalog.state !== "failed"
+     && history.state !== "failed";
+   return {
+     success,
+@@ -2074,11 +2178,14 @@ export function restoreNativeCodex(options: { skipHistory?: boolean; revalidateD
+   if (options.revalidateDesiredState && shouldSyncCodexOnStart(loadConfig())) {
+     return desiredEnabledRestoreSkip();
+   }
++  const historyError = preflightCodexHistoryInjection(false, false);
++  if (historyError) return skippedRestoreEnvelope(false, `Native restore refused: ${historyError}. Config, catalog, history and provenance were preserved.`);
+   // Captured before the config half: a successful journal restore DELETES the journal, and
+   // restoring the config can drop `model_catalog_json`. Either one would hide the routed
+   // catalog we actually wrote (#1798).
+   const journaledCatalogPath = journaledInjectedCatalogPath();
+   const config = restoreCodexConfigInline();
++  if (config.state === "failed") return skippedRestoreEnvelope(false, config.message);
+   const catalog = restoreCodexCatalogArtifact(options.revalidateDesiredState === true, journaledCatalogPath);
+   // Design B (loopback) steady state: threads are already tagged openai, so prove the
+   // no-op with a readonly probe instead of write-opening a DB the Codex app may hold
+@@ -2115,7 +2222,7 @@ export function restoreNativeCodex(options: { skipHistory?: boolean; revalidateD
+     ? `${config.message} Catalog restored to ${catalog.kept} native model(s) (dropped ${catalog.removed} proxy-routed).`
+     : config.message;
+   return {
+-    success: config.state !== "failed" && catalog.state !== "failed" && history.state !== "failed",
++    success: catalog.state !== "failed" && history.state !== "failed",
+     message,
+     artifacts: { config, catalog, history },
+   };
+diff --git a/structure/catalog.md b/structure/catalog.md
+index 9a0ca08296..8600070638 100644
+--- a/structure/catalog.md
++++ b/structure/catalog.md
+@@ -261,3 +261,11 @@ provider wire mapping; unpinned native requests retain their existing pass-throu
+ > Decision record: [ADR-0025](decisions/ADR-0025-ultra-reasoning-level.md)
+
+ > Decision record: [ADR-0026](decisions/ADR-0026-ultra-reasoning-level.md)
++
++## Paginated history writer boundary
++
++Catalog convergence can include a provider-history transition. Paginated history refusal is an explicit incomplete transition, not successful migration; see [Codex Home](codex-home.md#paginated-history-writer-boundary).
++
++Injection preflights affected history using the normalized config candidate before writing config/profile/journal, then checks again after the complete artifact write. Detected migration restores all three preimages before returning a structured refusal, including on legacy-uncoordinated homes. A failed config restore stops catalog/history work; coordinated restore rolls back its published remove transition. Legacy first-line provider patches are bound to the validated file identity before and after writing. These compensating checks do not provide a native-writer lock or authorize external ordinal allocation.
++
++The legacy external writer is now refused for affected rows in any store whose schema includes history_mode, even while their row mode is still legacy. This deliberately sacrifices automatic relabeling on migration-capable stores rather than racing native conversion. Synchronous/asynchronous restore, inline journal restore, and direct config removal preserve all artifacts on the same refusal.
+diff --git a/structure/codex-home.md b/structure/codex-home.md
+index 9b5e1ded4a..e3389bdf33 100644
+--- a/structure/codex-home.md
++++ b/structure/codex-home.md
+@@ -223,3 +223,11 @@ a deliberate user choice:
+ - Project-level Codex config that bypasses managed routing
+   (`src/codex/project-config-warnings.ts`), surfaced by `ocx doctor` as a warning rather than an
+   override.
++
++## Paginated history writer boundary
++
++`src/codex/history-provider.ts` rejects provider-history changes with `history_paginated_requires_native_writer` when a target begins with an ordinal-bearing record or declares `history_mode=paginated`. Apply, manifest-backed restore, and explicit legacy recovery preflight all selected targets before changing database rows or manifests. The append boundary checks again. Codex owns ordinal allocation and the live projection cursor; reading the last ordinal and appending N+1 is not safe concurrent coordination. Legacy unnumbered rollouts retain their existing behavior. This guard prevents the observed stable-format corruption; it does not implement native-writer integration or guarantee a concurrent legacy-to-paginated conversion is excluded.
++
++Injection preflights affected history using the normalized config candidate before writing config/profile/journal, then checks again after the complete artifact write. Detected migration restores all three preimages before returning a structured refusal, including on legacy-uncoordinated homes. A failed config restore stops catalog/history work; coordinated restore rolls back its published remove transition. Legacy first-line provider patches are bound to the validated file identity before and after writing. These compensating checks do not provide a native-writer lock or authorize external ordinal allocation.
++
++The legacy external writer is now refused for affected rows in any store whose schema includes history_mode, even while their row mode is still legacy. This deliberately sacrifices automatic relabeling on migration-capable stores rather than racing native conversion. Synchronous/asynchronous restore, inline journal restore, and direct config removal preserve all artifacts on the same refusal.
+diff --git a/structure/config.md b/structure/config.md
+index 224c5a350d..d8384e82b2 100644
+--- a/structure/config.md
++++ b/structure/config.md
+@@ -192,3 +192,11 @@ the residual directory for manual review; there is no recursive-delete fallback.
+ ## Remote client key files
+
+ Client connection metadata stores a stable `apiKeyId` and a non-secret rotation `pendingOperation`. The current data secret remains only in `service-api-token`; a bounded rotation temporarily keeps the old secret in owner-only `service-api-token.prev`. Commit or recovery clears the marker before orphan cleanup. `ocx disconnect` is local-only and leaves remote revocation to the hub's **Integrations → API Keys** page. Hub and local usage stores are not mirrored.
++
++## Paginated history writer boundary
++
++Authless routing cannot relabel paginated history through the legacy file writer. A refused history transition must be reported; provider-definition retention during that refusal remains an integration concern. See [Codex Home](codex-home.md#paginated-history-writer-boundary).
++
++Injection preflights affected history using the normalized config candidate before writing config/profile/journal, then checks again after the complete artifact write. Detected migration restores all three preimages before returning a structured refusal, including on legacy-uncoordinated homes. A failed config restore stops catalog/history work; coordinated restore rolls back its published remove transition. Legacy first-line provider patches are bound to the validated file identity before and after writing. These compensating checks do not provide a native-writer lock or authorize external ordinal allocation.
++
++The legacy external writer is now refused for affected rows in any store whose schema includes history_mode, even while their row mode is still legacy. This deliberately sacrifices automatic relabeling on migration-capable stores rather than racing native conversion. Synchronous/asynchronous restore, inline journal restore, and direct config removal preserve all artifacts on the same refusal.
+diff --git a/structure/gui-and-management-api.md b/structure/gui-and-management-api.md
+index c6b35fbad8..9d2ca44805 100644
+--- a/structure/gui-and-management-api.md
++++ b/structure/gui-and-management-api.md
+@@ -504,3 +504,11 @@ converge the Codex catalog once and return its disposition. The Models UI owns a
+ picker data resource so failure cannot erase the ordinary model inventory; Apply publishes through
+ the resource's generation fence, and Most used reads usage only on explicit Apply. Stored mode
+ survives availability drift, while complete/native custom orders await explicit replacement.
++
++## Paginated history writer boundary
++
++Settings convergence must surface paginated-history refusal rather than claim history was migrated. See [Codex Home](codex-home.md#paginated-history-writer-boundary).
++
++Injection preflights affected history using the normalized config candidate before writing config/profile/journal, then checks again after the complete artifact write. Detected migration restores all three preimages before returning a structured refusal, including on legacy-uncoordinated homes. A failed config restore stops catalog/history work; coordinated restore rolls back its published remove transition. Legacy first-line provider patches are bound to the validated file identity before and after writing. These compensating checks do not provide a native-writer lock or authorize external ordinal allocation.
++
++The legacy external writer is now refused for affected rows in any store whose schema includes history_mode, even while their row mode is still legacy. This deliberately sacrifices automatic relabeling on migration-capable stores rather than racing native conversion. Synchronous/asynchronous restore, inline journal restore, and direct config removal preserve all artifacts on the same refusal.
+diff --git a/structure/ops/docs-and-release.md b/structure/ops/docs-and-release.md
+index 6d7988af78..bcf89f8933 100644
+--- a/structure/ops/docs-and-release.md
++++ b/structure/ops/docs-and-release.md
+@@ -300,3 +300,11 @@ This keeps release runs short and makes release a deployment of a verified commi
+ ## Remote Hub locale and release gate
+
+ The Remote Hub guide and affected CLI, server-config, management-API, and dashboard references have eight sources: root English plus `fr`, `ko`, `zh-cn`, `zh-tw`, `ru`, `ja`, and `tr`. English is canonical; commands, defaults, endpoint auth, and warnings remain exact in translations. A release requires the remote-only focused/full gates, privacy scan, GUI/docs builds, protocol compatibility receipts, and the MAINTAINERS security review for the exact head.
++
++## Paginated history writer boundary
++
++History-provider regression coverage includes numbered rollout apply/restore refusal without changing source bytes or provenance. See [Codex Home](../codex-home.md#paginated-history-writer-boundary).
++
++Injection preflights affected history using the normalized config candidate before writing config/profile/journal, then checks again after the complete artifact write. Detected migration restores all three preimages before returning a structured refusal, including on legacy-uncoordinated homes. A failed config restore stops catalog/history work; coordinated restore rolls back its published remove transition. Legacy first-line provider patches are bound to the validated file identity before and after writing. These compensating checks do not provide a native-writer lock or authorize external ordinal allocation.
++
++The legacy external writer is now refused for affected rows in any store whose schema includes history_mode, even while their row mode is still legacy. This deliberately sacrifices automatic relabeling on migration-capable stores rather than racing native conversion. Synchronous/asynchronous restore, inline journal restore, and direct config removal preserve all artifacts on the same refusal.
+diff --git a/structure/providers/openai-tiers.md b/structure/providers/openai-tiers.md
+index 9f86870bae..2e13055dea 100644
+--- a/structure/providers/openai-tiers.md
++++ b/structure/providers/openai-tiers.md
+@@ -368,3 +368,11 @@ model settings, and noncanonical `openai` rows never receive that recovery path.
+ `GET /api/codex-auth/accounts?refresh=1` treats missing main credentials, HTTP 401, and allowlisted
+ terminal 403 codes as `needsReauth`; generic permission failures remain non-terminal, and a
+ successful main usage refresh clears the runtime mark.
++
++## Paginated history writer boundary
++
++Provider account selection does not authorize relabeling paginated Codex records; the [history writer boundary](../codex-home.md#paginated-history-writer-boundary) applies independently of account mode.
++
++Injection preflights affected history using the normalized config candidate before writing config/profile/journal, then checks again after the complete artifact write. Detected migration restores all three preimages before returning a structured refusal, including on legacy-uncoordinated homes. A failed config restore stops catalog/history work; coordinated restore rolls back its published remove transition. Legacy first-line provider patches are bound to the validated file identity before and after writing. These compensating checks do not provide a native-writer lock or authorize external ordinal allocation.
++
++The legacy external writer is now refused for affected rows in any store whose schema includes history_mode, even while their row mode is still legacy. This deliberately sacrifices automatic relabeling on migration-capable stores rather than racing native conversion. Synchronous/asynchronous restore, inline journal restore, and direct config removal preserve all artifacts on the same refusal.
+diff --git a/structure/runtime.md b/structure/runtime.md
+index 3099c13bfd..edcb0c7712 100644
+--- a/structure/runtime.md
++++ b/structure/runtime.md
+@@ -185,3 +185,11 @@ not an authentication or entitlement decision.
+ ## Remote Hub hardening ownership
+
+ `src/remote/protocol.ts` owns pure interval/feature negotiation. `src/remote/hub-state.ts` owns the `GET|HEAD /v1/hub-state` contract, its caps, and the parser both sides share. `src/client/hub-client.ts` owns bounded, schema-validated remote catalog consumption, hub-state reads, and key-id probes; `src/client/hub-state.ts` owns the resolution and the owner-stamped 0600 cache, and a failed read reports "unavailable" rather than degrading to the client's own local provider and login state. `src/client/hub-relay.ts` is a fixed-authority management relay with URL, header, body, redirect, and stream bounds. The public data listener remains the direct client→hub path; the loopback management ingress never serves data-plane routes.
++
++## Paginated history writer boundary
++
++Provider-history transitions refuse paginated rollout writes before changing history state; see [Codex Home](codex-home.md#paginated-history-writer-boundary).
++
++Injection preflights affected history using the normalized config candidate before writing config/profile/journal, then checks again after the complete artifact write. Detected migration restores all three preimages before returning a structured refusal, including on legacy-uncoordinated homes. A failed config restore stops catalog/history work; coordinated restore rolls back its published remove transition. Legacy first-line provider patches are bound to the validated file identity before and after writing. These compensating checks do not provide a native-writer lock or authorize external ordinal allocation.
++
++The legacy external writer is now refused for affected rows in any store whose schema includes history_mode, even while their row mode is still legacy. This deliberately sacrifices automatic relabeling on migration-capable stores rather than racing native conversion. Synchronous/asynchronous restore, inline journal restore, and direct config removal preserve all artifacts on the same refusal.
+diff --git a/structure/subagents.md b/structure/subagents.md
+index a3513a726a..8b55aa1f03 100644
+--- a/structure/subagents.md
++++ b/structure/subagents.md
+@@ -195,3 +195,11 @@ Claude ModelInfo ordering receives optional `{ modelPickerOrder, featured }` aft
+ It orders routed output groups after alias deduplication, preserving the collision winner and
+ base/1M/Fast siblings. Native groups and explicit Desktop profile ownership are unchanged.
+ Native Codex advertisements still follow display priority; private guidance ranks do not freeze them.
++
++## Paginated history writer boundary
++
++History metadata for parent or child threads follows the same [paginated writer boundary](codex-home.md#paginated-history-writer-boundary); a child source does not authorize external ordinal allocation.
++
++Injection preflights affected history using the normalized config candidate before writing config/profile/journal, then checks again after the complete artifact write. Detected migration restores all three preimages before returning a structured refusal, including on legacy-uncoordinated homes. A failed config restore stops catalog/history work; coordinated restore rolls back its published remove transition. Legacy first-line provider patches are bound to the validated file identity before and after writing. These compensating checks do not provide a native-writer lock or authorize external ordinal allocation.
++
++The legacy external writer is now refused for affected rows in any store whose schema includes history_mode, even while their row mode is still legacy. This deliberately sacrifices automatic relabeling on migration-capable stores rather than racing native conversion. Synchronous/asynchronous restore, inline journal restore, and direct config removal preserve all artifacts on the same refusal.
+diff --git a/tests/codex-integration/codex-history-provider.test.ts b/tests/codex-integration/codex-history-provider.test.ts
+index fbc97238de..972245846f 100644
+--- a/tests/codex-integration/codex-history-provider.test.ts
++++ b/tests/codex-integration/codex-history-provider.test.ts
+@@ -1,10 +1,11 @@
+-import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, utimesSync, writeFileSync } from "node:fs";
++import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, utimesSync, writeFileSync } from "node:fs";
+ import { tmpdir } from "node:os";
+ import { join } from "node:path";
+ import { Database } from "bun:sqlite";
+ import { afterEach, describe, expect, setDefaultTimeout, test } from "bun:test";
+ import { classifyRecoverableHistoryError, countPendingOpencodexHistory, historyBackupPathFor, isRecoverableHistoryError, migrateHistoryToOpenai, restoreLegacyOpenaiHistory, restoredUserEventFor, setAfterNoopPendingCountForTests, setAfterStrictHistoryRolloutAppendForTests, setBeforeHistoryApplyTransactionForTests, setBeforeHistoryBackupConsumeForTests, setBeforeStrictHistoryRolloutAppendForTests, setHistoryDbBusyTimeoutForTests, snapshotCodexHistoryNoop, syncCodexHistoryProvider, withHistoryRetry } from "../../src/codex/history-provider";
+ import { INVALID_HISTORY_BACKUP_FIXTURES, validHistoryBackupFixture } from "../helpers/codex-history-manifest-fixtures";
++import { preflightCodexHistoryInjection, setHistoryAppendHooksForTests } from "../../src/codex/history-provider";
+
+ // Windows CI: a transient file lock can consume the full production 5s busy timeout, tripping
+ // bun's 5s default per-test timeout by itself. Fail fast into withHistoryRetry instead.
+@@ -15,6 +16,7 @@ setDefaultTimeout(30_000);
+
+ const noopSnapshotArtifacts = new Set<string>();
+ afterEach(() => {
++  setHistoryAppendHooksForTests(undefined);
+   setBeforeHistoryBackupConsumeForTests(undefined);
+   setBeforeStrictHistoryRolloutAppendForTests(undefined);
+   setAfterStrictHistoryRolloutAppendForTests(undefined);
+@@ -101,6 +103,135 @@ function makeFixture({ includeExec = false, includeLegacy = false } = {}) {
+ }
+
+ describe("Codex history provider sync", () => {
++  test.each(["{broken", "null", "[]", "42", '"text"'])("invalid first record %s is a structured integrity failure", (first) => {
++    const fixture = makeFixture();
++    noopSnapshotArtifacts.add(join(fixture.dbPath,".."));
++    writeFileSync(fixture.rollout, first + "\n");
++    expect(syncCodexHistoryProvider("opencodex",fixture.dbPath,fixture.backupPath)).toMatchObject({failed:true,rows:0,files:0,integrityCode:"history_rollout_record_invalid"});
++    const db = new Database(fixture.dbPath);
++    db.run("UPDATE threads SET model_provider='opencodex'");
++    db.close();
++    expect(restoreLegacyOpenaiHistory(fixture.dbPath)).toMatchObject({failed:true,rows:0,files:0,integrityCode:"history_rollout_record_invalid"});
++    expect(readFileSync(fixture.rollout,"utf8")).toBe(first+"\n");
++  });
++
++  test.each(["beforeWrite", "afterWrite"] as const)("descriptor-bound append refuses path replacement %s", (stage) => {
++    const fixture = makeFixture();
++    noopSnapshotArtifacts.add(join(fixture.dbPath,".."));
++    const replacement=JSON.stringify({ordinal:0,type:"session_meta",payload:{id:"thread-1",history_mode:"paginated",model_provider:"openai"}})+"\n";
++    setHistoryAppendHooksForTests({[stage]:(path:string)=>{
++      if(path!==fixture.rollout)return;
++      renameSync(path,path+".old");
++      writeFileSync(path,replacement);
++    }});
++    expect(syncCodexHistoryProvider("opencodex",fixture.dbPath,fixture.backupPath)).toMatchObject({failed:true,rows:0,integrityCode:"history_rollout_identity_changed"});
++    expect(readFileSync(fixture.rollout,"utf8")).toBe(replacement);
++    const db=new Database(fixture.dbPath,{readonly:true});
++    expect(db.query("SELECT model_provider FROM threads WHERE id='thread-1'").get()).toEqual({model_provider:"openai"});
++    db.close();
++  });
++
++  for (const stage of ["beforeFirstLineOpen", "beforeFirstLineWrite", "afterFirstLineWrite"] as const) {
++    test.each([false, true])(`first-line identity guard preserves replacement (${stage}, strict=%s)`, (strict) => {
++      const fixture = makeFixture();
++      noopSnapshotArtifacts.add(join(fixture.dbPath, ".."));
++      // Leave enough first-line padding for forward provider replacement in place.
++      const raw = readFileSync(fixture.rollout, "utf8");
++      writeFileSync(fixture.rollout, raw.replace('"model_provider":"openai"', '"model_provider":"openai"                '));
++      if (strict) expect(syncCodexHistoryProvider("opencodex", fixture.dbPath, fixture.backupPath).rows).toBe(1);
++      const provider = strict ? "opencodex" : "openai";
++      const replacement = JSON.stringify({ordinal:0,type:"session_meta",payload:{id:"thread-1",history_mode:"paginated",model_provider:provider}}) + "\n";
++      let fired = false;
++      setHistoryAppendHooksForTests({[stage]:(path:string)=>{
++        if(path!==fixture.rollout || fired)return;
++        fired=true;
++        renameSync(path,path+".old");
++        writeFileSync(path,replacement);
++      }});
++      const result=syncCodexHistoryProvider(strict?"openai":"opencodex",fixture.dbPath,fixture.backupPath);
++      expect(fired).toBe(true);
++      expect(result).toMatchObject({failed:true,rows:0,integrityCode:strict?"history_backup_partial_restore":"history_rollout_identity_changed"});
++      expect(readFileSync(fixture.rollout,"utf8")).toBe(replacement);
++      const db=new Database(fixture.dbPath,{readonly:true});
++      expect(db.query("SELECT model_provider FROM threads WHERE id='thread-1'").get()).toEqual({model_provider:provider});
++      db.close();
++      if(strict) expect(existsSync(fixture.backupPath)).toBe(true);
++    });
++  }
++
++  test("late paginated conversion rolls back routing instead of swallowing integrity failure",()=>{
++    const fixture=makeFixture();
++    noopSnapshotArtifacts.add(join(fixture.dbPath,".."));
++    const replacement=JSON.stringify({ordinal:0,type:"session_meta",payload:{id:"thread-1",history_mode:"paginated",model_provider:"openai"}})+"\n";
++    setBeforeHistoryApplyTransactionForTests(()=>writeFileSync(fixture.rollout,replacement));
++    expect(syncCodexHistoryProvider("opencodex",fixture.dbPath,fixture.backupPath)).toMatchObject({failed:true,rows:0,integrityCode:"history_paginated_requires_native_writer"});
++    expect(readFileSync(fixture.rollout,"utf8")).toBe(replacement);
++    const db=new Database(fixture.dbPath,{readonly:true});
++    expect(db.query("SELECT model_provider FROM threads WHERE id='thread-1'").get()).toEqual({model_provider:"openai"});
++    db.close();
++  });
++  test("refuses legacy rows in a migration-capable store before external writes", () => {
++    const fixture = makeFixture();
++    noopSnapshotArtifacts.add(join(fixture.dbPath, ".."));
++    const before = readFileSync(fixture.rollout, "utf8");
++    const db = new Database(fixture.dbPath);
++    db.run("ALTER TABLE threads ADD COLUMN history_mode TEXT DEFAULT 'legacy'");
++    db.close();
++    expect(syncCodexHistoryProvider("opencodex", fixture.dbPath, fixture.backupPath)).toMatchObject({failed:true,rows:0,files:0,integrityCode:"history_paginated_requires_native_writer"});
++    expect(readFileSync(fixture.rollout,"utf8")).toBe(before);
++    expect(existsSync(fixture.backupPath)).toBe(false);
++  });
++  test("injection preflight preserves provider definitions needed by paginated threads", () => {
++    const fixture = makeFixture({ includeLegacy: true });
++    noopSnapshotArtifacts.add(join(fixture.dbPath, ".."));
++    const db = new Database(fixture.dbPath);
++    db.run("ALTER TABLE threads ADD COLUMN history_mode TEXT DEFAULT 'legacy'");
++    db.run("UPDATE threads SET history_mode='paginated' WHERE id='thread-3'");
++    db.close();
++    expect(preflightCodexHistoryInjection(false, false, fixture.dbPath)).toBe("history_paginated_requires_native_writer");
++    expect(preflightCodexHistoryInjection(true, true, fixture.dbPath)).toBe("history_paginated_requires_native_writer");
++    expect(preflightCodexHistoryInjection(true, false, fixture.dbPath)).toBeNull();
++    expect(existsSync(fixture.backupPath)).toBe(false);
++  });
++
++  for (const marker of ["ordinal", "history_mode"] as const) {
++    test(`refuses paginated ${marker} before routing any row or writing a manifest`, () => {
++      const fixture = makeFixture();
++      noopSnapshotArtifacts.add(join(fixture.dbPath, ".."));
++      const records = readFileSync(fixture.rollout, "utf8").trim().split("\n").map(line => JSON.parse(line));
++      if (marker === "ordinal") records.forEach((record, ordinal) => { record.ordinal = ordinal; });
++      else records[0].payload.history_mode = "paginated";
++      const before = records.map(record => JSON.stringify(record)).join("\n") + "\n";
++      writeFileSync(fixture.rollout, before);
++      const result = syncCodexHistoryProvider("opencodex", fixture.dbPath, fixture.backupPath);
++      expect(result).toMatchObject({ rows: 0, files: 0, failed: true, integrityCode: "history_paginated_requires_native_writer" });
++      expect(readFileSync(fixture.rollout, "utf8")).toBe(before);
++      expect(existsSync(fixture.backupPath)).toBe(false);
++      const db = new Database(fixture.dbPath, { readonly: true });
++      expect(db.query("SELECT model_provider FROM threads WHERE id = 'thread-1'").get()).toEqual({ model_provider: "openai" });
++      db.close();
++    });
++  }
++
++  test("preserves a routed paginated rollout and its restore manifest", () => {
++    const fixture = makeFixture();
++    noopSnapshotArtifacts.add(join(fixture.dbPath, ".."));
++    expect(syncCodexHistoryProvider("opencodex", fixture.dbPath, fixture.backupPath).failed).toBeUndefined();
++    const records = readFileSync(fixture.rollout, "utf8").trim().split("\n").map(line => JSON.parse(line));
++    records.forEach((record, ordinal) => { record.ordinal = ordinal; });
++    const before = records.map(record => JSON.stringify(record)).join("\n") + "\n";
++    writeFileSync(fixture.rollout, before);
++    const manifest = readFileSync(fixture.backupPath, "utf8");
++    for (const result of [syncCodexHistoryProvider("openai", fixture.dbPath, fixture.backupPath), restoreLegacyOpenaiHistory(fixture.dbPath)]) {
++      expect(result).toMatchObject({ rows: 0, files: 0, failed: true, integrityCode: "history_paginated_requires_native_writer" });
++    }
++    expect(readFileSync(fixture.rollout, "utf8")).toBe(before);
++    expect(readFileSync(fixture.backupPath, "utf8")).toBe(manifest);
++    const db = new Database(fixture.dbPath, { readonly: true });
++    expect(db.query("SELECT model_provider FROM threads WHERE id = 'thread-1'").get()).toEqual({ model_provider: "opencodex" });
++    db.close();
++  });
++
+   test("maps resumable Codex threads to opencodex via the latest session_meta", () => {
+     const { dbPath, backupPath, rollout } = makeFixture();
+
+diff --git a/tests/codex-integration/codex-inject-integration.test.ts b/tests/codex-integration/codex-inject-integration.test.ts
+index 57e83650f1..0b30d78703 100644
+--- a/tests/codex-integration/codex-inject-integration.test.ts
++++ b/tests/codex-integration/codex-inject-integration.test.ts
+@@ -34,10 +34,10 @@ function runInject(codexHome: string, ocxHome: string, configJson = "{}"): { std
+   return { stdout: result.stdout?.trim() ?? "", status: result.status ?? 1 };
+ }
+
+-function runRestore(codexHome: string, ocxHome: string): { stdout: string; status: number } {
++function runRestore(codexHome: string, ocxHome: string, asyncRestore = false): { stdout: string; status: number } {
+   const script = `
+-    const { restoreNativeCodex } = require("./src/codex/inject");
+-    console.log(JSON.stringify(restoreNativeCodex()));
++    const { restoreNativeCodex, restoreNativeCodexAsync } = require("./src/codex/inject");
++    console.log(JSON.stringify(${asyncRestore ? "await restoreNativeCodexAsync()" : "restoreNativeCodex()"}));
+   `;
+   const result = spawnSync(process.execPath, ["--eval", script], {
+     cwd: repoRoot,
+@@ -68,6 +68,124 @@ describe("injectCodexConfig integration (Design B)", () => {
+     removeTreeWithRetry(ocxHome);
+   });
+
++  for (const stage of ["before-preflight", "after-preflight", "after-config", "after-artifacts"]) {
++  test.each([false,true])(`commit-boundary history refusal returns a result after rollback (${stage}, legacy=%s)`,(legacy)=>{
++    const original=legacy ? DESIGN_B_BLOCK+"\n" : 'model="test"\n';
++    writeFileSync(join(codexHome,"config.toml"),original);
++    if(legacy) writeFileSync(join(codexHome,"opencodex.config.toml"),"[invalid profile\n");
++    const script=`
++      const {Database}=require("bun:sqlite");
++      const {join}=require("node:path");
++      const {injectCodexConfig,setBeforeHistoryArtifactCommitForTests,setHistoryArtifactStageForTests}=require("./src/codex/inject");
++      let kind;
++      const migrate=()=>{
++        const db=new Database(join(process.env.CODEX_HOME,"state_5.sqlite"));
++        db.run("CREATE TABLE threads (rollout_path TEXT, model_provider TEXT, history_mode TEXT)");
++        db.run("INSERT INTO threads VALUES ('fixture','opencodex','paginated')");
++        db.close();
++      };
++      setBeforeHistoryArtifactCommitForTests(value=>{
++        kind=value;
++        if (${JSON.stringify(stage)} === "before-preflight") migrate();
++      });
++      setHistoryArtifactStageForTests(value=>{if(value===${JSON.stringify(stage)})migrate();});
++      const result=await injectCodexConfig(10100,{});
++      console.log(JSON.stringify({kind,result}));
++    `;
++    const child=spawnSync(process.execPath,["--eval",script],{cwd:repoRoot,env:{...process.env,CODEX_HOME:codexHome,OPENCODEX_HOME:ocxHome},encoding:"utf8",timeout:SPAWN_BUDGET_MS-5000});
++    expect(child.status).toBe(0);
++    const value=JSON.parse(child.stdout);
++    expect(value.kind).toBe(legacy?"legacy-uncoordinated":"coordinated");
++    expect(value.result).toMatchObject({success:false});
++    expect(value.result.message).toContain("history_paginated_requires_native_writer");
++    expect(readFileSync(join(codexHome,"config.toml"),"utf8")).toBe(original);
++    expect(existsSync(join(codexHome,"opencodex-journal.json"))).toBe(false);
++    if(legacy) expect(readFileSync(join(codexHome,"opencodex.config.toml"),"utf8")).toBe("[invalid profile\n");
++    else expect(existsSync(join(codexHome,"opencodex.config.toml"))).toBe(false);
++  });
++  }
++
++  test.each(["sync", "legacy-uncoordinated", "coordinated"])("config restore failure aborts every later artifact (%s)", (kind) => {
++    const original = kind === "coordinated" ? 'model="test"\n' : DESIGN_B_BLOCK + "\n";
++    writeFileSync(join(codexHome, "config.toml"), original);
++    if (kind !== "coordinated") writeFileSync(join(codexHome, "opencodex.config.toml"), "[invalid profile\n");
++    const catalog = '{"models":[],"sentinel":"preserve"}\n';
++    writeFileSync(join(codexHome, "models_cache.json"), catalog);
++    const script = `
++      const {Database}=require("bun:sqlite");
++      const {join}=require("node:path");
++      const {restoreNativeCodex,restoreNativeCodexAsync,setBeforeRestoreConfigForTests}=require("./src/codex/inject");
++      const readState=${kind === "coordinated" ? 'require("./src/codex/transition-state").readCodexTransitionState' : "()=>null"};
++      const before=readState();
++      let observed;
++      setBeforeRestoreConfigForTests(value=>{
++        observed=value;
++        const db=new Database(join(process.env.CODEX_HOME,"state_5.sqlite"));
++        db.run("CREATE TABLE threads (rollout_path TEXT, model_provider TEXT, history_mode TEXT)");
++        db.run("INSERT INTO threads VALUES ('fixture','opencodex','paginated')");
++        db.close();
++      });
++      const result=${kind === "sync" ? "restoreNativeCodex()" : "await restoreNativeCodexAsync()"};
++      console.log(JSON.stringify({observed,result,before,after:readState()}));
++    `;
++    const child=spawnSync(process.execPath,["--eval",script],{cwd:repoRoot,env:{...process.env,CODEX_HOME:codexHome,OPENCODEX_HOME:ocxHome},encoding:"utf8",timeout:SPAWN_BUDGET_MS-5000});
++    expect(child.status).toBe(0);
++    const value=JSON.parse(child.stdout);
++    expect(value.observed).toBe(kind);
++    expect(value.result.success).toBe(false);
++    if(kind==="coordinated") {
++      // Never advance durable generation/tx state when config restoration fails.
++      expect(value.before.state).toMatchObject({nativeGeneration:0,currentTxId:null});
++      expect(value.after.state).toEqual(value.before.state);
++    }
++    for (const artifact of Object.values(value.result.artifacts)) {
++      expect(artifact).toMatchObject({state:"skipped",changed:false});
++    }
++    expect(readFileSync(join(codexHome,"config.toml"),"utf8")).toBe(original);
++    expect(readFileSync(join(codexHome,"models_cache.json"),"utf8")).toBe(catalog);
++    expect(existsSync(join(codexHome,"opencodex-journal.json"))).toBe(false);
++    if(kind!=="coordinated") expect(readFileSync(join(codexHome,"opencodex.config.toml"),"utf8")).toBe("[invalid profile\n");
++    else expect(existsSync(join(codexHome,"opencodex.config.toml"))).toBe(false);
++  });
++
++  test.each([false, true])("paginated history preserves config and profile before provider transition (authless=%s)", (authless) => {
++    const original = 'model_provider = "opencodex"\n[model_providers.opencodex]\nname="OpenCodex"\nbase_url="http://127.0.0.1:10100/v1"\nwire_api="responses"\n';
++    const configPath = join(codexHome, "config.toml");
++    const profilePath = join(codexHome, "opencodex.config.toml");
++    writeFileSync(configPath, original);
++    writeFileSync(profilePath, "# preserve profile\n");
++    const rollout = join(codexHome, "fixture.jsonl");
++    const bytes = JSON.stringify({ordinal:0,type:"session_meta",payload:{id:"fixture",history_mode:"paginated",model_provider:"opencodex"}}) + "\n";
++    writeFileSync(rollout, bytes);
++    const db = new Database(join(codexHome, "state_5.sqlite"));
++    db.run("CREATE TABLE threads (id TEXT, rollout_path TEXT, model_provider TEXT, history_mode TEXT)");
++    db.run("INSERT INTO threads VALUES ('fixture', ?, 'opencodex', 'paginated')", rollout);
++    db.close();
++    const result = runInject(codexHome, ocxHome, JSON.stringify({codexDesktopAuthless:authless}));
++    expect(result.status).toBe(0);
++    expect(JSON.parse(result.stdout)).toMatchObject({success:false});
++    expect(result.stdout).toContain("history_paginated_requires_native_writer");
++    expect(readFileSync(configPath,"utf8")).toBe(original);
++    expect(readFileSync(profilePath,"utf8")).toBe("# preserve profile\n");
++    expect(readFileSync(rollout,"utf8")).toBe(bytes);
++    expect(existsSync(join(codexHome,"opencodex-journal.json"))).toBe(false);
++    const restoreScript = `
++      const { restoreNativeCodex, restoreNativeCodexAsync, removeCodexConfig } = require("./src/codex/inject");
++      const results = [restoreNativeCodex(), await restoreNativeCodexAsync(), removeCodexConfig()];
++      console.log(JSON.stringify(results));
++    `;
++    const restored = spawnSync(process.execPath, ["--eval", restoreScript], {
++      cwd: repoRoot, env: { ...process.env, CODEX_HOME: codexHome, OPENCODEX_HOME: ocxHome },
++      encoding: "utf8", timeout: SPAWN_BUDGET_MS - 5_000,
++    });
++    expect(restored.status).toBe(0);
++    for (const outcome of JSON.parse(restored.stdout)) expect(outcome.success).toBe(false);
++    expect(readFileSync(configPath,"utf8")).toBe(original);
++    expect(readFileSync(profilePath,"utf8")).toBe("# preserve profile\n");
++    expect(readFileSync(rollout,"utf8")).toBe(bytes);
++    expect(existsSync(join(codexHome,"opencodex-journal.json"))).toBe(false);
++  });
++
+   test("remote target validate-only writes nothing; commit journals client ownership and restores exact preimage", () => {
+     const original = '# remote baseline\nmodel_provider = "openai"\n';
+     writeFileSync(join(codexHome, "config.toml"), original, "utf8");
+@@ -760,7 +878,7 @@ describe("injectCodexConfig integration (Design B)", () => {
+     expect(readFileSync(join(codexHome, "config.toml"), "utf8")).toBe(original);
+   });
+
+-  test("restoreNativeCodex removes a stale journal without changing external provider state", () => {
++  test.each([false,true])("restore removes a stale journal without changing external provider state (async=%s)", (asyncRestore) => {
+     const configPath = join(codexHome, "config.toml");
+     const config = 'model_provider = "custom"\nmodel = "third-party-model"\n';
+     writeFileSync(configPath, config, "utf8");
+@@ -782,7 +900,9 @@ describe("injectCodexConfig integration (Design B)", () => {
+       id TEXT PRIMARY KEY, rollout_path TEXT NOT NULL, model_provider TEXT NOT NULL,
+       source TEXT NOT NULL, first_user_message TEXT NOT NULL, has_user_event INTEGER NOT NULL
+     )`);
+-    db.run(`INSERT INTO threads VALUES ('thread-custom', ?, 'custom', 'cli', 'hello', 1)`, rolloutPath);
++      db.run(`INSERT INTO threads VALUES ('thread-custom', ?, 'custom', 'cli', 'hello', 1)`, rolloutPath);
++      db.run("ALTER TABLE threads ADD COLUMN history_mode TEXT DEFAULT 'legacy'");
++      db.run("INSERT INTO threads VALUES ('old-routed', ?, 'opencodex', 'cli', 'older', 1, 'paginated')", rolloutPath);
+     db.close();
+     const dbBefore = readFileSync(dbPath);
+
+@@ -795,7 +915,7 @@ describe("injectCodexConfig integration (Design B)", () => {
+       timestamp: new Date().toISOString(),
+     }), "utf8");
+
+-    const r = runRestore(codexHome, ocxHome);
++      const r = runRestore(codexHome, ocxHome, asyncRestore);
+     expect(r.status).toBe(0);
+     const result = JSON.parse(r.stdout);
+     expect(result.success).toBe(true);
+```
+
+## Design reflection amendment HIST-ARCH-02
+
+Accepted: native restore preflight must include manifest-owned targets whose DB provider already equals openai after an interrupted restore. MODIFY preflightCodexHistoryInjection: when providerTableMode is false, call readBackup(historyBackupPathFor(resolvedPath), resolvedPath), collect Object.values(manifest.entries), refuse history_mode-capable stores with any such entries and assertLegacyHistoryWritable for each entry.rolloutPath before scanning current routed rows. Use the existing read-only manifest reader, not a new parser. An invalid/foreign manifest maps to the existing integrity failure string before config mutation.
+
+NEW regression inside existing codex-inject-integration.test.ts: seed legacy routed history with syncCodexHistoryProvider(opencodex), leaving a nonempty real manifest; set its DB provider back to openai, add history_mode TEXT DEFAULT legacy, then call native restore. Assert success=false; config/profile/journal/backup/rollout bytes unchanged. Both sync and async restore must refuse. Hosted CI only; locally NOT RUN.
+
+Preservation statement is conditional on detected incompatibility before/within artifact transaction. Native migration after final preflight is a residual race; no global atomicity or native writer lock is claimed.
+
+Additional compensation review material is held in local scratch under repository security-note policy. It is an implementation prerequisite; do not interpret the public source diff as unchanged adoption.
diff --git a/devlog/_plan/260912_history_containment/020_continuation.md b/devlog/_plan/260912_history_containment/020_continuation.md
new file mode 100644
index 0000000000..93ea1af49e
--- /dev/null
+++ b/devlog/_plan/260912_history_containment/020_continuation.md
@@ -0,0 +1,407 @@
+# Continuation source-pinned change design
+
+Source: PR #4086 at 0c39bc60845211e1fe9efdeb8b34043fe4daac96. Initial carry uses the following public diff, revalidated against current dev at phase P. The current-tree map below is authoritative; fenced diff headers retain historical source provenance. Main resolves conflicts against current owners; no wholesale replacement from a stale head.
+
+Before: current merge-base behavior in removed lines. After: added lines below. Tests are authored but NOT RUN locally; final-tip hosted CI observes these files. No new dependency or persisted schema is introduced by containment/continuation; relay owner state remains bounded/process-local and needs separate security review.
+
+Activation: after final route selection, an unexpanded previous_response_id on selected openai-responses with explicit statelessResponses (any input kind), or unmapped lowered custom result; observe recoverable 400 and zero upstream calls, then complete-history retry and next incremental request. Capability creation comes from provider definitions/config, serialization uses existing provider config, deserialization existing loader, consumers selected core adapter guard; no new capability values.
+
+Current-dev adaptation: old structure/04_transports-and-sidecars.md has been retired; transfer the continuation contract into structure/transports/responses.md and concise ownership links in mapped docs. Apply current source hunks, manually place the English guide addition beside continuation documentation while preserving newer text. This phase uses an independent dev branch; shared files alone create no dependency.
+
+```diff
+diff --git a/docs-site/src/content/docs/guides/codex-integration.md b/docs-site/src/content/docs/guides/codex-integration.md
+index 5b75a21b41..368cbc5580 100644
+--- a/docs-site/src/content/docs/guides/codex-integration.md
++++ b/docs-site/src/content/docs/guides/codex-integration.md
+@@ -245,6 +245,15 @@ The cache remains bounded; this does not extend retention or recover history the
+ longer has. HTTP clients must handle the error explicitly and resend their full context without
+ `previous_response_id`. Retrying only the same ID cannot recover missing state.
+
++The same recovery signal applies to routed Responses providers configured with
++`statelessResponses: true`, and to routed requests when a custom tool is lowered to a
++function but a delta result has no local call to establish its original type. Full replay
++preserves the call, result, and reasoning together; opencodex does not guess the result type
++or discard it. Stateful providers can still resolve native function and native-only custom
++continuations themselves. These checks follow the selected wire protocol and tool catalog,
++not the model name. For gateways that cannot resolve stored response IDs, explicitly enable
++`statelessResponses` on that provider; this does not change other providers' defaults.
++
+ ### Authless Codex Desktop (opt-in)
+
+ In **Dashboard → Overview**, **Open Codex without signing in** controls this existing
+diff --git a/docs-site/src/content/docs/ko/guides/codex-integration.md b/docs-site/src/content/docs/ko/guides/codex-integration.md
+index ea7ff40cde..485ad39570 100644
+--- a/docs-site/src/content/docs/ko/guides/codex-integration.md
++++ b/docs-site/src/content/docs/ko/guides/codex-integration.md
+@@ -128,6 +128,15 @@ upstream 요청 전에 `previous_response_not_found`를 반환합니다. Codex W
+ `previous_response_id` 없이 전체 컨텍스트를 다시 보내야 합니다. 같은 ID만 재시도해서는
+ 누락된 상태를 복구할 수 없습니다.
+
++`statelessResponses: true`인 routed Responses provider에도 같은 복구 신호가 적용됩니다.
++또한 routed 경로에서 custom 도구를 function으로 변환하지만 증분 결과에 대응하는
++로컬 호출 기록이 없으면 전체 기록을 요청합니다. 호출, 결과, reasoning을 함께 재생하며
++결과 유형을 추측하거나 버리지 않습니다. 상태를 저장하는 provider의 네이티브 function 및
++네이티브 custom 전용 continuation은 그대로 전달됩니다. 이 검사는 모델명이 아니라 선택된
++wire protocol과 도구 선언을 따릅니다. 저장된 response ID를 복원하지 못하는 gateway에는
++해당 provider의 `statelessResponses`를 명시적으로 활성화하세요. 다른 provider의 기본값은
++바뀌지 않습니다.
++
+ ## 스레드 식별자와 대화 기록
+
+ 기본 loopback 형식은 새 thread에 네이티브 `openai` provider 태그를 유지하므로 일반적인 resume history는 다시 매핑할 필요가 없습니다. sync와 restore는 일치하는 백업 manifest만 적용하여 각 thread의 원래 provider, source, event marker를 정확히 복원합니다. manifest가 없는 `opencodex` row는 변경하지 않으며, legacy 재태깅을 명시적으로 강제하려는 경우에만 `ocx recover-history --legacy-openai --yes`를 사용합니다. 이 명령은 의도적으로 범위가 넓습니다. 사용자 메시지가 있고 현재 `opencodex`로 표시된 모든 thread를 `openai`로 바꾸고, `exec`를 `cli`로 정규화하며 event marker를 설정합니다. 정상적인 dedicated-provider history도 포함됩니다. 상태를 백업하고 이 전체 범위를 의도한 경우에만 사용하세요. non-loopback 전용 provider 모드는 활성 상태일 때만 history를 `opencodex` provider 아래로 미러링하고, 종료할 때는 백업된 메타데이터를 복원합니다. history를 건드리지 않으려면 `syncResumeHistory: false`로 설정하세요.
+diff --git a/docs-site/src/content/docs/reference/configuration/providers.md b/docs-site/src/content/docs/reference/configuration/providers.md
+index f7e8f16abe..f2b73c822f 100644
+--- a/docs-site/src/content/docs/reference/configuration/providers.md
++++ b/docs-site/src/content/docs/reference/configuration/providers.md
+@@ -938,7 +938,8 @@ representation returned to the client, including the visible content-to-summary
+ echoing full history with `previous_response_id` does not duplicate that history. Hidden-summary
+ requests and opaque reasoning blobs retain their existing representation. Cache hits can also
+ supply earlier history for delta continuations;
+-after a cache miss, resend the complete conversation without `previous_response_id`. Stateless
++after a cache miss, the proxy returns `previous_response_not_found` before upstream dispatch so
++the client can resend the complete conversation without `previous_response_id`. Stateless
+ repair labels orphan results and missing tool results; it cannot reconstruct lost history or
+ prove whether a missing tool execution succeeded.
+
+diff --git a/src/responses/custom-tool-compat.ts b/src/responses/custom-tool-compat.ts
+index ce8f9591d1..3577a23256 100644
+--- a/src/responses/custom-tool-compat.ts
++++ b/src/responses/custom-tool-compat.ts
+@@ -261,6 +261,29 @@ export function rewriteRoutedCustomToolsForUpstream(
+   return { body: rewriteForUpstream(body, conversionNames, callIds), names, repairNames };
+ }
+
++/**
++ * A delta result has no tool name. Without its call, lowering cannot tell whether it belongs
++ * to a converted function or a native custom tool. Request full replay instead of guessing.
++ */
++export function hasUnmappedRoutedCustomToolOutput(
++  body: unknown,
++  supportsResponsesCustomTools?: boolean,
++): boolean {
++  if (!isPlainObject(body) || !Array.isArray(body.input)) return false;
++  if (collectRoutedCustomToolNames(body, supportsResponsesCustomTools).size === 0) return false;
++  const callIds = new Set<string>();
++  for (const item of body.input) {
++    if (isPlainObject(item)
++      && (item.type === "custom_tool_call" || item.type === "function_call")
++      && typeof item.call_id === "string") callIds.add(item.call_id);
++  }
++  return body.input.some(item => isPlainObject(item)
++    && item.type === "custom_tool_call_output"
++    && typeof item.call_id === "string"
++    && item.call_id.length > 0
++    && !callIds.has(item.call_id));
++}
++
+ export function restoreRoutedCustomCalls(
+   value: unknown,
+   names: ReadonlySet<string>,
+diff --git a/src/server/responses/core.ts b/src/server/responses/core.ts
+index b961e7cef9..c2b4a92469 100644
+--- a/src/server/responses/core.ts
++++ b/src/server/responses/core.ts
+@@ -394,7 +394,7 @@ import {
+   payloadRewriteAsBlockRewrite,
+   relaySseWithBlockRewrite,
+ } from "../sse-payload-rewrite";
+-import { restoreRoutedCustomCalls, restoreRoutedCustomCallsInJson } from "../../responses/custom-tool-compat";
++import { hasUnmappedRoutedCustomToolOutput, restoreRoutedCustomCalls, restoreRoutedCustomCallsInJson } from "../../responses/custom-tool-compat";
+ import { createRoutedCustomToolRestoreBlockRewrite } from "../responses-custom-tool-repair";
+ import { collectFunctionCallRepairSchemas, repairFunctionCallsInJson } from "../../responses/function-call-compat";
+ import { createResponsesFunctionToolRepairBlockRewrite } from "../responses-function-tool-repair";
+@@ -3673,6 +3673,22 @@ async function handleResponsesInner(
+     );
+   }
+
++  if (hasUnexpandedPreviousResponse) {
++    const continuationProvider = resolveWireProtocolOverride(route.providerName, route.modelId, route.provider, inboundWire);
++    // Stateless destinations cannot resolve the omitted prefix. Stateful destinations may,
++    // but a lowered custom result still needs its call to recover the original wire type.
++    // Native function/custom continuations without lowering keep their upstream-owned state.
++    if (continuationProvider.adapter === "openai-responses"
++      && (continuationProvider.statelessResponses === true
++        || hasUnmappedRoutedCustomToolOutput(parsed._rawBody, continuationProvider.supportsResponsesCustomTools))) {
++      return formatErrorResponse(
++        400,
++        "previous_response_not_found",
++        "Routed continuation requires unavailable local history; resend the full conversation without previous_response_id.",
++      );
++    }
++  }
++
+   // Captured before normalization: whether the CLIENT asked for SSE. The
+   // transport-neutral upstream-streaming policy below may force a bounded JSON
+   // upstream for reliability (#875); the answer must then be reframed to SSE
+diff --git a/src/types/provider.ts b/src/types/provider.ts
+index b51230d6d1..feae0898ce 100644
+--- a/src/types/provider.ts
++++ b/src/types/provider.ts
+@@ -230,8 +230,8 @@ export interface OcxProviderConfig {
+   /**
+    * Responses upstream that stores nothing server-side (DeepSeek documents "the API
+    * is stateless"). Stateful request parameters are dropped, `store` is pinned false,
+-   * and orphaned tool results left by a replay miss are repaired rather than
+-   * forwarded to an upstream that cannot resolve their pair.
++   * and missing local continuation history returns previous_response_not_found so
++   * clients can resend full input. Explicit input still receives orphan-item repair.
+    */
+   statelessResponses?: boolean;
+   /**
+diff --git a/structure/04_transports-and-sidecars.md b/structure/04_transports-and-sidecars.md
+index c98c837cec..fc0634da8b 100644
+--- a/structure/04_transports-and-sidecars.md
++++ b/structure/04_transports-and-sidecars.md
+@@ -413,7 +413,10 @@ logic fills absent values and preserves explicit false; renamed custom configura
+ no new destination-based migration. The existing stateless pass sets `store: false`, removes
+ stored continuation parameters, and repairs orphan calls/results without claiming execution
+ success. A local replay-cache hit supplies history; a miss cannot reconstruct it, so callers
+-must resend complete history without `previous_response_id`. This flag also enables the existing
++receive `previous_response_not_found` before upstream dispatch and must resend complete history
++without `previous_response_id`. Routed custom-tool lowering also requires this recovery when a
++delta result lacks its call and the original wire type cannot be established. Stateful native
++function and native-only custom continuations retain upstream-owned resolution. This flag also enables the existing
+ visible content-to-summary rewrite for SSE and JSON; summary-channel items and opaque reasoning
+ blobs keep their existing response handling. The shared recording callback applies the same
+ reasoning rewrite under the exact client-visible predicate before caching output, after tool
+diff --git a/tests/codex-integration/issue-702-expired-replay-state.test.ts b/tests/codex-integration/issue-702-expired-replay-state.test.ts
+index 13b96be638..1a9b3bd092 100644
+--- a/tests/codex-integration/issue-702-expired-replay-state.test.ts
++++ b/tests/codex-integration/issue-702-expired-replay-state.test.ts
+@@ -286,6 +286,126 @@ afterEach(() => {
+   else process.env.OPENCODEX_API_AUTH_TOKEN = previousApiToken;
+ });
+
++describe("routed replay recovery", () => {
++  test.each([
++    { stateless: true, custom: false, expired: false },
++    { stateless: true, custom: false, expired: true },
++    { stateless: false, custom: true, expired: false },
++    { stateless: false, custom: true, expired: true },
++    { stateless: false, custom: true, expired: false, authMode: "forward" },
++    { stateless: true, custom: false, expired: false, adapter: "openai-chat" },
++  ] as const)("recovers missing history without orphaning tool results: %j", async scenario => {
++    const { stateless, custom, expired } = scenario;
++    const upstreamRequests: Record<string, unknown>[] = [];
++    const realNow = Date.now;
++    const toolCall = custom
++      ? { type: "custom_tool_call", call_id: "call_replay", name: "exec", input: "text(1)", status: "completed" }
++      : { type: "function_call", call_id: "call_replay", name: "lookup", arguments: "{}", status: "completed" };
++    const toolResult = {
++      type: custom ? "custom_tool_call_output" : "function_call_output",
++      call_id: "call_replay", output: "1",
++    };
++    const reasoning = { type: "reasoning", content: [{ type: "reasoning_text", text: "Use the lookup result." }] };
++    const history = [inputMessage(HISTORICAL_USER_SENTINEL), reasoning, toolCall];
++    const tools = custom
++      ? [{ type: "custom", name: "exec", description: "Run JavaScript", format: { type: "text" } }]
++      : [{ type: "function", name: "lookup", parameters: { type: "object", properties: {} } }];
++    const upstream = Bun.serve({
++      port: 0,
++      async fetch(request) {
++        const body = await request.json() as Record<string, unknown>;
++        upstreamRequests.push(body);
++        const items = body.input as Array<Record<string, unknown>>;
++        // A strict upstream cannot resolve a tool result without its matching function call.
++        if (!items.some(item => item.type === "function_call" && item.call_id === "call_replay")
++          || !items.some(item => item.type === "function_call_output" && item.call_id === "call_replay")) {
++          return Response.json({ error: { type: "invalid_request_error", message: "No matching tool call" } }, { status: 400 });
++        }
++        return new Response(completedSse("resp_routed_recovered", "recovered"), {
++          headers: { "content-type": "text/event-stream" },
++        });
++      },
++    });
++    let server: ReturnType<typeof startServer> | null = null;
++    let socket: WebSocket | null = null;
++    try {
++      if (expired) {
++        Date.now = () => realNow() - EXPIRED_AGE_MS;
++        rememberResponseState(
++          { input: [history[0]], tools, store: false },
++          { id: FIRST_RESPONSE_ID, status: "completed", output: [reasoning, toolCall] },
++          undefined, { force: true },
++        );
++        Date.now = realNow;
++      }
++      saveConfig({
++        port: 0, hostname: "127.0.0.1", websockets: true, defaultProvider: "routed-test",
++        providers: {
++          "routed-test": {
++            adapter: "adapter" in scenario ? scenario.adapter : "openai-responses",
++            modelAdapters: { "test-model": "openai-responses" },
++            baseUrl: upstream.url.toString(), allowPrivateNetwork: true,
++            authMode: "authMode" in scenario ? scenario.authMode : "key", apiKey: "synthetic-key", defaultModel: "test-model",
++            statelessResponses: stateless, preserveResponsesReasoningContent: true,
++          },
++        },
++      } as OcxConfig);
++      server = startServer(0);
++      const deltaRequest = {
++        model: "routed-test/test-model", previous_response_id: FIRST_RESPONSE_ID,
++        input: [toolResult], tools, store: false,
++      };
++      const httpRejected = await originalFetch(new URL("/v1/responses", server.url), {
++        method: "POST", headers: { "content-type": "application/json" },
++        body: JSON.stringify(deltaRequest),
++      });
++      expect(httpRejected.status).toBe(400);
++      expect(await httpRejected.json()).toMatchObject({ error: { code: "previous_response_not_found" } });
++      expect(upstreamRequests).toHaveLength(0);
++      socket = await openResponseSocket(server.url, {});
++      const rejected = await sendSocketTurn(socket, deltaRequest);
++      expect(rejected).toMatchObject({
++        type: "error", status: 400,
++        error: { type: "invalid_request_error", code: "previous_response_not_found" },
++      });
++      expect(upstreamRequests).toHaveLength(0);
++
++      socket.close();
++      socket = await openResponseSocket(server.url, {});
++      const recovered = await sendSocketTurn(socket, {
++        model: "routed-test/test-model", input: [...history, toolResult], tools, store: false,
++      });
++      expect(recovered.type).toBe("response.completed");
++      expect(upstreamRequests).toHaveLength(1);
++      expect(upstreamRequests[0]!.previous_response_id).toBeUndefined();
++      expect(upstreamRequests[0]!.input).toEqual([
++        history[0], reasoning,
++        { type: "function_call", call_id: "call_replay", name: custom ? "exec" : "lookup",
++          arguments: custom ? JSON.stringify({ input: "text(1)" }) : "{}", status: "completed" },
++        { ...toolResult, type: "function_call_output" },
++      ]);
++      await waitForRecordedResponseState();
++
++      // Recovery must seed complete local history so the next delta does not repeat the miss.
++      const continued = await sendSocketTurn(socket, {
++        model: "routed-test/test-model", previous_response_id: "resp_routed_recovered",
++        input: [inputMessage(CURRENT_USER_SENTINEL)], tools, store: false,
++      });
++      expect(continued.type).toBe("response.completed");
++      expect(upstreamRequests).toHaveLength(2);
++      expect(upstreamRequests[1]!.previous_response_id).toBeUndefined();
++      const items = upstreamRequests[1]!.input as Array<Record<string, unknown>>;
++      expect(items.filter(item => item.call_id === "call_replay")).toHaveLength(2);
++      expect(items.at(-1)).toEqual(inputMessage(CURRENT_USER_SENTINEL));
++    } finally {
++      Date.now = realNow;
++      socket?.close();
++      await server?.stop(true);
++      await upstream.stop(true);
++    }
++  }, SERVER_BUDGET_MS);
++});
++
+ describe("Issue #702 expired forward replay state", () => {
+   test("known continuation spill failure returns terminal structured previous_response_not_found before upstream I/O", async () => {
+     const responseId = "resp_issue_702_missing_spill";
+@@ -512,7 +632,7 @@ describe("Issue #702 expired forward replay state", () => {
+     expect(JSON.stringify(scenario.upstreamRequests[0]!.body)).toContain(HISTORICAL_USER_SENTINEL);
+   });
+
+-  test("API-key Responses providers can still forward native previous_response_id state", async () => {
++  test.each(["message", "function", "custom"] as const)("API-key Responses providers can still forward native %s continuation state", async kind => {
+     const upstreamRequests: Record<string, unknown>[] = [];
+     const realNow = Date.now;
+     let upstream: ReturnType<typeof Bun.serve> | null = null;
+@@ -539,6 +659,7 @@ describe("Issue #702 expired forward replay state", () => {
+             allowPrivateNetwork: true,
+             apiKey: "provider-key",
+             defaultModel: "gpt-5.5",
++            statelessResponses: false,
+           },
+         },
+       } as OcxConfig);
+@@ -551,6 +672,12 @@ describe("Issue #702 expired forward replay state", () => {
+           model: "test-openai/gpt-5.5",
+           previous_response_id: "resp_upstream_native_state",
+           input: [inputMessage(CURRENT_USER_SENTINEL)],
++          ...(kind === "message" ? {} : {
++            tools: [kind === "custom"
++              ? { type: "custom", name: "apply_patch", description: "Apply patch", format: { type: "text" } }
++              : { type: "function", name: "lookup", parameters: { type: "object", properties: {} } }],
++            input: [{ type: kind === "custom" ? "custom_tool_call_output" : "function_call_output", call_id: "call_native", output: "done" }],
++          }),
+           stream: true,
+         }),
+       });
+@@ -558,6 +685,9 @@ describe("Issue #702 expired forward replay state", () => {
+       await response.text();
+       expect(upstreamRequests).toHaveLength(1);
+       expect(upstreamRequests[0]!.previous_response_id).toBe("resp_upstream_native_state");
++      if (kind !== "message") expect(upstreamRequests[0]!.input).toEqual([
++        { type: kind === "custom" ? "custom_tool_call_output" : "function_call_output", call_id: "call_native", output: "done" },
++      ]);
+     } finally {
+       Date.now = realNow;
+       globalThis.fetch = originalFetch;
+diff --git a/tests/responses/custom-tool-compat.test.ts b/tests/responses/custom-tool-compat.test.ts
+index 530238c499..adfb2105c0 100644
+--- a/tests/responses/custom-tool-compat.test.ts
++++ b/tests/responses/custom-tool-compat.test.ts
+@@ -1,5 +1,5 @@
+ import { describe, expect, test } from "bun:test";
+-import { rewriteRoutedCustomToolsForUpstream } from "../../src/responses/custom-tool-compat";
++import { hasUnmappedRoutedCustomToolOutput, rewriteRoutedCustomToolsForUpstream } from "../../src/responses/custom-tool-compat";
+
+ function convertedInputDescription(name: string): string | undefined {
+   const result = rewriteRoutedCustomToolsForUpstream({
+@@ -14,6 +14,51 @@ function convertedInputDescription(name: string): string | undefined {
+ }
+
+ describe("routed custom-tool compatibility", () => {
++  test("requires replay for ambiguous delta results without guessing their native or lowered type", () => {
++    const exec = { type: "custom", name: "exec", description: "Run JavaScript" };
++    const patch = { type: "custom", name: "apply_patch", description: "Apply a patch" };
++    const result = { type: "custom_tool_call_output", call_id: "call_sample", output: "done" };
++    const body = { tools: [exec, patch], input: [result] };
++    expect(hasUnmappedRoutedCustomToolOutput(body)).toBe(true);
++    expect(body.input).toEqual([result]);
++    // A native patch result with its known call remains native, even with exec declared.
++    const knownPatch = { ...body, input: [
++      { type: "custom_tool_call", name: "apply_patch", call_id: "call_sample", input: "patch" }, result,
++    ] };
++    expect(hasUnmappedRoutedCustomToolOutput(knownPatch)).toBe(false);
++    expect((rewriteRoutedCustomToolsForUpstream(knownPatch).body as typeof knownPatch).input[1]).toEqual(result);
++    // A complete lowered call/result pair can use the existing lossless conversion.
++    const knownExec = { ...body, input: [
++      { type: "custom_tool_call", name: "exec", call_id: "call_sample", input: "text(1)" }, result,
++    ] };
++    expect(hasUnmappedRoutedCustomToolOutput(knownExec)).toBe(false);
++    expect((rewriteRoutedCustomToolsForUpstream(knownExec).body as typeof knownExec).input[1]!.type).toBe("function_call_output");
++  });
++
++  test("preserves native-only continuations and follows explicit custom-tool lowering", () => {
++    const result = { type: "custom_tool_call_output", call_id: "call_sample", output: "done" };
++    const patchOnly = { tools: [{ type: "custom", name: "apply_patch" }], input: [result] };
++    expect(hasUnmappedRoutedCustomToolOutput(patchOnly)).toBe(false);
++    expect(hasUnmappedRoutedCustomToolOutput(patchOnly, true)).toBe(false);
++    expect(hasUnmappedRoutedCustomToolOutput(patchOnly, false)).toBe(true);
++    expect(hasUnmappedRoutedCustomToolOutput({ input: [result] })).toBe(false);
++    expect(hasUnmappedRoutedCustomToolOutput({
++      tools: [{ type: "custom", name: "exec" }],
++      input: [{ ...result, type: "function_call_output" }],
++    })).toBe(false);
++  });
++
++  test("detects lowered results when the current catalog is nested or supplied by additional_tools", () => {
++    const result = { type: "custom_tool_call_output", call_id: "call_sample", output: "done" };
++    const tool = { type: "custom", name: "exec", description: "Run JavaScript" };
++    expect(hasUnmappedRoutedCustomToolOutput({
++      tools: [{ type: "namespace", name: "functions", tools: [tool] }], input: [result],
++    })).toBe(true);
++    expect(hasUnmappedRoutedCustomToolOutput({
++      input: [{ type: "additional_tools", tools: [tool] }, result],
++    })).toBe(true);
++  });
++
+   test.each([
+     ["absent", undefined],
+     ["true", true],
+```
+
+## Current-tree map and reflection
+
+D1/D2/D3 accepted ALIGNED. Baseline d8df1b1064a846ecfff0d924e9395a1c16bf3504; historical source-PR parent differs. MODIFY src/responses/custom-tool-compat.ts, src/server/responses/core.ts, src/types/provider.ts and both existing test files from the pinned diff; English/Korean integration guides and providers.md receive the same pending contract. No new files.
+
+MODIFY structure/transports/responses.md as primary contract. Add concise ownership links in runtime.md, catalog.md, subagents.md, adapters/registry.md, transports/streaming-health.md, transports/inventory.md, data-planes/images.md, data-planes/inbound-compat.md, providers/kiro.md, providers/xai-grok.md, providers/chat-compat.md, gui-and-management-api.md, clients/claude-desktop.md, ops/service-and-sidecars.md and ops/docs-and-release.md. Do not recreate structure/04_transports-and-sidecars.md or edit generated INDEX.md.
diff --git a/devlog/_plan/260912_history_containment/030_relay.md b/devlog/_plan/260912_history_containment/030_relay.md
new file mode 100644
index 0000000000..8fb1675a47
--- /dev/null
+++ b/devlog/_plan/260912_history_containment/030_relay.md
@@ -0,0 +1,1594 @@
+# Relay source-pinned change design
+
+Source: PR #3663 at 8e0b53b0f96ae840c0ce836c043174aac98816a2. Initial carry uses the following public diff, revalidated against current dev at phase P. Every diff header is the exact NEW/MODIFY file map. Main resolves conflicts against current owners; no wholesale replacement from a stale head.
+
+Before: current merge-base behavior in removed lines. After: added lines below. Tests are authored but NOT RUN locally; final-tip hosted CI observes these files. No new dependency or persisted schema is introduced by containment/continuation; relay owner state remains bounded/process-local and needs separate security review.
+
+Disposition-first: carry only after owner/auth audit; inspect existing listener admission and accepted-attempt ownership. Known/unknown/expired/conflicting owners, failover, direct caller and proxy bearer cases are covered by source regressions below. Native live-account smoke is not authorized and cannot be claimed. Public diff only; new findings stay scratch.
+
+```diff
+diff --git a/docs-site/src/content/docs/guides/codex-integration.md b/docs-site/src/content/docs/guides/codex-integration.md
+index b2ae7fcb91..b7bc5aecec 100644
+--- a/docs-site/src/content/docs/guides/codex-integration.md
++++ b/docs-site/src/content/docs/guides/codex-integration.md
+@@ -57,6 +57,63 @@ The proxy listens on port `10100` by default and serves `POST /v1/responses`,
+ `POST /v1/responses/compact`, `POST /v1/images/generations`, `POST /v1/images/edits`,
+ `GET /v1/models`, `GET /healthz`, and the `/api/*` management surface.
+
++### Experimental context management (Codex 0.153+)
++
++For an eligible ChatGPT account, enable the experimental feature in Codex's own
++`config.toml` (merge this into an existing `[features]` table):
++
++```toml
++[features]
++context_management.experimental_mode = true
++```
++
++On the default built-in loopback integration, the next `ocx sync` or proxy start changes the
++managed root `openai_base_url` to `http://127.0.0.1:10100/backend-api/codex`. Codex checks this
++backend path before enabling its `new_context`, history, and notes tools. Start a new Codex
++session after synchronization. The feature remains opt-in; user-owned base URLs and remote
++custom-provider injection are not rewritten. No context-window or compaction-limit override
++is needed or added.
++
++The backend prefix aliases the existing data-plane routes, including Responses WebSocket
++upgrades. The original `/v1` routes and the realtime sideband override remain available. The
++proxy also relays the ten native `alpha/history/v2/*` and `alpha/notes/v2/*` POST endpoints
++through the built-in `openai` provider with the `openai-responses` adapter and canonical
++ChatGPT forward destination. Direct uses the current caller/main login; Pool selects a Codex
++account. `openai-apikey` uses its configured API key, and custom or noncanonical Responses
++providers are not candidates for this context relay and receive no Codex-account credentials
++from it. These private endpoints are not implemented by other model providers or the OpenAI
++API-key route.
++
++Caller headers are restricted to the shared Codex forward allowlist: `authorization`,
++`chatgpt-account-id`, and approved OpenAI beta, originator, session, and Codex protocol metadata.
++The context relay additionally forwards `x-openai-encrypted-tool-arguments` and
++`x-openai-tool-output-truncation-policy`; arbitrary caller headers such as cookies are not
++forwarded. A proxy data-plane key presented as a bearer is replaced with the selected Codex
++credential (the stored main login in Direct); missing credentials fail before forwarding.
++Proxy admission credentials never go upstream. Encrypted arguments, response bodies, and
++upstream error statuses are preserved.
++
++A successful ChatGPT model response records the root session's actual serving account in a
++bounded, process-local ownership registry. History and notes use that recorded owner, including
++an explicitly selected account, even when the current active account changes. Stored-account token
++refresh may continue for the same physical account; a replaced account identity is rejected.
++Direct caller-owned sessions keep the caller credential and cannot be taken over by a proxy bearer.
++This does not migrate server-side history between accounts.
++
++Unknown, expired, evicted, conflicting, or restart-lost ownership returns HTTP 409 before account
++selection or upstream I/O. The relay does not guess from the current active account. Existing
++sessions should save a checkpoint or other durable summary before enabling the feature or resetting
++context. Enabling it does not backfill earlier history or notes, and a new ownership observation
++does not prove that older backend content exists. After a restart, establish ownership with a
++successful model request before using context tools; start a new session when ownership conflicts.
++
++Existing model affinity, cooldown, and retry rules are unchanged. Context requests are not
++automatically retried, including notes writes; ChatGPT forward requests do not use same-key 429
++replay. History traffic does not consume or settle a model quota-recovery probe.
++
++To disable the feature, remove the experimental key (or set it to `false`), run `ocx sync`,
++and start a new Codex session. The managed root base returns to `/v1`.
++
+ ### Built-in image generation (`image_gen`)
+
+ Codex's built-in `image_gen` tool does not go through `/v1/responses` — the codex-rs extension
+diff --git a/docs-site/src/content/docs/ko/guides/codex-integration.md b/docs-site/src/content/docs/ko/guides/codex-integration.md
+index 3f777153ec..7dc14176c6 100644
+--- a/docs-site/src/content/docs/ko/guides/codex-integration.md
++++ b/docs-site/src/content/docs/ko/guides/codex-integration.md
+@@ -40,6 +40,61 @@ loopback `openai_base_url` 형태에서만 쓰이고, 그 키와 함께 제거
+
+ 프록시는 기본적으로 포트 `10100`에서 듣고 `POST /v1/responses`, `POST /v1/responses/compact`, `POST /v1/images/generations`, `POST /v1/images/edits`, `GET /v1/models`, `GET /healthz`, 그리고 `/api/*` 관리 표면을 제공합니다.
+
++### 실험적 컨텍스트 관리 (Codex 0.153+)
++
++지원되는 ChatGPT 계정에서는 Codex의 `config.toml`에 다음 설정을 추가합니다.
++기존 `[features]` 테이블이 있으면 그 안에 병합하세요.
++
++```toml
++[features]
++context_management.experimental_mode = true
++```
++
++기본 내장 loopback 통합에서는 다음 `ocx sync` 또는 프록시 시작 시 관리되는 루트
++`openai_base_url`이 `http://127.0.0.1:10100/backend-api/codex`로 바뀝니다. Codex는 이 경로를
++확인한 뒤 `new_context`, history, notes 도구를 활성화합니다. 동기화 후 새 Codex 세션을
++시작하세요. 이 기능은 명시적으로 켜야 하며, 사용자 소유 URL과 원격 사용자 지정 provider
++주입은 변경하지 않습니다. 컨텍스트 창이나 압축 한도를 덮어쓰지 않습니다.
++
++이 backend 접두사는 Responses WebSocket 업그레이드를 포함한 기존 데이터 경로의 별칭입니다.
++원래 `/v1` 경로와 realtime sideband 오버라이드도 유지됩니다. 열 개의 네이티브
++`alpha/history/v2/*`, `alpha/notes/v2/*` POST 엔드포인트는 `openai-responses` 어댑터와 정식
++ChatGPT forward 목적지를 사용하는 내장 `openai` provider로만 전달합니다. Direct는 현재
++호출자/메인 로그인을, Pool은 선택된 Codex 계정을 사용합니다. `openai-apikey`는 설정된 API
++키를 사용하는 별도 경로이며 이 비공개 엔드포인트를 지원하지 않습니다. 사용자 지정 또는
++비정식 Responses provider는 이 컨텍스트 relay의 후보가 아니며 Codex 계정 자격 증명을
++전달받지 않습니다.
++
++호출자 헤더는 공통 Codex forward 허용 목록으로 제한됩니다. `authorization`,
++`chatgpt-account-id`, 승인된 OpenAI beta, originator, session 및 Codex 프로토콜 메타데이터와
++추가 헤더 `x-openai-encrypted-tool-arguments`, `x-openai-tool-output-truncation-policy`만
++전달합니다. 쿠키 등 임의 헤더는 전달하지 않습니다. 프록시 데이터 키를 bearer로 사용하면
++선택된 Codex 자격 증명으로 교체하며, Direct에서는 저장된 메인 로그인을 사용합니다.
++자격 증명이 없으면 전달 전에 실패합니다. 프록시 인증 자격 증명은 upstream으로 보내지
++않습니다. 암호화된 인수, 응답 본문, upstream 오류 상태는 보존합니다.
++
++성공한 ChatGPT 모델 응답은 루트 세션을 실제로 처리한 계정을 크기가 제한된 프로세스 로컬
++소유권 레지스트리에 기록합니다. History와 notes는 현재 활성 계정이 바뀌어도 명시적으로
++선택된 계정을 포함해 기록된 소유 계정을 사용합니다. 저장된 계정의 토큰은 같은 실제 계정에
++한해 갱신할 수 있으며, 다른 실제 계정으로 교체되면 거부합니다. Direct 호출자 소유 세션은
++호출자 자격 증명을 유지하며 프록시 bearer로 인계할 수 없습니다. 서버 측 history를 계정 간에
++이동하는 기능은 아닙니다.
++
++소유권이 없거나 만료, 제거, 충돌 또는 재시작으로 소실된 경우 계정 선택이나 upstream 요청
++전에 HTTP 409를 반환합니다. 현재 활성 계정으로 추측하지 않습니다. 기존 세션에서는 기능을
++켜거나 컨텍스트를 초기화하기 전에 체크포인트 또는 지속적으로 보관할 요약을 먼저 저장하세요.
++기능을 켜도 이전 history나 notes를 소급해서 채우지 않으며, 소유권이 새로 확인되어도 이전
++backend 콘텐츠가 존재한다는 뜻은 아닙니다. 재시작 후에는 성공한 모델 요청으로 소유권을
++확립한 뒤 컨텍스트 도구를 사용하고, 소유권이 충돌하면 새 세션을 시작하세요.
++
++기존 모델 affinity, cooldown 및 재시도 규칙은 변경하지 않습니다. Notes 쓰기를 포함한
++컨텍스트 요청은 자동 재시도하지 않으며, ChatGPT forward 요청에 같은 키를 사용한 429
++재시도를 추가하지 않습니다. History 트래픽은 모델의 quota-recovery probe를 점유하거나
++완료 처리하지 않습니다.
++
++끄려면 실험 설정을 삭제하거나 `false`로 바꾼 뒤 `ocx sync`를 실행하고 새 세션을 시작하세요.
++관리되는 루트 URL은 `/v1`로 돌아갑니다.
++
+ ### 내장 이미지 생성 (`image_gen`)
+
+ Codex의 내장 `image_gen` 도구는 `/v1/responses`를 거치지 않습니다. codex-rs 확장은 채팅과 같은 ChatGPT bearer 인증을 사용해서 `{base_url}/images/generations`를 직접 POST하며, 참조 이미지가 붙어 있으면 `/images/edits`를 POST합니다. 주입된 `base_url`이 opencodex를 가리키므로, 프록시가 이 호출을 OpenAI upstream으로 전달합니다.
+diff --git a/scripts/test-layout/layout.json b/scripts/test-layout/layout.json
+index 7d312309ce..b72066c1d2 100644
+--- a/scripts/test-layout/layout.json
++++ b/scripts/test-layout/layout.json
+@@ -11,7 +11,7 @@
+   "domains": {
+     "providers": {
+       "match": [
+-        "^(?:aside|auto|azure|baseten|chutes|cline|command|commandcode|context|cyber|deepinfra|deepseek|digitalocean|exa|featherless|forward|hyperbolic|kimi|meta|mimo|minimax|moonshot|muse|new|nous|novita|nscale|nvidia|opencode|openrouter|qwen38|sambanova|umans|vercel|zcode|zhipu)-"
++        "^(?:aside|auto|azure|baseten|chutes|cline|command|commandcode|context(?!-compat|-history)|cyber|deepinfra|deepseek|digitalocean|exa|featherless|forward|hyperbolic|kimi|meta|mimo|minimax|moonshot|muse|new|nous|novita|nscale|nvidia|opencode|openrouter|qwen38|sambanova|umans|vercel|zcode|zhipu)-"
+       ],
+       "children": {
+         "cursor": [
+@@ -33,11 +33,13 @@
+     },
+     "codex-integration": {
+       "match": [
++        "^context-compat\\.test\\.ts$",
+         "^(?:active|app|bearer|catalog|combos\\.test\\.ts|doctor\\.test\\.ts|effort|gather|history|injection|issue|multi|native|parallel|project|selected|slug|ultrafast|warmup\\.test\\.ts)-"
+       ]
+     },
+     "server": {
+       "match": [
++        "^context-history\\.test\\.ts$",
+         "^(?:account|alias|bounded|cancel|config\\.test\\.ts|consume|data|debug|error|errors|fetch|health|input|loopback|management|memory|outbound|owned|passive|port|ports\\.test\\.ts|proxy|relay|response|retry|server|session|sidebar|stream|v2)-"
+       ]
+     },
+@@ -378,6 +380,7 @@
+     "codex-cli-update-zero-effect.test.ts": "codex-integration",
+     "codex-composed-acceptance.test.ts": "codex-integration",
+     "codex-config-generation.test.ts": "codex-integration",
++    "codex-context-owner.test.ts": "codex-integration",
+     "codex-convergence-account-selectors.test.ts": "codex-integration",
+     "codex-convergence-contract.test.ts": "codex-integration",
+     "codex-cooldown-recovery.test.ts": "codex-integration",
+@@ -493,6 +496,9 @@
+     "consume-for-inspection-cancel.test.ts": "server",
+     "container-bootstrap.test.ts": "service",
+     "context-cap-unknown-window.test.ts": "providers",
++    "context-compat.test.ts": "codex-integration",
++    "context-history-ownership.test.ts": "server",
++    "context-history.test.ts": "server",
+     "continuation-dedup.test.ts": "responses",
+     "core-lab-boundary.test.ts": "lab",
+     "cost-cap-unknown-evidence.test.ts": "usage",
+diff --git a/src/codex/context-compat.ts b/src/codex/context-compat.ts
+new file mode 100644
+index 0000000000..8158ec728a
+--- /dev/null
++++ b/src/codex/context-compat.ts
+@@ -0,0 +1,42 @@
++/** Backend path and opt-in config compatibility for native Codex history/notes. */
++export const CONTEXT_BACKEND_PREFIX = "/backend-api/codex";
++
++const CONTEXT_ENDPOINTS = new Set([
++  "alpha/history/v2/list_windows", "alpha/history/v2/list_items",
++  "alpha/history/v2/read_item", "alpha/history/v2/search_contents",
++  "alpha/notes/v2/thread_hint", "alpha/notes/v2/list_files_by_prefix",
++  "alpha/notes/v2/read_file", "alpha/notes/v2/search_contents",
++  "alpha/notes/v2/append_to_file", "alpha/notes/v2/write_file",
++]);
++
++export function contextEndpoint(path: string): string | undefined {
++  const endpoint = path.startsWith("/v1/") ? path.slice(4) : "";
++  return CONTEXT_ENDPOINTS.has(endpoint) ? endpoint : undefined;
++}
++
++/** Alias only the data-plane prefix. Existing auth/origin and route gates still run. */
++export function codexCompatibleUrl(rawUrl: string): URL {
++  const url = new URL(rawUrl);
++  if (url.pathname === CONTEXT_BACKEND_PREFIX || url.pathname.startsWith(CONTEXT_BACKEND_PREFIX + "/")) {
++    url.pathname = "/v1" + url.pathname.slice(CONTEXT_BACKEND_PREFIX.length);
++  }
++  return url;
++}
++
++/** Change only marker-managed built-in routing, and only with an explicit context opt-in. */
++export function contextCompatibleBaseLine(content: string, line: string): string {
++  let parsed: {features?: {context_management?: {experimental_mode?: boolean}}};
++  try {
++    parsed = Bun.TOML.parse(content) as typeof parsed;
++  } catch {
++    // Injection tolerates incomplete user config; malformed TOML is not an opt-in.
++    return line;
++  }
++  if (parsed.features?.context_management?.experimental_mode !== true) return line;
++  const match = /^openai_base_url = "([^"]+)"$/.exec(line);
++  if (!match) return line;
++  const url = new URL(match[1]);
++  if (url.pathname !== "/v1" || !["127.0.0.1", "localhost", "[::1]"].includes(url.hostname)) return line;
++  url.pathname = CONTEXT_BACKEND_PREFIX;
++  return `openai_base_url = "${url.href}"`;
++}
+diff --git a/src/codex/context-owner.ts b/src/codex/context-owner.ts
+new file mode 100644
+index 0000000000..cf0149c139
+--- /dev/null
++++ b/src/codex/context-owner.ts
+@@ -0,0 +1,141 @@
++import { createHmac, randomBytes } from "node:crypto";
++import type { CodexAuthContext } from "./auth-context";
++import { MAIN_CODEX_ACCOUNT_ID } from "./account-id";
++
++export type ContextSessionOwner = Readonly<
++  | { kind: "stored"; accountId: string; physicalIdentity: string; ambiguous: boolean }
++  | { kind: "caller"; physicalIdentity?: string; callerCredentialIdentity: string; ambiguous: boolean }
++>;
++
++const TTL_MS = 24 * 60 * 60_000;
++const MAX_ENTRIES = 2048;
++const MAX_BYTES = 1024 * 1024;
++const salt = randomBytes(32);
++type Entry = { owner: ContextSessionOwner; destination: string; touchedAt: number; bytes: number };
++const owners = new Map<string, Entry>();
++let totalBytes = 0;
++
++function digest(domain: string, value: string): string {
++  return createHmac("sha256", salt).update(domain).update("\0").update(value).digest("hex");
++}
++
++function validId(value: string | null | undefined): value is string {
++  return typeof value === "string" && /^[A-Za-z0-9._:-]{1,512}$/.test(value);
++}
++
++function destinationIdentity(destination: string): string | undefined {
++  if (!destination || destination.length > 4096) return undefined;
++  try {
++    const url = new URL(destination);
++    if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.hash) return undefined;
++    return digest("destination", url.href.replace(/\/+$/, ""));
++  } catch { return undefined; }
++}
++
++function physicalIdentity(headers: Headers): string | undefined {
++  const account = headers.get("chatgpt-account-id");
++  return validId(account) ? digest("physical-account", account) : undefined;
++}
++
++function callerCredentialIdentity(headers: Headers): string | undefined {
++  const authorization = headers.get("authorization");
++  if (!authorization || authorization.length > 32_768 || !/^Bearer [^\s]+$/i.test(authorization)) return undefined;
++  const account = headers.get("chatgpt-account-id");
++  if (account !== null && !validId(account)) return undefined;
++  return digest("caller-credential", JSON.stringify([authorization.slice(7), account]));
++}
++
++function remove(key: string): void {
++  const prior = owners.get(key);
++  if (!prior) return;
++  owners.delete(key);
++  totalBytes -= prior.bytes;
++}
++
++function sweep(now: number): void {
++  for (const [key, entry] of owners) {
++    if (now < entry.touchedAt || now - entry.touchedAt >= TTL_MS) remove(key);
++  }
++}
++
++/** Called only after a model attempt was accepted by its actual destination. */
++export function recordContextSessionOwner(
++  inboundHeaders: Headers, destination: string, auth: CodexAuthContext,
++  outboundHeaders: Headers, substituteMainCredential: boolean, now = Date.now(),
++): void {
++  if (!Number.isFinite(now)) return;
++  // A malformed explicit parent must not fall back to an unrelated local session.
++  const root = inboundHeaders.get("x-codex-parent-thread-id") ?? inboundHeaders.get("session-id");
++  if (!validId(root)) return;
++  const destinationKey = destinationIdentity(destination);
++  const credential = callerCredentialIdentity(outboundHeaders);
++  if (!destinationKey || !credential) return;
++  const physical = physicalIdentity(outboundHeaders);
++  let owner: ContextSessionOwner;
++  if (auth.kind !== "main" || substituteMainCredential) {
++    if (!physical) return;
++    if (auth.kind !== "main" && (!validId(auth.accountId)
++      || auth.chatgptAccountId !== outboundHeaders.get("chatgpt-account-id"))) return;
++    // Direct proxy-bearer substitution has no token snapshot in its `main` context;
++    // its accepted outbound identity is still evidence for the stored main slot.
++    owner = { kind: "stored", accountId: auth.kind === "main" ? MAIN_CODEX_ACCOUNT_ID : auth.accountId,
++      physicalIdentity: physical, ambiguous: false };
++  } else {
++    owner = { kind: "caller", ...(physical ? { physicalIdentity: physical } : {}),
++      callerCredentialIdentity: credential, ambiguous: false };
++  }
++  sweep(now);
++  const key = digest("root-session", root);
++  const prior = owners.get(key);
++  if (prior) {
++    const samePhysical = prior.owner.physicalIdentity !== undefined && physical !== undefined
++      ? prior.owner.physicalIdentity === physical
++      : prior.owner.kind === "caller" && owner.kind === "caller"
++        && prior.owner.physicalIdentity === undefined && owner.physicalIdentity === undefined
++        && prior.owner.callerCredentialIdentity === owner.callerCredentialIdentity;
++    if (prior.owner.ambiguous || prior.destination !== destinationKey
++      || prior.owner.kind !== owner.kind || !samePhysical) {
++      // Once two accepted attempts prove conflicting ownership, no later write can
++      // silently choose which account contains this session's history.
++      owner = { ...prior.owner, ambiguous: true };
++    }
++  }
++  const ownerDestination = prior?.destination ?? destinationKey;
++  const bytes = Buffer.byteLength(JSON.stringify([key, ownerDestination, owner]), "utf8");
++  remove(key);
++  owners.set(key, { owner: Object.freeze(owner), destination: ownerDestination, touchedAt: now, bytes });
++  totalBytes += bytes;
++  while (owners.size > MAX_ENTRIES || totalBytes > MAX_BYTES) {
++    const oldest = owners.keys().next().value;
++    if (oldest === undefined) break;
++    remove(oldest);
++  }
++}
++
++/** Missing/expired/evicted ownership is unknown; never infer it from active routing. */
++export function getContextSessionOwner(
++  sessionId: string, destination: string, now = Date.now(),
++): ContextSessionOwner | undefined {
++  if (!validId(sessionId) || !Number.isFinite(now)) return undefined;
++  const destinationKey = destinationIdentity(destination);
++  if (!destinationKey) return undefined;
++  sweep(now);
++  const key = digest("root-session", sessionId);
++  const entry = owners.get(key);
++  if (!entry || entry.destination !== destinationKey) return undefined;
++  owners.delete(key);
++  entry.touchedAt = now;
++  owners.set(key, entry);
++  return entry.owner;
++}
++
++/** Compare only already-materialized headers; this function never reads credentials. */
++export function contextSessionOwnerMatches(owner: ContextSessionOwner, headers: Headers): boolean {
++  if (owner.ambiguous) return false;
++  if (owner.kind === "stored") return owner.physicalIdentity === physicalIdentity(headers);
++  return owner.callerCredentialIdentity === callerCredentialIdentity(headers);
++}
++
++export function clearContextSessionOwnersForTests(): void {
++  owners.clear(); totalBytes = 0;
++}
+diff --git a/src/codex/inject.ts b/src/codex/inject.ts
+index 37e631305b..e9765e8a7f 100644
+--- a/src/codex/inject.ts
++++ b/src/codex/inject.ts
+@@ -1,3 +1,4 @@
++import { contextCompatibleBaseLine } from "./context-compat";
+ import { existsSync, readFileSync, unlinkSync } from "node:fs";
+ import {
+   atomicWriteFile,
+@@ -364,7 +365,7 @@ export function setRootOpenaiBaseUrl(
+   const lines = content.split("\n");
+   const firstTable = lines.findIndex((l) => /^\s*\[/.test(l));
+   const rootEnd = firstTable === -1 ? lines.length : firstTable;
+-  const key = buildOpenaiBaseUrlLine(portOrTarget, hostname);
++  const key = contextCompatibleBaseLine(content, buildOpenaiBaseUrlLine(portOrTarget, hostname));
+
+   for (let i = 0; i < rootEnd; i++) {
+     if (!isRootOpenaiBaseUrlLine(lines[i])) continue;
+@@ -399,7 +400,7 @@ function setRootOpenaiBaseUrlForTarget(
+   const lines = content.split("\n");
+   const firstTable = lines.findIndex((line) => /^\s*\[/.test(line));
+   const rootEnd = firstTable === -1 ? lines.length : firstTable;
+-  const key = buildOpenaiBaseUrlLineForTarget(target);
++  const key = contextCompatibleBaseLine(content, buildOpenaiBaseUrlLineForTarget(target));
+   for (let index = 0; index < rootEnd; index += 1) {
+     if (!isRootOpenaiBaseUrlLine(lines[index])) continue;
+     const markerOwned = index > 0 && lines[index - 1].includes(OCX_SECTION_MARKER);
+diff --git a/src/server/context-history.ts b/src/server/context-history.ts
+new file mode 100644
+index 0000000000..de06cbcf40
+--- /dev/null
++++ b/src/server/context-history.ts
+@@ -0,0 +1,142 @@
++/** Native history/notes JSON relay. No interpretation of encrypted tool arguments or retries. */
++import { formatErrorResponse } from "../bridge";
++import {
++  CodexAccountCooldownError, CodexAuthContextError, CodexMainProfileDrainingError, CodexDirectAuthenticationError,
++  CodexPoolAuthenticationError, CodexThreadAffinityExpiredError, CodexMainSubstitutionUnavailableError,
++  codexMainProfileDrainingResponse, cooldownErrorResponse,
++  materializeCodexUpstreamAuth, isCodexAuthContextUsable, resolveCodexAuthContext, releaseCodexAuthContextProbeLease,
++} from "../codex/auth-context";
++import { getContextSessionOwner, contextSessionOwnerMatches } from "../codex/context-owner";
++import { contextEndpoint } from "../codex/context-compat";
++import { formatCodexProviderForLog } from "../codex/routing";
++import { listOpenAiForwardSidecarCandidates } from "../providers/openai-sidecar";
++import { signalWithTimeout } from "../lib/abort";
++import { readBoundedResponseBytes } from "../lib/bounded-body";
++import type { AdmissionLease } from "../lib/admission";
++import type { OcxConfig } from "../types";
++import { ForwardAdmissionCredentialError, validateForwardAdmissionCredential, type DataPlaneAdmission } from "./auth-cors";
++import { readJsonRequestBody } from "./request-decompress";
++import { codexLogAccountId, decodeRequestErrorResponse } from "./responses";
++import { codexAccountSelectionForTurn } from "./lifecycle";
++import type { RequestLogContext } from "./request-log";
++
++const PROTOCOL_HEADERS = ["x-openai-encrypted-tool-arguments", "x-openai-tool-output-truncation-policy"];
++const RESPONSE_HEADERS = ["content-type", "retry-after", "x-request-id", "openai-processing-ms", ...PROTOCOL_HEADERS];
++const MAX_RESPONSE_BYTES = 16 * 1024 * 1024;
++
++export function contextSelectionHeaders(headers: Headers, sessionId: string): Headers {
++  const result = new Headers(headers);
++  // Codex history tools carry root session_id in JSON, unlike Responses' HTTP headers.
++  // Root model requests use (session-id=root, thread-id=root); don't fabricate a parent key.
++  if (!result.has("x-codex-parent-thread-id") && !result.has("session-id") && !result.has("thread-id")) {
++    result.set("session-id", sessionId);
++    result.set("thread-id", sessionId);
++  }
++  return result;
++}
++
++export async function handleContextHistory(
++  req: Request, config: OcxConfig, logCtx: RequestLogContext,
++  endpoint: string, turnAdmissionLease?: AdmissionLease, admission?: DataPlaneAdmission,
++): Promise<Response> {
++  if (!contextEndpoint("/v1/" + endpoint) || req.method !== "POST") {
++    return formatErrorResponse(404, "not_found", "Unknown context endpoint");
++  }
++  // Only a trusted listener admission authorizes replacing a proxy bearer with Codex auth.
++  const substituteMainCredential = admission?.source === "bearer";
++  try { if (!substituteMainCredential) validateForwardAdmissionCredential(req.headers, config); }
++  catch (err) {
++    if (err instanceof ForwardAdmissionCredentialError) return formatErrorResponse(401, "authentication_error", err.message);
++    throw err;
++  }
++  let body: unknown;
++  try { body = await readJsonRequestBody(req); }
++  catch (err) { return decodeRequestErrorResponse(err, "context_history"); }
++  const sessionId = (body as {context?: {session_id?: unknown}} | null)?.context?.session_id;
++  if (typeof sessionId !== "string" || !/^[A-Za-z0-9._:-]{1,512}$/.test(sessionId)) {
++    return formatErrorResponse(400, "invalid_request_error", "context.session_id must be a bounded nonempty string");
++  }
++  const candidate = listOpenAiForwardSidecarCandidates(config)[0];
++  if (!candidate) return formatErrorResponse(400, "invalid_request_error", "History and notes require the native ChatGPT forward provider");
++  const rootHeader = req.headers.get("x-codex-parent-thread-id")?.trim() || req.headers.get("session-id")?.trim();
++  if (rootHeader && rootHeader !== sessionId) {
++    return formatErrorResponse(409, "context_account_unavailable", "Context root does not match this request");
++  }
++  const owner = getContextSessionOwner(sessionId, candidate.provider.baseUrl);
++  if (!owner || owner.ambiguous || (owner.kind === "caller" && substituteMainCredential)) {
++    return formatErrorResponse(409, "context_account_unavailable",
++      "Context account ownership is unavailable; start a new session and preserve needed state before resetting context");
++  }
++  let authContext: Awaited<ReturnType<typeof resolveCodexAuthContext>>;
++  const headers = new Headers(candidate.provider.headers);
++  try {
++    authContext = await resolveCodexAuthContext(contextSelectionHeaders(req.headers, sessionId), config, owner.kind === "stored" ? "pool" : "direct", {
++      // Resolve the proven physical owner as an explicit account. Context operations
++      // never create affinity, rotate on quota, or inspect file-main for a caller owner.
++      modelId: "context_history",
++      ...(owner.kind === "stored" ? { accountId: owner.accountId } : { requestScopedMainCredential: true }),
++      admission,
++      substituteMainCredentialForDirect: substituteMainCredential,
++      beginCodexAccountSelection: codexAccountSelectionForTurn(turnAdmissionLease),
++    });
++    if (authContext.kind !== "main" && authContext.probeLeaseId) {
++      // History traffic must not occupy or settle the model's quota-recovery probe.
++      releaseCodexAuthContextProbeLease(authContext);
++      return formatErrorResponse(503, "upstream_error", "Model quota recovery is pending; retry context operation later");
++    }
++    if (!isCodexAuthContextUsable(authContext, config)) throw new CodexPoolAuthenticationError("Selected Codex account is unavailable");
++    logCtx.provider = formatCodexProviderForLog(candidate.providerName, codexLogAccountId(authContext), config);
++    // Materialization rechecks the current account policy after async selection.
++    // Synthetic lane IDs are local selection metadata, never upstream headers.
++    for (const [key, value] of materializeCodexUpstreamAuth(req.headers, authContext, {
++      config, modelId: "context_history", admission, substituteMainCredential,
++    })) {
++      headers.set(key, value);
++    }
++    // Recheck actual wire identity after async selection/materialization. A replaced
++    // account slot or login must not receive another physical account's history.
++    const currentOwner = getContextSessionOwner(sessionId, candidate.provider.baseUrl);
++    if (!currentOwner || currentOwner.kind !== owner.kind
++      || !contextSessionOwnerMatches(owner, headers) || !contextSessionOwnerMatches(currentOwner, headers)) {
++      return formatErrorResponse(409, "context_account_unavailable", "Context account identity changed; start a new session");
++    }
++    // Check the assembled outbound headers, including configured provider headers.
++    validateForwardAdmissionCredential(headers, config);
++  } catch (err) {
++    if (err instanceof CodexAccountCooldownError) return cooldownErrorResponse(err);
++    if (err instanceof CodexMainProfileDrainingError) return codexMainProfileDrainingResponse();
++    if (err instanceof CodexThreadAffinityExpiredError) return formatErrorResponse(409, "invalid_request_error", "Codex thread account affinity expired; start a new session");
++    if (err instanceof CodexAuthContextError || err instanceof CodexPoolAuthenticationError || err instanceof CodexDirectAuthenticationError
++      || err instanceof CodexMainSubstitutionUnavailableError || err instanceof ForwardAdmissionCredentialError) {
++      return formatErrorResponse(401, "authentication_error", "Selected Codex account is unavailable or needs reauthentication");
++    }
++    throw err;
++  }
++  headers.set("content-type", "application/json");
++  for (const key of PROTOCOL_HEADERS) {
++    const value = req.headers.get(key); if (value !== null) headers.set(key, value);
++  }
++  const deadline = signalWithTimeout(35_000, req.signal);
++  let response: Response | undefined;
++  try {
++    response = await fetch(`${candidate.provider.baseUrl}/${endpoint}`, {
++      method: "POST", headers, body: JSON.stringify(body), signal: deadline.signal, redirect: "manual",
++    });
++    const result = await readBoundedResponseBytes(response, {maxBytes: MAX_RESPONSE_BYTES, signal: deadline.signal});
++    if (result.oversized) return formatErrorResponse(502, "upstream_error", "Context response exceeded 16 MiB");
++    const outputHeaders = new Headers();
++    for (const key of RESPONSE_HEADERS) {
++      const value = response.headers.get(key); if (value !== null) outputHeaders.set(key, value);
++    }
++    // A context 403 is not evidence that the model credential is invalid. Don't mutate pool
++    // health/quota or retry writes; preserve the real upstream result for the caller.
++    return new Response([204,205,304].includes(response.status) ? null : result.bytes, {status:response.status, headers:outputHeaders});
++  } catch {
++    if (req.signal.aborted) return formatErrorResponse(499, "client_closed_request", "Context request canceled by client");
++    if (deadline.signal.aborted) return formatErrorResponse(504, "upstream_error", "Context upstream timed out");
++    return formatErrorResponse(502, "upstream_error", "Context upstream connection failed");
++  } finally {
++    deadline.cleanup();
++    if (response?.body && !response.body.locked) void response.body.cancel().catch(() => undefined);
++  }
++}
+diff --git a/src/server/index.ts b/src/server/index.ts
+index 82f36d7b6a..f074235f36 100644
+--- a/src/server/index.ts
++++ b/src/server/index.ts
+@@ -195,6 +195,8 @@ import {
+ import { handleImages } from "./images";
+ import { handleLive, logLiveSidebandFrame, parseLiveSidebandTarget, resolveLiveSidebandUpgrade } from "./live";
+ import { handleSearch } from "./search";
++import { handleContextHistory } from "./context-history";
++import { codexCompatibleUrl, contextEndpoint } from "../codex/context-compat";
+ import { fetchAllModels, handleManagementAPI, VERSION, type ManagementApiDeps } from "./management-api";
+ import {
+   createManagementSessionControl,
+@@ -820,6 +822,7 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
+     }
+     if (path === "/v1/responses/compact") return req.method === "POST";
+     if (path === "/v1/alpha/search") return req.method === "POST";
++    if (contextEndpoint(path)) return req.method === "POST";
+     if (path === "/v1/images/generations" || path === "/v1/images/edits") {
+       return req.method === "POST";
+     }
+@@ -1047,7 +1050,7 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
+       // The unauthenticated loopback listener (#1102) serves a fixed allowlist and nothing
+       // else. Rejecting here, before any handler runs, is what keeps the surface from growing
+       // silently when a route is added below.
+-      if (ingress === "unauthenticated-loopback" && !loopbackRouteAllowed(new URL(req.url), req)) {
++      if (ingress === "unauthenticated-loopback" && !loopbackRouteAllowed(codexCompatibleUrl(req.url), req)) {
+         return withCors(
+           formatErrorResponse(404, "not_found", `Unknown endpoint: ${req.method} ${new URL(req.url).pathname}`),
+           req,
+@@ -1056,7 +1059,7 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
+       }
+       // Tailscale Serve terminates only on this separately bound loopback socket. Reject before
+       // dispatch so no data, readiness, health, WebSocket, or unknown-static handler can run.
+-      if (ingress === "hub-management" && !managementIngressRouteAllowed(new URL(req.url), req)) {
++      if (ingress === "hub-management" && !managementIngressRouteAllowed(codexCompatibleUrl(req.url), req)) {
+         return withCors(
+           formatErrorResponse(404, "not_found", `Unknown endpoint: ${req.method} ${new URL(req.url).pathname}`),
+           req,
+@@ -1069,7 +1072,7 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
+       // same code path a plain loopback bind has always taken — Host-header check included.
+       // Routing, provider selection and response bodies keep using `config`.
+       const policy: RequestPolicyView = ingress === "unauthenticated-loopback" ? loopbackPolicy() : config;
+-      const url = new URL(req.url);
++      const url = codexCompatibleUrl(req.url);
+       markActivity(`${req.method} ${url.pathname}`);
+
+       // Readiness is exact-GET on the literal /readyz path. Compare the DECODED
+@@ -1825,6 +1828,31 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
+         }), req, policy);
+       }
+
++      if (contextEndpoint(url.pathname) !== undefined && req.method === "POST") {
++        disableResponsesRequestTimeout(req, requestServer);
++        if (isDraining()) {
++          return drainingResponse(req, policy);
++        }
++        const admission = resolveApiAuth(req, policy);
++        if (!admission) return withCors(formatErrorResponse(401, "authentication_error", "opencodex API key required"), req, policy);
++        if (!isAllowedRequestOrigin(req, policy)) {
++          return withCors(formatErrorResponse(403, "origin_rejected", "cross-origin data-plane request blocked"), req, policy);
++        }
++        const start = Date.now();
++        const requestId = nextRequestLogId(start);
++        const logCtx: RequestLogContext = {
++          model: "context_history",
++          provider: "unknown",
++          ...admissionFields(admission),
++        };
++        return runAdmittedHttpTurn(req, policy, async turnAdmissionLease => {
++          const response = await handleContextHistory(req, config, logCtx, contextEndpoint(url.pathname)!, turnAdmissionLease, admission);
++          addFinalRequestLog(requestId, start, logCtx, response.status,
++            response.status === 499 ? { closeReason: "client_cancel" } : undefined);
++          return withCors(response, req, policy);
++        });
++      }
++
+       if (url.pathname === "/v1/alpha/search" && req.method === "POST") {
+         disableResponsesRequestTimeout(req, requestServer);
+         if (isDraining()) {
+diff --git a/src/server/live.ts b/src/server/live.ts
+index 91caec1f66..a139c6c177 100644
+--- a/src/server/live.ts
++++ b/src/server/live.ts
+@@ -1,3 +1,4 @@
++import { codexCompatibleUrl } from "../codex/context-compat";
+ /**
+  * /v1/live and /v1/realtime/calls relay (issue #371).
+  *
+@@ -646,7 +647,7 @@ export async function handleLive(
+     // Frameless API-shape call-create posts to `{base}/live` without the AVAS
+     // query (openai/codex RealtimeCallClient, realtime_call.rs); only the
+     // realtime/calls inbound shape keeps the legacy keyed AVAS endpoint.
+-    url = new URL(req.url).pathname === "/v1/live"
++    url = codexCompatibleUrl(req.url).pathname === "/v1/live"
+       ? forwardLiveUrl(relay.providerBaseUrl, /* usesBackendShape */ false)
+       : keyedLiveUrl(relay.providerBaseUrl);
+   }
+diff --git a/src/server/responses/core.ts b/src/server/responses/core.ts
+index 684931c9f9..b451103c1d 100644
+--- a/src/server/responses/core.ts
++++ b/src/server/responses/core.ts
+@@ -1,4 +1,5 @@
+ import type { Server } from "bun";
++import { recordContextSessionOwner } from "../../codex/context-owner";
+ import { randomUUID } from "node:crypto";
+ import { bridgeToResponsesSSE, buildResponseJSON, formatErrorResponse, type ResponsesTerminalStatus } from "../../bridge";
+ import { formatPassthroughUpstreamError } from "./passthrough-error";
+@@ -3880,8 +3881,14 @@ async function handleResponsesInner(
+   // message, and leave Codex fataling on a missing compaction item (#422).
+   const routedCompaction = parsed._compactionRequest === true
+     && !isCanonicalOpenAiForwardProvider(route.provider);
+-  const commitReasoningReplayServingRoute = (): void => {
++  const commitReasoningReplayServingRoute = (outboundHeaders?: HeadersInit): void => {
+     commitReasoningReplayServingIdentity(parsed._reasoningReplayScope);
++    // History has no model namespace. Record the account that actually accepted this
++    // final attempt, after refresh/failover, rather than guessing from mutable affinity.
++    if (outboundHeaders && isCanonicalOpenAiForwardProvider(route.provider)) {
++      recordContextSessionOwner(req.headers, route.provider.baseUrl, authCtx,
++        new Headers(outboundHeaders), substituteMainCredential);
++    }
+   };
+   if (routedCompaction) {
+     delete parsed.context.tools;
+@@ -4951,7 +4958,7 @@ async function handleResponsesInner(
+       // For streamed passthrough, a successful terminal response means non-error upstream status
+       // before relay starts. Waiting for SSE completion would retain request state across the whole
+       // stream; a later body failure does not undo that this destination accepted and served the turn.
+-      commitReasoningReplayServingRoute();
++      commitReasoningReplayServingRoute(request.headers);
+       const terminalRepairPolicy = providerModelResponsesTerminalRepair(
+         route.providerName,
+         route.provider,
+@@ -5271,7 +5278,7 @@ async function handleResponsesInner(
+           return formatErrorResponse(502, "upstream_error", undeclaredToolCallMessage(undeclared));
+         }
+       }
+-      commitReasoningReplayServingRoute();
++      commitReasoningReplayServingRoute(request.headers);
+       if (rememberPassthroughResponseChecked) {
+         try {
+           rememberPassthroughResponseChecked(
+@@ -5355,7 +5362,7 @@ async function handleResponsesInner(
+     }
+     // An unclassified passthrough body is relayed directly and has no bounded completion observer;
+     // use the same non-error-status success boundary as SSE instead of retaining per-stream state.
+-    commitReasoningReplayServingRoute();
++    commitReasoningReplayServingRoute(request.headers);
+     const body = relayWithAbort(upstreamResponse.body, upstream);
+     const turnAc = new AbortController();
+     const tracked = body ? trackStreamLifetime(body, turnAc, undefined, options.turnAdmissionLease) : null;
+@@ -5671,7 +5678,7 @@ async function handleResponsesInner(
+       streamRoutedModelOutput: wsPlan.streamRoutedModelOutput,
+       on429: rotateSidecarProviderOn429,
+       retryOn429Policy: rateLimitRetryPolicyFor(route.provider),
+-      onCompletedResponse: commitReasoningReplayServingRoute,
++      onCompletedResponse: () => commitReasoningReplayServingRoute(),
+     });
+     // Register the sidecar stream as an active turn so drainAndShutdown waits for (or aborts)
+     // in-flight web-search turns instead of skipping them during graceful shutdown.
+diff --git a/tests/codex-integration/codex-auth-context.test.ts b/tests/codex-integration/codex-auth-context.test.ts
+index bb4f24a098..34ca20c112 100644
+--- a/tests/codex-integration/codex-auth-context.test.ts
++++ b/tests/codex-integration/codex-auth-context.test.ts
+@@ -72,6 +72,8 @@ import {
+   tryAdmitTurn,
+ } from "../../src/server/lifecycle";
+ import type { CodexModelEntitlementSnapshot } from "../../src/codex/model-entitlements";
++import { recordContextSessionOwner, clearContextSessionOwnersForTests } from "../../src/codex/context-owner";
++import { handleContextHistory } from "../../src/server/context-history";
+ import { hasForwardableCodexBearer } from "../../src/server/auth-cors";
+ import { removeTreeWithRetry } from "../helpers/remove-tree";
+
+@@ -2228,3 +2230,50 @@ describe("native-main fence names its gate reason", () => {
+     }
+   });
+ });
++
++
++test("context Direct bearer admission uses real stored-main materialization and fails closed without it", async () => {
++  const cfg = config();
++  cfg.providers.openai = {
++    adapter: "openai-responses", baseUrl: "https://chatgpt.com/backend-api/codex",
++    authMode: "forward", codexAccountMode: "direct",
++  };
++  const token = liveJwt();
++  const admission = { kind: "environment", source: "bearer" } as const;
++  clearContextSessionOwnersForTests();
++  recordContextSessionOwner(new Headers({ "session-id": "synthetic-root" }), cfg.providers.openai.baseUrl,
++    { kind: "main", accountId: null }, new Headers({ authorization: `Bearer ${token}`, "chatgpt-account-id": "stored_main_acc" }), true);
++  const request = () => new Request("http://localhost/v1/alpha/notes/v2/read_file", {
++    method: "POST", headers: { authorization: "Bearer ocx_data_test_admission", "openai-beta": "responses=experimental", cookie: "synthetic=private" },
++    body: JSON.stringify({ context: { session_id: "synthetic-root" } }),
++  });
++  const originalFetch = globalThis.fetch;
++  let calls = 0;
++  globalThis.fetch = Object.assign(async (input: string | URL | Request, init?: RequestInit) => {
++    calls++;
++    expect(String(input)).toBe("https://chatgpt.com/backend-api/codex/alpha/notes/v2/read_file");
++    const headers = new Headers(init?.headers);
++    expect(headers.get("authorization")).toBe(`Bearer ${token}`);
++    expect(headers.get("chatgpt-account-id")).toBe("stored_main_acc");
++    expect(headers.get("openai-beta")).toBe("responses=experimental");
++    expect(headers.has("cookie")).toBe(false);
++    return new Response("{}");
++  }, { preconnect: originalFetch.preconnect });
++  try {
++    for (const available of [true, false]) {
++      writeFileSync(join(testDir, "auth.json"), JSON.stringify({ tokens: available ? { access_token: token, account_id: "stored_main_acc" } : {} }));
++      const turn = tryAdmitTurn();
++      expect(turn).not.toBeNull();
++      try {
++        const response = await handleContextHistory(request(), cfg, { model: "context_history", provider: "" }, "alpha/notes/v2/read_file", turn!, admission);
++        expect(response.status).toBe(available ? 200 : 401);
++      } finally {
++        turn?.release();
++      }
++    }
++    expect(calls).toBe(1);
++  } finally {
++    clearContextSessionOwnersForTests();
++    globalThis.fetch = originalFetch;
++  }
++});
+diff --git a/tests/codex-integration/codex-context-owner.test.ts b/tests/codex-integration/codex-context-owner.test.ts
+new file mode 100644
+index 0000000000..5d34fc0406
+--- /dev/null
++++ b/tests/codex-integration/codex-context-owner.test.ts
+@@ -0,0 +1,151 @@
++import { beforeEach, describe, expect, test } from "bun:test";
++import type { CodexAuthContext } from "../../src/codex/auth-context";
++import { clearContextSessionOwnersForTests, contextSessionOwnerMatches,
++  getContextSessionOwner, recordContextSessionOwner } from "../../src/codex/context-owner";
++
++const destination = "https://chatgpt.com/backend-api/codex";
++const start = 1_000_000;
++const root = (id = "root") => new Headers({ "session-id": id, "thread-id": id });
++const outbound = (account: string | null = "physical-a", token = "accepted-a") => new Headers({
++  authorization: `Bearer ${token}`, ...(account === null ? {} : { "chatgpt-account-id": account }),
++});
++const stored = (id = "slot-a", account = "physical-a"): CodexAuthContext => ({
++  kind: "pool", accountId: id, chatgptAccountId: account,
++  accessToken: "accepted-a", generation: 1, writerGeneration: 0, fixedAccount: true,
++});
++const caller: CodexAuthContext = { kind: "main", accountId: null };
++beforeEach(clearContextSessionOwnersForTests);
++
++describe("context session ownership", () => {
++  test("an explicit stored account owns the session independently of routing state", () => {
++    recordContextSessionOwner(root(), destination, stored(), outbound(), false, start);
++    const owner = getContextSessionOwner("root", destination, start)!;
++    expect(owner).toMatchObject({ kind: "stored", accountId: "slot-a", ambiguous: false });
++    expect(contextSessionOwnerMatches(owner, outbound())).toBe(true);
++    expect(contextSessionOwnerMatches(owner, outbound("physical-b"))).toBe(false);
++    expect(JSON.stringify(owner)).not.toContain("physical-a");
++    expect(JSON.stringify(owner)).not.toContain("accepted-a");
++  });
++
++  test("stored ownership survives token and generation refresh within the same physical account", () => {
++    recordContextSessionOwner(root(), destination, stored(), outbound(), false, start);
++    const refreshed = { ...stored(), generation: 2, accessToken: "refreshed" } as CodexAuthContext;
++    recordContextSessionOwner(root(), destination, refreshed, outbound("physical-a", "refreshed"), false, start + 1);
++    const owner = getContextSessionOwner("root", destination, start + 2)!;
++    expect(owner.ambiguous).toBe(false);
++    expect(contextSessionOwnerMatches(owner, outbound("physical-a", "refreshed"))).toBe(true);
++  });
++
++  test("stored identity must match the accepted outbound account", () => {
++    recordContextSessionOwner(root(), destination, stored(), outbound("physical-b"), false, start);
++    expect(getContextSessionOwner("root", destination, start)).toBeUndefined();
++    recordContextSessionOwner(root(), destination, stored(), outbound(null), false, start);
++    expect(getContextSessionOwner("root", destination, start)).toBeUndefined();
++  });
++
++  test("caller-owned credentials remain fenced from proxy or other bearer credentials", () => {
++    recordContextSessionOwner(root(), destination, caller, outbound(), false, start);
++    const owner = getContextSessionOwner("root", destination, start)!;
++    expect(owner.kind).toBe("caller");
++    expect(contextSessionOwnerMatches(owner, outbound())).toBe(true);
++    expect(contextSessionOwnerMatches(owner, outbound("physical-a", "proxy-secret"))).toBe(false);
++    expect(contextSessionOwnerMatches(owner, outbound("physical-b"))).toBe(false);
++  });
++
++  test("only an accepted same-account model turn authorizes a rotated caller token", () => {
++    recordContextSessionOwner(root(), destination, caller, outbound(), false, start);
++    const refreshed = outbound("physical-a", "refreshed");
++    expect(contextSessionOwnerMatches(getContextSessionOwner("root", destination, start)!, refreshed)).toBe(false);
++    recordContextSessionOwner(root(), destination, caller, refreshed, false, start + 1);
++    const owner = getContextSessionOwner("root", destination, start + 1)!;
++    expect(owner.ambiguous).toBe(false);
++    expect(contextSessionOwnerMatches(owner, refreshed)).toBe(true);
++    expect(contextSessionOwnerMatches(owner, outbound())).toBe(false);
++  });
++
++  test("caller without physical identity allows only the exact credential", () => {
++    recordContextSessionOwner(root(), destination, caller, outbound(null), false, start);
++    let owner = getContextSessionOwner("root", destination, start)!;
++    expect(contextSessionOwnerMatches(owner, outbound(null))).toBe(true);
++    recordContextSessionOwner(root(), destination, caller, outbound(null, "rotated"), false, start + 1);
++    owner = getContextSessionOwner("root", destination, start + 1)!;
++    expect(owner.ambiguous).toBe(true);
++    expect(contextSessionOwnerMatches(owner, outbound(null, "rotated"))).toBe(false);
++  });
++
++  test("substituted Direct main is stored ownership, not caller ownership", () => {
++    recordContextSessionOwner(root(), destination, caller, outbound(), true, start);
++    expect(getContextSessionOwner("root", destination, start)).toMatchObject({ kind: "stored", accountId: "__main__" });
++  });
++
++  test("root and child model turns share the root body session lookup", () => {
++    recordContextSessionOwner(root(), destination, stored(), outbound(), false, start);
++    recordContextSessionOwner(new Headers({ "x-codex-parent-thread-id": "root", "session-id": "child" }),
++      destination, stored(), outbound(), false, start + 1);
++    expect(getContextSessionOwner("root", destination, start + 1)?.ambiguous).toBe(false);
++    expect(getContextSessionOwner("child", destination, start + 1)).toBeUndefined();
++  });
++
++  test.each(["physical", "kind", "destination"])("conflicting %s remains ambiguous after later writes", conflict => {
++    recordContextSessionOwner(root(), destination, stored(), outbound(), false, start);
++    recordContextSessionOwner(root(), conflict === "destination" ? "https://other.test/codex" : destination,
++      conflict === "kind" ? caller : stored("slot-b", conflict === "physical" ? "physical-b" : "physical-a"),
++      outbound(conflict === "physical" ? "physical-b" : "physical-a"), false, start + 1);
++    recordContextSessionOwner(root(), destination, stored(), outbound(), false, start + 2);
++    const owner = getContextSessionOwner("root", destination, start + 2)!;
++    expect(owner.ambiguous).toBe(true);
++    expect(contextSessionOwnerMatches(owner, outbound())).toBe(false);
++    expect(getContextSessionOwner("root", "https://other.test/codex", start + 2)).toBeUndefined();
++  });
++
++  test("destination mismatch cannot bootstrap a new owner", () => {
++    recordContextSessionOwner(root(), destination, stored(), outbound(), false, start);
++    expect(getContextSessionOwner("root", "https://other.test/codex", start)).toBeUndefined();
++    expect(getContextSessionOwner("root", destination + "/", start)).toBeDefined();
++  });
++
++  test("a fresh lookup detects conflict after an earlier snapshot was read", () => {
++    recordContextSessionOwner(root(), destination, stored(), outbound(), false, start);
++    const oldOwner = getContextSessionOwner("root", destination, start)!;
++    recordContextSessionOwner(root(), destination, stored("slot-b", "physical-b"), outbound("physical-b"), false, start + 1);
++    const currentOwner = getContextSessionOwner("root", destination, start + 1)!;
++    expect(oldOwner.ambiguous).toBe(false);
++    expect(currentOwner.ambiguous).toBe(true);
++    expect(contextSessionOwnerMatches(currentOwner, outbound())).toBe(false);
++  });
++
++  test("expiry and restart lose ownership instead of guessing an active account", () => {
++    recordContextSessionOwner(root(), destination, stored(), outbound(), false, start);
++    expect(getContextSessionOwner("root", destination, start + 24 * 60 * 60_000)).toBeUndefined();
++    recordContextSessionOwner(root(), destination, stored(), outbound(), false, start);
++    clearContextSessionOwnersForTests();
++    expect(getContextSessionOwner("root", destination, start)).toBeUndefined();
++  });
++
++  test("LRU capacity evicts the untouched entry, preserving a recently looked-up owner", () => {
++    for (let i = 0; i < 2048; i++) recordContextSessionOwner(root(`root-${i}`), destination, stored(), outbound(), false, start);
++    expect(getContextSessionOwner("root-0", destination, start + 1)).toBeDefined();
++    recordContextSessionOwner(root("overflow"), destination, stored(), outbound(), false, start + 2);
++    expect(getContextSessionOwner("root-0", destination, start + 2)).toBeDefined();
++    expect(getContextSessionOwner("root-1", destination, start + 2)).toBeUndefined();
++  });
++
++  test("byte capacity also bounds long account slots", () => {
++    for (let i = 0; i < 1600; i++) recordContextSessionOwner(root(`root-${i}`), destination,
++      stored("a".repeat(512)), outbound(), false, start);
++    expect(getContextSessionOwner("root-0", destination, start)).toBeUndefined();
++    expect(getContextSessionOwner("root-1599", destination, start)).toBeDefined();
++  });
++
++  test("invalid and oversized identifiers never create ownership", () => {
++    for (const id of ["", "bad root", "a".repeat(513)]) {
++      recordContextSessionOwner(root(id), destination, stored(), outbound(), false, start);
++      expect(getContextSessionOwner(id, destination, start)).toBeUndefined();
++    }
++    recordContextSessionOwner(new Headers({ "x-codex-parent-thread-id": "bad root", "session-id": "root" }),
++      destination, stored(), outbound(), false, start);
++    expect(getContextSessionOwner("root", destination, start)).toBeUndefined();
++    recordContextSessionOwner(root(), "https://x.test/" + "a".repeat(4096), stored(), outbound(), false, start);
++    expect(getContextSessionOwner("root", destination, start)).toBeUndefined();
++  });
++});
+diff --git a/tests/codex-integration/codex-inject.test.ts b/tests/codex-integration/codex-inject.test.ts
+index 84ac5f67b6..54bf6cd34c 100644
+--- a/tests/codex-integration/codex-inject.test.ts
++++ b/tests/codex-integration/codex-inject.test.ts
+@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
+ import {
+   applyEol,
+   buildOpenaiBaseUrlLine,
++  buildRealtimeWsBaseUrlLine,
+   buildProfileFile,
+   buildProviderTableBlock,
+   chooseCatalogPathForInjection,
+@@ -13,7 +14,7 @@ import {
+   stripRootContextWindowOverrides,
+   standaloneCodexRoutingTarget,
+ } from "../../src/codex/inject";
+-import { stripJournaledOpenaiBaseUrl } from "../../src/codex/injected-marker";
++import { OCX_SECTION_MARKER, stripJournaledOpenaiBaseUrl } from "../../src/codex/injected-marker";
+ import {
+   MANAGED_AGENTS_TABLE_MARKER,
+   MANAGED_SUBAGENT_DEFAULT_MARKER,
+@@ -687,3 +688,33 @@ describe("EOL boundary helpers (Windows CRLF configs)", () => {
+     expect(applyEol(crlf, "\r\n")).toBe(crlf);
+   });
+ });
++
++test('managed injection is idempotent and retains every unrelated value',()=>{
++ const source=`model = "gpt-6-astra"\n${OCX_SECTION_MARKER}\nopenai_base_url = "http://127.0.0.1:10100/v1"\nservice_tier = "fast"\n[features]\ncontext_management.experimental_mode = true\n[features.multi_agent_v2]\nenabled = true\n`;
++ const target={baseUrl:'http://127.0.0.1:10100/v1',requiresAdmissionToken:false,tokenEnv:'OPENCODEX_API_AUTH_TOKEN' as const};
++ const result=setRootOpenaiBaseUrl(source,target);
++ expect(result.keptUserBaseUrl).toBe(false);
++ expect(result.content).toBe(source.replace('10100/v1','10100/backend-api/codex'));
++ expect(setRootOpenaiBaseUrl(result.content,target).content).toBe(result.content);
++ expect(buildRealtimeWsBaseUrlLine(target)).toContain('10100/v1');
++ expect(setRootOpenaiBaseUrl(source,10100).content).toBe(result.content);
++});
++test('feature disabled and user-owned routing remain intact',()=>{
++ const source='openai_base_url = "http://127.0.0.1:10100/v1"\n[features]\ncontext_management.experimental_mode = true\n';
++ expect(setRootOpenaiBaseUrl(source,10100)).toEqual({content:source,keptUserBaseUrl:true});
++ const managed=`${OCX_SECTION_MARKER}\nopenai_base_url = "http://127.0.0.1:10100/v1"\n[features]\ncontext_management.experimental_mode = false\n`;
++ expect(setRootOpenaiBaseUrl(managed,10100).content).toBe(managed);
++});
++
++
++test("malformed TOML preserves user routing and does not enable context injection", () => {
++  const target = { baseUrl: "http://127.0.0.1:10100/v1", requiresAdmissionToken: false, tokenEnv: "OPENCODEX_API_AUTH_TOKEN" as const };
++  for (const malformed of ['model = "unterminated', '[features]\ncontext_management.experimental_mode = true\nbroken = [']) {
++    const userOwned = `openai_base_url = "https://example.invalid/v1"\n${malformed}\n`;
++    const managed = `${OCX_SECTION_MARKER}\nopenai_base_url = "http://127.0.0.1:10100/v1"\n${malformed}\n`;
++    for (const inject of [(source: string) => setRootOpenaiBaseUrl(source, 10100), (source: string) => setRootOpenaiBaseUrl(source, target)]) {
++      expect(inject(userOwned)).toEqual({ content: userOwned, keptUserBaseUrl: true });
++      expect(inject(managed)).toEqual({ content: managed, keptUserBaseUrl: false });
++    }
++  }
++});
+diff --git a/tests/codex-integration/context-compat.test.ts b/tests/codex-integration/context-compat.test.ts
+new file mode 100644
+index 0000000000..a0e19f4c60
+--- /dev/null
++++ b/tests/codex-integration/context-compat.test.ts
+@@ -0,0 +1,22 @@
++import { describe, test, expect } from "bun:test";
++import { codexCompatibleUrl, contextEndpoint, contextCompatibleBaseLine } from "../../src/codex/context-compat";
++
++describe("route and config isolation", () => {
++  test("aliases data-plane routes and preserves query; never aliases management", () => {
++    for (const route of ["responses", "responses/compact", "models", "alpha/search", "live", "realtime/calls"]) {
++      expect(codexCompatibleUrl(`http://127.0.0.1:10100/backend-api/codex/${route}?a=1`).pathname).toBe(`/v1/${route}`);
++    }
++    expect(codexCompatibleUrl("http://127.0.0.1:10100/v1/responses?a=1").href).toBe("http://127.0.0.1:10100/v1/responses?a=1");
++    expect(codexCompatibleUrl("http://127.0.0.1:10100/backend-api/codex/api/config").pathname).toBe("/v1/api/config");
++    expect(contextEndpoint("/v1/alpha/notes/v2/write_file")).toBe("alpha/notes/v2/write_file");
++    expect(contextEndpoint("/v1/alpha/notes/v2/delete_file")).toBeUndefined();
++    expect(contextEndpoint("/v1/alpha/notes/v2/../write_file")).toBeUndefined();
++  });
++  test("opt-in changes only the built-in loopback base URL", () => {
++    const line='openai_base_url = "http://127.0.0.1:10100/v1"';
++    expect(contextCompatibleBaseLine('[features]\ncontext_management.experimental_mode = true\n',line)).toBe('openai_base_url = "http://127.0.0.1:10100/backend-api/codex"');
++    for(const content of ['','[features]\ncontext_management.experimental_mode = false\n']) expect(contextCompatibleBaseLine(content,line)).toBe(line);
++    const remote='openai_base_url = "https://example.com/v1"';
++    expect(contextCompatibleBaseLine('[features.context_management]\nexperimental_mode=true\n',remote)).toBe(remote);
++  });
++});
+diff --git a/tests/fixtures/test-layout-expected.json b/tests/fixtures/test-layout-expected.json
+index 5276f08f46..288049cd0d 100644
+--- a/tests/fixtures/test-layout-expected.json
++++ b/tests/fixtures/test-layout-expected.json
+@@ -215,6 +215,7 @@
+   "codex-cli-update-zero-effect.test.ts": "codex-integration",
+   "codex-composed-acceptance.test.ts": "codex-integration",
+   "codex-config-generation.test.ts": "codex-integration",
++  "codex-context-owner.test.ts": "codex-integration",
+   "codex-convergence-account-selectors.test.ts": "codex-integration",
+   "codex-convergence-contract.test.ts": "codex-integration",
+   "codex-cooldown-recovery.test.ts": "codex-integration",
+@@ -330,6 +331,9 @@
+   "consume-for-inspection-cancel.test.ts": "server",
+   "container-bootstrap.test.ts": "service",
+   "context-cap-unknown-window.test.ts": "providers",
++  "context-compat.test.ts": "codex-integration",
++  "context-history-ownership.test.ts": "server",
++  "context-history.test.ts": "server",
+   "continuation-dedup.test.ts": "responses",
+   "core-lab-boundary.test.ts": "lab",
+   "cost-cap-unknown-evidence.test.ts": "usage",
+diff --git a/tests/server/context-history-ownership.test.ts b/tests/server/context-history-ownership.test.ts
+new file mode 100644
+index 0000000000..83a9a79d42
+--- /dev/null
++++ b/tests/server/context-history-ownership.test.ts
+@@ -0,0 +1,150 @@
++import { afterEach, beforeEach, expect, test } from "bun:test";
++import { mkdtempSync, writeFileSync } from "node:fs";
++import { join } from "node:path";
++import { tmpdir } from "node:os";
++import { handleResponses } from "../../src/server/responses";
++import { handleContextHistory } from "../../src/server/context-history";
++import { tryAdmitTurn } from "../../src/server/lifecycle";
++import type { DataPlaneAdmission } from "../../src/server/auth-cors";
++import { saveCodexAccountCredential } from "../../src/codex/account-store";
++import { clearAccountNeedsReauth } from "../../src/codex/account-runtime-state";
++import { clearAccountQuota, setAccountQuotaFromParsed } from "../../src/codex/quota";
++import { clearCodexUpstreamHealth, clearThreadAccountMap, resetCodexRoutingForManualSelection } from "../../src/codex/routing";
++import { clearContextSessionOwnersForTests, getContextSessionOwner } from "../../src/codex/context-owner";
++import type { OcxConfig } from "../../src/types";
++import { removeTreeWithRetry } from "../helpers/remove-tree";
++
++const destination = "https://chatgpt.com/backend-api/codex";
++const originalFetch = globalThis.fetch;
++let previousHome: string | undefined;
++let previousCodexHome: string | undefined;
++let home = "";
++let sent: Array<{ url: string; headers: Headers }> = [];
++let failFirstAccount: string | undefined;
++
++function install(id: string, owner: string, token = `${id}-token`): void {
++  saveCodexAccountCredential(id, { accessToken: token, refreshToken: `${id}-refresh`,
++    chatgptAccountId: owner, expiresAt: Date.now() + 3600_000 });
++  setAccountQuotaFromParsed(id, { weeklyPercent: 20 });
++}
++
++function config(): OcxConfig {
++  return { port: 0, defaultProvider: "openai", activeCodexAccountId: "pool-b",
++    autoSwitchThreshold: 95, accountPoolStrategy: "fill-first", emptyCompletionRetry: false,
++    codexAccountNamespaces: { side: "pool-a" },
++    codexAccounts: [{ id: "pool-a", isMain: false }, { id: "pool-b", isMain: false }],
++    providers: { openai: { adapter: "openai-responses", baseUrl: destination,
++      authMode: "forward", codexAccountMode: "pool" } } };
++}
++
++function requestHeaders(session: string, bearer = "caller-native-token", account = "caller-account"): Headers {
++  return new Headers({ "content-type": "application/json", authorization: `Bearer ${bearer}`,
++    "chatgpt-account-id": account, "session-id": session, "thread-id": session });
++}
++
++async function model(cfg: OcxConfig, session: string, name = "side/gpt-5.5", headers = requestHeaders(session), admission?: DataPlaneAdmission): Promise<Response> {
++  const lease = tryAdmitTurn(); expect(lease).not.toBeNull();
++  try {
++    const response = await handleResponses(new Request("http://localhost/v1/responses", { method: "POST", headers,
++      body: JSON.stringify({ model: name, input: "hello", stream: false }) }), cfg,
++      { model: "", provider: "" }, { turnAdmissionLease: lease!, admission });
++    const text = await response.text();
++    return new Response(text, { status: response.status, headers: response.headers });
++  } finally { lease?.release(); }
++}
++
++async function notes(cfg: OcxConfig, session: string, headers = requestHeaders(session), admission?: DataPlaneAdmission): Promise<Response> {
++  const lease = tryAdmitTurn(); expect(lease).not.toBeNull();
++  try {
++    return await handleContextHistory(new Request("http://localhost/v1/alpha/notes/v2/read_file", {
++      method: "POST", headers, body: JSON.stringify({ context: { session_id: session } }),
++    }), cfg, { model: "context_history", provider: "" }, "alpha/notes/v2/read_file", lease!, admission);
++  } finally { lease?.release(); }
++}
++
++beforeEach(() => {
++  previousHome = process.env.OPENCODEX_HOME; previousCodexHome = process.env.CODEX_HOME;
++  home = mkdtempSync(join(tmpdir(), "ocx-context-owner-"));
++  process.env.OPENCODEX_HOME = home; process.env.CODEX_HOME = home;
++  clearContextSessionOwnersForTests(); clearAccountQuota(); clearThreadAccountMap(); clearCodexUpstreamHealth();
++  for (const id of ["pool-a", "pool-b", "__main__"]) clearAccountNeedsReauth(id);
++  install("pool-a", "physical-a"); install("pool-b", "physical-b");
++  sent = []; failFirstAccount = undefined;
++  globalThis.fetch = Object.assign(async (input: string | URL | Request, init?: RequestInit) => {
++    const url = String(input); const headers = new Headers(init?.headers); sent.push({ url, headers });
++    if (url === `${destination}/responses`) {
++      if (headers.get("chatgpt-account-id") === failFirstAccount) {
++        failFirstAccount = undefined;
++        return Response.json({ error: { message: "usage limit reached", type: "usage_limit_reached" } }, { status: 429 });
++      }
++      return Response.json({ id: "response-owned", object: "response", status: "completed",
++        output: [{ id: "message-owned", type: "message", role: "assistant", status: "completed",
++          content: [{ type: "output_text", text: "ready", annotations: [] }] }],
++        usage: { input_tokens: 1, output_tokens: 1, total_tokens: 2 } });
++    }
++    if (url === `${destination}/alpha/notes/v2/read_file`) return Response.json({ value: "same account" });
++    throw new Error(`Unexpected test request: ${url}`);
++  }, { preconnect: originalFetch.preconnect });
++});
++
++afterEach(() => {
++  globalThis.fetch = originalFetch;
++  clearContextSessionOwnersForTests(); clearAccountQuota(); clearThreadAccountMap(); clearCodexUpstreamHealth();
++  removeTreeWithRetry(home);
++  if (previousHome === undefined) delete process.env.OPENCODEX_HOME; else process.env.OPENCODEX_HOME = previousHome;
++  if (previousCodexHome === undefined) delete process.env.CODEX_HOME; else process.env.CODEX_HOME = previousCodexHome;
++});
++
++test("successful explicit account A owns context while active B remains selected", async () => {
++  const cfg = config(); resetCodexRoutingForManualSelection("pool-b");
++  const response = await model(cfg, "root-explicit");
++  expect(response.status).toBe(200);
++  expect(getContextSessionOwner("root-explicit", destination)).toMatchObject({ kind: "stored", accountId: "pool-a", ambiguous: false });
++  expect((await notes(cfg, "root-explicit")).status).toBe(200);
++  expect(sent.map(row => row.headers.get("chatgpt-account-id"))).toEqual(["physical-a", "physical-a"]);
++  expect(cfg.activeCodexAccountId).toBe("pool-b");
++  install("pool-a", "physical-a", "renewed-a-token");
++  expect((await notes(cfg, "root-explicit")).status).toBe(200);
++  expect(sent.at(-1)!.headers.get("authorization")).toBe("Bearer renewed-a-token");
++  install("pool-a", "replacement-a");
++  expect((await notes(cfg, "root-explicit")).status).toBe(409);
++  expect(sent).toHaveLength(3);
++  clearContextSessionOwnersForTests();
++  expect((await notes(cfg, "root-explicit")).status).toBe(409);
++  expect(sent).toHaveLength(3);
++});
++
++test("failed account A then successful B records only the serving account", async () => {
++  const cfg = config(); cfg.activeCodexAccountId = "pool-a";
++  resetCodexRoutingForManualSelection("pool-a"); failFirstAccount = "physical-a";
++  const response = await model(cfg, "root-retry", "gpt-5.5");
++  expect(response.status).toBe(200);
++  expect(sent.map(row => row.headers.get("chatgpt-account-id"))).toEqual(["physical-a", "physical-b"]);
++  expect(getContextSessionOwner("root-retry", destination)).toMatchObject({ kind: "stored", accountId: "pool-b", ambiguous: false });
++  expect((await notes(cfg, "root-retry")).status).toBe(200);
++  expect(sent.at(-1)!.headers.get("chatgpt-account-id")).toBe("physical-b");
++});
++
++test("Direct caller context never borrows stored login or proxy admission", async () => {
++  const cfg = config(); cfg.providers.openai.codexAccountMode = "direct";
++  expect((await model(cfg, "root-caller", "gpt-5.5")).status).toBe(200);
++  expect(getContextSessionOwner("root-caller", destination)?.kind).toBe("caller");
++  expect((await notes(cfg, "root-caller")).status).toBe(200);
++  expect(sent.map(row => row.headers.get("authorization"))).toEqual(["Bearer caller-native-token", "Bearer caller-native-token"]);
++  const admission = { kind: "environment", source: "bearer" } as const;
++  expect((await notes(cfg, "root-caller", requestHeaders("root-caller", "ocx_data_test_key"), admission)).status).toBe(409);
++  expect(sent).toHaveLength(2);
++});
++
++test("Direct proxy-bearer model and notes use stored main without leaking the proxy secret", async () => {
++  const cfg = config(); cfg.providers.openai.codexAccountMode = "direct";
++  const token = `header.${Buffer.from(JSON.stringify({ exp: Math.floor(Date.now() / 1000) + 3600 })).toString("base64url")}.signature`;
++  writeFileSync(join(home, "auth.json"), JSON.stringify({ tokens: { access_token: token, account_id: "physical-main" } }));
++  const admission = { kind: "environment", source: "bearer" } as const;
++  const headers = requestHeaders("root-proxy", "ocx_data_test_key", "untrusted-account");
++  expect((await model(cfg, "root-proxy", "gpt-5.5", headers, admission)).status).toBe(200);
++  expect(getContextSessionOwner("root-proxy", destination)).toMatchObject({ kind: "stored", accountId: "__main__" });
++  expect((await notes(cfg, "root-proxy", headers, admission)).status).toBe(200);
++  expect(sent.map(row => row.headers.get("authorization"))).toEqual([`Bearer ${token}`, `Bearer ${token}`]);
++  expect(sent.every(row => row.headers.get("chatgpt-account-id") === "physical-main")).toBe(true);
++});
+diff --git a/tests/server/context-history.test.ts b/tests/server/context-history.test.ts
+new file mode 100644
+index 0000000000..26c3d03b9b
+--- /dev/null
++++ b/tests/server/context-history.test.ts
+@@ -0,0 +1,281 @@
++// mock.module replacements require file isolation (bun test --isolate).
++import { describe, test, expect, mock, beforeEach, afterAll } from "bun:test";
++import type { CodexAuthContext } from "../../src/codex/auth-context";
++import { recordContextSessionOwner, clearContextSessionOwnersForTests } from "../../src/codex/context-owner";
++import type { DataPlaneAdmission } from "../../src/server/auth-cors";
++import type { OcxConfig } from "../../src/types";
++import type { RequestLogContext } from "../../src/server/request-log";
++
++type Selection = { headers: Headers; mode: string; options: { modelId: string; admission?: DataPlaneAdmission; substituteMainCredentialForDirect?: boolean; accountId?: string; requestScopedMainCredential?: boolean } };
++let selection: Selection | undefined;
++const config: OcxConfig = { port: 0, defaultProvider: "openai", providers: {} };
++const logContext = (): RequestLogContext => ({ model: "context_history", provider: "" });
++let materialized: { config: OcxConfig; modelId: string } | undefined;
++let materializationError: Error | undefined;
++let materializationOptions: { admission?: DataPlaneAdmission; substituteMainCredential?: boolean } | undefined;
++let outgoingBearer = "test-only";
++let outgoingAccount = "test-only";
++let accountMode = "pool";
++let validated=0;
++let probe=false;let released=0;let directError=false;
++const errors = {
++  CodexAccountCooldownError: class extends Error {},
++  CodexMainSubstitutionUnavailableError: class extends Error {},
++  CodexDirectAuthenticationError: class extends Error {},
++  CodexAuthContextError: class extends Error {},
++  CodexMainProfileDrainingError: class extends Error {},
++  CodexPoolAuthenticationError: class extends Error {},
++  CodexThreadAffinityExpiredError: class extends Error {},
++};
++mock.module("../../src/codex/auth-context",()=>({
++  ...errors,
++  resolveCodexAuthContext:async(headers: Headers, _config: OcxConfig, mode: string, options: Selection["options"])=>{selection={headers,mode,options};if(directError)throw new errors.CodexDirectAuthenticationError();return {kind:"pool",accountId:"test-account",...(probe?{probeLeaseId:"test-probe"}:{})};},
++  isCodexAuthContextUsable:()=>true,
++  releaseCodexAuthContextProbeLease:()=>{released++;},
++  materializeCodexUpstreamAuth: (_headers: Headers, _auth: unknown, options: { config: OcxConfig; modelId: string; admission?: DataPlaneAdmission; substituteMainCredential?: boolean }) => {
++    materializationOptions = options;
++    materialized = { config: options.config, modelId: options.modelId };
++    if (materializationError) throw materializationError;
++    return new Headers({ authorization: `Bearer ${outgoingBearer}`, "chatgpt-account-id": outgoingAccount });
++  },
++  headersForCodexAuthContext:(_headers: Headers, _auth: unknown, selectedConfig: OcxConfig, modelId: string) => {
++    materialized = { config: selectedConfig, modelId };
++    if (materializationError) throw materializationError;
++    return new Headers({ authorization: "Bearer test-only", "chatgpt-account-id": outgoingAccount });
++  },
++  cooldownErrorResponse:()=>new Response("cooldown",{status:429}),
++  codexMainProfileDrainingResponse:()=>new Response("draining",{status:503}),
++}));
++const realRouting = await import("../../src/codex/routing");
++mock.module("../../src/codex/routing",()=>({...realRouting, formatCodexProviderForLog:()=>"openai-test"}));
++mock.module("../../src/providers/openai-sidecar",()=>({listOpenAiForwardSidecarCandidates:()=>[{providerName:"openai",provider:{baseUrl:"https://chatgpt.com/backend-api/codex"},accountMode}]}));
++class ForwardAdmissionCredentialError extends Error {}
++mock.module("../../src/server/auth-cors",()=>({ForwardAdmissionCredentialError,validateForwardAdmissionCredential:(h:Headers)=>{validated++;if(!h.has("authorization") || h.get("authorization") === "Bearer ocx_data_test_admission")throw new ForwardAdmissionCredentialError("test credential missing");}}));
++mock.module("../../src/server/responses",()=>({codexLogAccountId:()=>"test",decodeRequestErrorResponse:()=>new Response("invalid json",{status:400})}));
++mock.module("../../src/server/lifecycle",()=>({codexAccountSelectionForTurn:()=>()=>undefined}));
++const { handleContextHistory, contextSelectionHeaders } = await import("../../src/server/context-history");
++const destination = "https://chatgpt.com/backend-api/codex";
++function seedOwner(sessionId: string, kind: "stored" | "caller" = "stored", account = "test-only", now?: number) {
++  const auth = kind === "caller" ? { kind: "main", accountId: null } : {
++    kind: "pool", accountId: "test-account", chatgptAccountId: account,
++    accessToken: "test-only", generation: 1, writerGeneration: 0,
++  };
++  recordContextSessionOwner(new Headers({ "session-id": sessionId }), destination,
++    auth as CodexAuthContext, new Headers({ authorization: "Bearer test-only", "chatgpt-account-id": account }), false, now);
++}
++const originalFetch=globalThis.fetch;
++function setFetch(handler: (input: string | URL | Request, init?: RequestInit) => Promise<Response>): void {
++  globalThis.fetch = Object.assign(handler, { preconnect: originalFetch.preconnect });
++}
++afterAll(()=>{clearContextSessionOwnersForTests();globalThis.fetch=originalFetch;mock.restore();});
++beforeEach(()=>{clearContextSessionOwnersForTests();for (const id of ["root", "root-test", "s"]) seedOwner(id);outgoingAccount="test-only";globalThis.fetch=originalFetch;materialized=undefined;materializationError=undefined;selection=undefined;validated=0;materializationOptions=undefined;outgoingBearer="test-only";accountMode="pool";probe=false;released=0;directError=false;});
++
++describe("context relay contract",()=>{
++  test("selects root shared lane but sends original body and protocol headers",async()=>{
++    const body={context:{session_id:"root-test",current_agent_name:"/root"},encrypted_arguments:"opaque+==",unknown:{future:true}};
++    let sent: RequestInit & { url: string } = { url: "" };
++    setFetch(async(url: string | URL | Request, opts?: RequestInit)=>{sent={url:String(url),...opts};return new Response('{"ok":true}',{headers:{"content-type":"application/json","x-request-id":"req-test"}});});
++    const req=new Request("http://127.0.0.1/backend-api/codex/alpha/notes/v2/write_file",{method:"POST",headers:{authorization:"Bearer incoming","content-type":"application/json","x-openai-encrypted-tool-arguments":"true","x-openai-tool-output-truncation-policy":"{\"mode\":\"tokens\"}"},body:JSON.stringify(body)});
++    const r=await handleContextHistory(req,config,logContext(),"alpha/notes/v2/write_file");
++    expect(r.status).toBe(200);expect(r.headers.get("x-request-id")).toBe("req-test");
++    expect(materialized).toEqual({ config, modelId: "context_history" });
++    expect(validated).toBeGreaterThanOrEqual(1);expect(selection?.mode).toBe("pool");expect(selection?.options.modelId).toBe("context_history");
++    expect(selection?.headers.get("session-id")).toBe("root-test");expect(selection?.headers.get("thread-id")).toBe("root-test");expect(selection?.headers.get("x-codex-parent-thread-id")).toBeNull();
++    expect(JSON.parse(String(sent.body))).toEqual(body);expect(new Headers(sent.headers).has("session-id")).toBe(false);
++    expect(new Headers(sent.headers).get("x-openai-encrypted-tool-arguments")).toBe("true");expect(sent.redirect).toBe("manual");
++  });
++  test("propagates errors without retrying or hiding a write failure",async()=>{
++    let calls=0;
++    setFetch(async()=>{calls++;return new Response('{"error":"feature denied"}',{status:403,headers:{"retry-after":"7"}});});
++    const req=new Request("http://localhost/v1/alpha/notes/v2/write_file",{method:"POST",headers:{authorization:"Bearer test","content-type":"application/json"},body:JSON.stringify({context:{session_id:"s"}})});
++    const r=await handleContextHistory(req,config,logContext(),"alpha/notes/v2/write_file");
++    expect(r.status).toBe(403);expect(await r.text()).toBe('{"error":"feature denied"}');expect(r.headers.get("retry-after")).toBe("7");expect(calls).toBe(1);
++  });
++  test("rejects malformed context before any account selection",async()=>{
++    const req=new Request("http://localhost/v1/alpha/notes/v2/write_file",{method:"POST",headers:{authorization:"Bearer test","content-type":"application/json"},body:"{}"});
++    expect((await handleContextHistory(req,config,logContext(),"alpha/notes/v2/write_file")).status).toBe(400);expect(selection).toBeUndefined();
++    expect(contextSelectionHeaders(new Headers({"x-codex-parent-thread-id":"parent"}),"s").get("session-id")).toBeNull();
++  });
++});
++
++test("context traffic releases quota probe and maps missing direct auth",async()=>{
++ const request=()=>new Request("http://localhost/v1/alpha/notes/v2/read_file",{method:"POST",headers:{authorization:"Bearer test","content-type":"application/json"},body:JSON.stringify({context:{session_id:"root-test"}})});
++ probe=true;
++ expect((await handleContextHistory(request(),config,logContext(),"alpha/notes/v2/read_file")).status).toBe(503);
++ expect(released).toBe(1);
++ probe=false;directError=true;
++ expect((await handleContextHistory(request(),config,logContext(),"alpha/notes/v2/read_file")).status).toBe(401);
++});
++test("invalid header characters are rejected before selection",async()=>{
++ const req=new Request("http://localhost/v1/alpha/notes/v2/read_file",{method:"POST",headers:{authorization:"Bearer test","content-type":"application/json"},body:JSON.stringify({context:{session_id:"bad\nvalue"}})});
++ expect((await handleContextHistory(req,config,logContext(),"alpha/notes/v2/read_file")).status).toBe(400);
++ expect(selection).toBeUndefined();
++});
++
++function contextRequest(body: string, headers: HeadersInit = { authorization: "Bearer test" }, signal?: AbortSignal): Request {
++  return new Request("http://localhost/v1/alpha/notes/v2/read_file", { method: "POST", headers, body, signal });
++}
++
++test("missing admission credential fails before parsing or selecting an account", async () => {
++  const response = await handleContextHistory(contextRequest("not json", {}), config, logContext(), "alpha/notes/v2/read_file");
++  expect(response.status).toBe(401);
++  expect(selection).toBeUndefined();
++});
++
++test("malformed JSON and non-string or oversized session IDs fail before selection", async () => {
++  for (const body of ["not json", "null", JSON.stringify({ context: { session_id: 42 } }), JSON.stringify({ context: { session_id: "a".repeat(513) } })]) {
++    expect((await handleContextHistory(contextRequest(body), config, logContext(), "alpha/notes/v2/read_file")).status).toBe(400);
++    expect(selection).toBeUndefined();
++  }
++});
++
++test("existing session and child affinity headers are not overwritten", () => {
++  for (const entry of [{ "session-id": "existing" }, { "thread-id": "child" }, { "x-codex-parent-thread-id": "parent" }] as Record<string, string>[]) {
++    const headers = new Headers(entry);
++    const result = contextSelectionHeaders(headers, "root");
++    expect([...result]).toEqual([...headers]);
++    expect([...headers]).toEqual([...new Headers(entry)]);
++  }
++});
++
++test("network failures and client cancellation do not retry writes", async () => {
++  let calls = 0;
++  setFetch(async () => { calls++; throw new Error("test transport failure"); });
++  const body = JSON.stringify({ context: { session_id: "root" } });
++  expect((await handleContextHistory(contextRequest(body), config, logContext(), "alpha/notes/v2/write_file")).status).toBe(502);
++  const controller = new AbortController();
++  setFetch(async () => { calls++; controller.abort(); throw new Error("test canceled"); });
++  expect((await handleContextHistory(contextRequest(body, { authorization: "Bearer test" }, controller.signal), config, logContext(), "alpha/notes/v2/write_file")).status).toBe(499);
++  expect(calls).toBe(2);
++});
++
++test("unknown endpoints and methods are rejected before admission", async () => {
++  expect((await handleContextHistory(contextRequest("{}"), config, logContext(), "alpha/notes/v2/delete_file")).status).toBe(404);
++  expect((await handleContextHistory(new Request("http://localhost/v1/alpha/notes/v2/read_file"), config, logContext(), "alpha/notes/v2/read_file")).status).toBe(404);
++  expect(validated).toBe(0);
++  expect(selection).toBeUndefined();
++});
++
++test("credential materialization rechecks hardlocks and maps auth errors", async () => {
++  const body = JSON.stringify({ context: { session_id: "root" } });
++  let calls = 0;
++  setFetch(async () => { calls++; return new Response("unexpected"); });
++  for (const [error, status] of [[new errors.CodexAccountCooldownError(), 429], [new errors.CodexAuthContextError(), 401]] as const) {
++    materializationError = error;
++    const response = await handleContextHistory(contextRequest(body), config, logContext(), "alpha/notes/v2/read_file");
++    expect(response.status).toBe(status);
++    expect(materialized).toEqual({ config, modelId: "context_history" });
++  }
++  expect(calls).toBe(0);
++});
++
++
++const bearerAdmission: DataPlaneAdmission = { kind: "configured", keyId: "synthetic-key", source: "bearer" };
++const admissionHeaders = { authorization: "Bearer ocx_data_test_admission" };
++
++test("bearer-admitted context validates the body before selecting credentials", async () => {
++  const response = await handleContextHistory(contextRequest("{}", admissionHeaders), config, logContext(), "alpha/notes/v2/read_file", undefined, bearerAdmission);
++  expect(response.status).toBe(400);
++  expect(await response.text()).toContain("context.session_id");
++  expect(selection).toBeUndefined();
++});
++
++test("stored ownership remains fixed across current Direct and Pool settings", async () => {
++  let calls = 0;
++  setFetch(async (_url, init) => {
++    calls++;
++    expect(new Headers(init?.headers).get("authorization")).toBe("Bearer test-only");
++    return new Response("{}");
++  });
++  for (const mode of ["direct", "pool"]) {
++    accountMode = mode;
++    const response = await handleContextHistory(contextRequest('{"context":{"session_id":"root"}}', admissionHeaders), config, logContext(), "alpha/notes/v2/read_file", undefined, bearerAdmission);
++    expect(response.status).toBe(200);
++    expect(selection?.mode).toBe("pool");
++    expect(selection?.options.accountId).toBe("test-account");
++    expect(selection?.options.admission).toEqual(bearerAdmission);
++    expect(selection?.options.substituteMainCredentialForDirect).toBe(true);
++    expect(materializationOptions?.admission).toEqual(bearerAdmission);
++    expect(materializationOptions?.substituteMainCredential).toBe(true);
++  }
++  expect(calls).toBe(2);
++});
++
++test("proxy credentials cannot escape materialization or bypass non-bearer rejection", async () => {
++  let calls = 0;
++  setFetch(async () => { calls++; return new Response("unexpected"); });
++  outgoingBearer = "ocx_data_test_admission";
++  const body = '{"context":{"session_id":"root"}}';
++  const response = await handleContextHistory(contextRequest(body, admissionHeaders), config, logContext(), "alpha/notes/v2/read_file", undefined, bearerAdmission);
++  expect(response.status).toBe(401);
++  expect(materialized).toBeDefined();
++  for (const admission of [undefined, { kind: "environment", source: "dedicated" } as const, { kind: "loopback", source: "loopback" } as const]) {
++    selection = undefined;
++    expect((await handleContextHistory(contextRequest(body, admissionHeaders), config, logContext(), "alpha/notes/v2/read_file", undefined, admission)).status).toBe(401);
++    expect(selection).toBeUndefined();
++  }
++  expect(calls).toBe(0);
++});
++
++
++test("missing usable stored credentials fail before upstream I/O in bearer mode", async () => {
++  let calls = 0;
++  setFetch(async () => { calls++; return new Response("unexpected"); });
++  for (const mode of ["direct", "pool"]) {
++    accountMode = mode;
++    materializationError = mode === "direct"
++      ? new errors.CodexMainSubstitutionUnavailableError()
++      : new errors.CodexPoolAuthenticationError();
++    const response = await handleContextHistory(contextRequest('{"context":{"session_id":"root"}}', admissionHeaders), config, logContext(), "alpha/notes/v2/read_file", undefined, bearerAdmission);
++    expect(response.status).toBe(401);
++    expect(materializationOptions?.substituteMainCredential).toBe(true);
++  }
++  expect(calls).toBe(0);
++});
++
++
++test("unknown, expired and conflicting owners fail before selecting or sending", async () => {
++  let calls = 0;
++  setFetch(async () => { calls++; return new Response("unexpected"); });
++  for (const state of ["unknown", "expired", "conflicting"]) {
++    clearContextSessionOwnersForTests();
++    if (state === "expired") seedOwner("root", "stored", "test-only", Date.now() - 25 * 60 * 60_000);
++    if (state === "conflicting") { seedOwner("root"); seedOwner("root", "stored", "other-account"); }
++    expect((await handleContextHistory(contextRequest('{"context":{"session_id":"root"}}'), config, logContext(), "alpha/notes/v2/read_file")).status).toBe(409);
++    expect(selection).toBeUndefined();
++  }
++  expect(calls).toBe(0);
++});
++
++test("stored token refresh is accepted but physical account replacement is refused", async () => {
++  let calls = 0;
++  setFetch(async () => { calls++; return new Response("{}"); });
++  outgoingBearer = "refreshed-test-token";
++  const body = '{"context":{"session_id":"root"}}';
++  expect((await handleContextHistory(contextRequest(body), config, logContext(), "alpha/notes/v2/read_file")).status).toBe(200);
++  outgoingAccount = "replacement-account";
++  expect((await handleContextHistory(contextRequest(body), config, logContext(), "alpha/notes/v2/read_file")).status).toBe(409);
++  expect(calls).toBe(1);
++});
++
++test("caller owner uses Direct request credentials and cannot authorize proxy-bearer substitution", async () => {
++  clearContextSessionOwnersForTests(); seedOwner("root", "caller");
++  let calls = 0;
++  setFetch(async () => { calls++; return new Response("{}"); });
++  const body = '{"context":{"session_id":"root"}}';
++  expect((await handleContextHistory(contextRequest(body), config, logContext(), "alpha/notes/v2/read_file")).status).toBe(200);
++  expect(selection?.mode).toBe("direct");
++  expect(selection?.options.requestScopedMainCredential).toBe(true);
++  expect(selection?.options.accountId).toBeUndefined();
++  expect(materializationOptions?.substituteMainCredential).toBe(false);
++  selection = undefined;
++  expect((await handleContextHistory(contextRequest(body, admissionHeaders), config, logContext(), "alpha/notes/v2/read_file", undefined, bearerAdmission)).status).toBe(409);
++  expect(selection).toBeUndefined(); expect(calls).toBe(1);
++});
++
++test("a context root conflicting with protocol headers is rejected without selection", async () => {
++  const response = await handleContextHistory(contextRequest('{"context":{"session_id":"root"}}', {
++    authorization: "Bearer test", "session-id": "another-root",
++  }), config, logContext(), "alpha/notes/v2/read_file");
++  expect(response.status).toBe(409); expect(selection).toBeUndefined();
++});
+diff --git a/tests/server/server-live.test.ts b/tests/server/server-live.test.ts
+index 16ee4c7946..bf096961b0 100644
+--- a/tests/server/server-live.test.ts
++++ b/tests/server/server-live.test.ts
+@@ -198,7 +198,7 @@ test("POST /v1/live rewrites ChatGPT multipart into backend realtime/calls JSON"
+   }
+ });
+
+-test("POST /v1/live relays to an OpenAI API-key provider at /v1/live without AVAS", async () => {
++test.each(["/v1/live", "/backend-api/codex/live"])("POST %s relays to an OpenAI API-key provider at /v1/live without AVAS", async (path) => {
+   const captured: CapturedRequest[] = [];
+   const upstream = fakeLiveUpstream(captured, 201, "/v1/live/rtc_api");
+   saveConfig({
+@@ -217,7 +217,7 @@ test("POST /v1/live relays to an OpenAI API-key provider at /v1/live without AVA
+   const server = startServer(0);
+   try {
+     const { body, contentType } = multipartLiveBody();
+-    const response = await fetch(new URL("/v1/live", server.url), {
++    const response = await fetch(new URL(path, server.url), {
+       method: "POST",
+       headers: { "content-type": contentType },
+       body,
+diff --git a/tests/server/server-management-auth.test.ts b/tests/server/server-management-auth.test.ts
+index aece9bc93a..22554b6cad 100644
+--- a/tests/server/server-management-auth.test.ts
++++ b/tests/server/server-management-auth.test.ts
+@@ -4,6 +4,7 @@ import { mkdtempSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+ import { tmpdir } from "node:os";
+ import { join } from "node:path";
+ import { getConfigPath, saveConfig } from "../../src/config";
++import { clearContextSessionOwnersForTests } from "../../src/codex/context-owner";
+ import { startServer } from "../../src/server";
+ import { findAvailablePort } from "../../src/server/ports";
+ import type { OcxConfig } from "../../src/types";
+@@ -589,6 +590,71 @@ describe("management and data-plane credential separation", () => {
+     }
+   });
+
++  test("Codex backend aliases retain data-plane authentication and cannot enter management", async () => {
++    saveConfig(remoteConfig());
++    const server = startServer(0);
++    try {
++      for (const token of [undefined, "admin-secret", "data-secret"]) {
++        const headers: Record<string, string> = token ? { "x-opencodex-api-key": token } : {};
++        const models = await fetch(new URL("/backend-api/codex/models", server.url), { headers });
++        expect(models.status).toBe(token === "data-secret" ? 200 : 401);
++        const context = await fetch(new URL("/backend-api/codex/alpha/notes/v2/read_file", server.url), {
++          method: "POST", headers, body: "{}",
++        });
++        expect(context.status).toBe(token === "data-secret" ? 400 : 401);
++        const management = await fetch(new URL("/backend-api/codex/api/config", server.url), { headers });
++        expect(management.status).toBe(404);
++      }
++    } finally {
++      await server.stop(true);
++    }
++  });
++
++  test("context bearer admission reaches body validation without accepting foreign credentials", async () => {
++    saveConfig(remoteConfig());
++    const server = startServer(0);
++    try {
++      for (const prefix of ["/v1", "/backend-api/codex"]) {
++        for (const token of ["data-secret", "admin-secret", "foreign-secret"]) {
++          const response = await fetch(new URL(`${prefix}/alpha/notes/v2/read_file`, server.url), {
++            method: "POST", headers: { authorization: `Bearer ${token}` }, body: "{}",
++          });
++          expect(response.status).toBe(token === "data-secret" ? 400 : 401);
++          if (token === "data-secret") expect(await response.text()).toContain("context.session_id");
++        }
++      }
++    } finally {
++      await server.stop(true);
++    }
++  });
++
++  test("authenticated context without a successful model owner fails closed on both listener prefixes", async () => {
++    const cfg = remoteConfig();
++    cfg.providers.openai = { adapter: "openai-responses", baseUrl: "https://chatgpt.com/backend-api/codex", authMode: "forward", codexAccountMode: "pool" };
++    saveConfig(cfg); clearContextSessionOwnersForTests();
++    const originalFetch = globalThis.fetch;
++    let upstreamCalls = 0;
++    globalThis.fetch = Object.assign(async (input: string | URL | Request, init?: RequestInit) => {
++      const url = new URL(input instanceof Request ? input.url : String(input));
++      if (url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]" || url.hostname === "0.0.0.0") return originalFetch(input, init);
++      upstreamCalls++; throw new Error("unknown context owner must not reach upstream");
++    }, { preconnect: originalFetch.preconnect });
++    const server = startServer(0);
++    try {
++      for (const prefix of ["/v1", "/backend-api/codex"]) {
++        const response = await fetch(new URL(`${prefix}/alpha/notes/v2/read_file`, server.url), {
++          method: "POST", headers: { authorization: "Bearer data-secret" },
++          body: JSON.stringify({ context: { session_id: "unknown-root" } }),
++        });
++        expect(response.status).toBe(409);
++        expect(await response.text()).toContain("context_account_unavailable");
++      }
++      expect(upstreamCalls).toBe(0);
++    } finally {
++      await server.stop(true); globalThis.fetch = originalFetch; clearContextSessionOwnersForTests();
++    }
++  });
++
+   test("data and management environment tokens authorize only their own planes", async () => {
+     saveConfig(remoteConfig());
+     const server = startServer(0);
+```
diff --git a/devlog/_plan/260912_history_containment/040_verification.md b/devlog/_plan/260912_history_containment/040_verification.md
new file mode 100644
index 0000000000..f63c9d4816
--- /dev/null
+++ b/devlog/_plan/260912_history_containment/040_verification.md
@@ -0,0 +1,7 @@
+# Final evidence and Windows recovery disposition
+
+MODIFY .tmp/history-lane/handoff.md with current branch/head, each original PR/issue disposition, carry URLs, exact hosted run IDs/results and remaining review/acceptance. No production change for #3522 without same-process evidence.
+
+Read current #3522 comments and #3790 landed ancestry; inspect windows-secret-acl and responses/state recovery ownership. Compare alleged failure against existing tests without running local suites. Distinguish synthetic hosted Windows evidence from the reported live-process incident.
+
+Run existing GitHub hosted CI against final carried tip(s), inspect failures with gh run view --log-failed, amend only justified defects, and repeat final-head CI when changed. Do not cancel workflows, change protections, or merge. Local tests/build/typecheck/install: NOT RUN. Text proof: git diff --check. Evidence JSON includes headSha, run id, event, status, conclusion and URL.
diff --git a/devlog/_plan/260912_history_containment/051_resume_status.md b/devlog/_plan/260912_history_containment/051_resume_status.md
new file mode 100644
index 0000000000..98b7c5d92c
--- /dev/null
+++ b/devlog/_plan/260912_history_containment/051_resume_status.md
@@ -0,0 +1,25 @@
+# Resumed history verification
+
+Continuation carry #4350 was merged by the coordinator; its final-head hosted run 34673958547
+completed successfully. Containment carry #4342 was also merged, but run 34674692660 failed and
+has not been represented as passing. Relay #4360 remains draft; latest inspected carry92592066
+includes the independently supplied activation-fixture update. Run34682796830 failed.
+
+This repair addresses hosted history-owned failures: canonical temporary-home identities on macOS,
+explicit failed config artifacts, complete preimage preservation after failed cleanup, admission
+principal result fields and relay error/credential validation ordering. Default-off dispatch is
+revalidated after asynchronous waits. Listener cancellation coverage observes actual active-turn
+accounting; a manually released fake lease is not release evidence.
+
+Local product suites, builds, typecheck and installation: NOT RUN by explicit user direction.
+Regression source and independent source review are not a runtime pass. Final repaired-head hosted
+CI remains required. Unrelated GUI/client/translation failures are recorded for their owners and
+are not changed in this lane. No new worktree, task, account setting or service mutation occurred.
+
+The host goal is blocked and the persisted workflow remains A. Its state was not reset or edited;
+authorized repairs continue under the explicit resume instruction. This status does not claim a
+completed verification cycle.
+
+The prior same-process Windows spill impossibility conclusion is withdrawn: the existing ACL
+compliance check executes before the timeout-memo refusal. Actual long-lived process recovery,
+native paginated-writer support and damaged-history recovery remain unverified and unresolved.
diff --git a/devlog/_plan/260912_omo_client_integration/000_plan.md b/devlog/_plan/260912_omo_client_integration/000_plan.md
new file mode 100644
index 0000000000..1dac5ccb34
--- /dev/null
+++ b/devlog/_plan/260912_omo_client_integration/000_plan.md
@@ -0,0 +1,88 @@
+# omo as an export and integration client
+
+## What this unit adds
+
+`omo-ai@beta` (5.0.0-0.beta.53, bin `omo`, repo `code-yeongyu/oh-my-openagent`)
+describes itself as "omo native edition - the senpi-based OMO harness". It keeps
+engine state under `~/.omo/agent` and its allowlist of carried-forward state
+files names `models.json` — the same custom-provider catalog Pi, Prime and Aside
+read. The user asked for its preset to appear on the Integrations page beside
+the other thirteen clients, with a real brand mark.
+
+This unit registers `omo` as the fourteenth export client and the fourteenth
+file integration, reusing the Pi builder the way `prime` and `aside` already do
+rather than restating the document shape a fourth time.
+
+## Why the Pi family is the right precedent
+
+`prime` is documented in `src/clients/config-export.ts` as "the pi coding agent
+shipped under a different brand": it derives its config directory and env prefix
+from its own `piConfig` block, so `models.json` is the same contract. omo reaches
+the same place by a different route — it is a harness around
+`@code-yeongyu/senpi`, written by the same author as Pi — so the claim has to be
+verified against senpi's parser rather than assumed from the family
+resemblance. `001_omo_contract.md` carries that evidence; the builder is only
+reused where the bytes are verified to be accepted.
+
+## Path resolution
+
+omo publishes its own precedence in `bin/lib/agent-dir.js`:
+`OMO_CODING_AGENT_DIR`, then `SENPI_CODING_AGENT_DIR`, then
+`PI_CODING_AGENT_DIR`, then `~/.omo/agent`. The third entry is Pi's variable and
+is deliberately honored by omo itself, so mirroring the chain is reporting omo's
+contract, not inventing a shared one. Relative overrides are refused for the
+reason MCode, ZCode, Pi and Prime already refuse them: a background proxy and a
+foreground client can have different working directories and would otherwise
+disagree about which file is named.
+
+## Work phases
+
+| id | phase | contents |
+|----|-------|----------|
+| wp1 | roadmap | this unit: contract evidence, registration checklist, mark provenance, per-phase docs |
+| wp2 | registration | the whole atomic change: path helpers, `EXPORT_CLIENTS.omo`, contribution, `INTEGRATION_CLIENTS.omo`, CLI help and count, catalog-refresh fan-out, every GUI list and record, the mark wiring, nine locales, and every test literal and allowlist that moves with them |
+| wp3 | GUI verification | build and serve this worktree's GUI, confirm the row, tab and mark render, and copy-edit the semantics prose against what the page actually shows |
+| wp4 | docs | `docs-site` agents reference and integrations guide, English plus translated locales |
+| wp5 | verification | typecheck, focused tests, GUI build, and the rendered dashboard proving the row and tab exist |
+| wp6 | gjc rename | the Gajae Code label becomes `gjc` on every user-visible surface, with the `gajae` id untouched |
+
+wp3, wp4 and wp6 each depend on wp2; wp5 depends on wp3 and wp4.
+
+**Why wp2 is one phase and not two.** The first plan split backend from GUI.
+Two audit rounds failed it on the same ground.
+`tests/gui/integrations-invariants.test.ts` asserts sorted equality between
+`EXPORT_CLIENT_IDS` and five lists, three of which live in `gui/src`; the GUI
+test literals and the two translation allowlists hang off the same edit; and CI
+runs `cd gui && bun test` unconditionally. There is no ordering of the halves
+that leaves the tree green at the boundary, so registration is one change.
+
+## Scope boundaries
+
+In scope: registration of one new client id across the surfaces
+`002_registration_checklist.md` enumerates, plus its brand mark and its docs
+rows.
+
+Out of scope: any change to how the Pi document is built for the existing
+clients; any new remote-bind credential path; any change to the Integrations
+page layout or to the journal/rollback machinery; publishing, releasing, or
+pushing anything.
+
+Also out of scope, deliberately: renaming the `gajae` client **id**. wp6 changes
+what the user reads, not what the system keys on. The id is the segment in
+`/api/client-integrations/gajae` and the key an enable record is filed under, so
+renaming it would orphan the stored state of anyone who already connected that
+client and leave our ownership record unable to match the block it wrote. The
+user asked for the short name and chose the label-only scope.
+
+## Terminal outcomes
+
+DONE requires all five criteria in the bound goalplan to hold with fresh proof:
+the row and tab render on the running dashboard with a real mark, the exported
+document matches the schema omo parses at the path omo resolves, `bun run
+typecheck` is clean, every exact-list test passes with omo included plus a new
+omo test, and an enable/disable round trip writes and removes only the owned
+fragments.
+
+BLOCKED is the outcome if senpi turns out to reject the Pi document and no
+honest mapping exists. NEEDS_HUMAN is the outcome if omo publishes no usable
+first-party mark and the user wants something other than the monogram fallback.
diff --git a/devlog/_plan/260912_omo_client_integration/001_omo_contract.md b/devlog/_plan/260912_omo_client_integration/001_omo_contract.md
new file mode 100644
index 0000000000..663ec0dd37
--- /dev/null
+++ b/devlog/_plan/260912_omo_client_integration/001_omo_contract.md
@@ -0,0 +1,96 @@
+# What omo actually reads
+
+Evidence: `omo-ai` version `5.0.0-0.beta.53` unpacked at `/tmp/omoprobe2/package`,
+and `@code-yeongyu/senpi` version `2026.9.10-2` unpacked at
+`/tmp/senpiprobe/package`. Schema
+claims below were executed against that tarball's own TypeBox compiler
+(`typebox@1.3.18`), not read off documentation.
+
+## omo parses nothing
+
+`bin/omo.js` either runs setup or `runLauncher()`, and the launcher brands senpi
+and spawns it. The catalog is senpi's. Branded with `configDir: ".omo"` and
+`flatLayout: false`, senpi resolves `getModelsPath() = join(getAgentDir(),
+"models.json")` (`senpi dist/config.js:506-508`), which with omo's default agent
+directory (`bin/lib/agent-dir.js:41-43`) is `~/.omo/agent/models.json`.
+
+omo's own setup only *inspects* that path — `setup-detect.js:139-143` lists it in
+`detectedFilePaths`, and `setup-models.js:19` tells the user to define the
+provider `baseUrl` in it. Setup writes `auth.json`, never `models.json`, so
+opencodex is not fighting omo's installer for the file.
+
+## Path precedence
+
+The launcher resolves, first non-empty trimmed value winning:
+`OMO_CODING_AGENT_DIR`, `SENPI_CODING_AGENT_DIR`, `PI_CODING_AGENT_DIR`, else
+`~/.omo/agent` (`agent-dir.js:15,33-38`). It then *overwrites* the first two with
+the resolved absolute path before spawning senpi, so senpi's own lookup — which
+reads the same three names in the same order (`brand.js:126-140`,
+`config.js:456-457`) — always finds the launcher's answer and never reaches its
+project-local `.omo/agent` walk.
+
+Home is `env.HOME || env.USERPROFILE || os.homedir()` (`agent-dir.js:27-30`).
+
+That third variable is Pi's. omo honors it deliberately, so `omoAgentDir` reading
+it is reporting omo's contract rather than asserting a shared one.
+
+## The provider block senpi validates
+
+`providers` is a keyed object; each provider's `models` is an **array** whose
+identity is `id`, not a keyed object — a keyed object fails with `must be array`
+(`model-config-schema.js:201-220`). That is Pi's shape, not OpenCode's.
+
+Accepted provider keys include `baseUrl`, `apiKey`, `api`, `headers`
+(`Record<string, string>`), `compat`, `models`, and `modelOverrides`. `api` is a
+bare string at schema time rather than an enum; an unknown value loads and then
+fails at stream time (`provider-composer.js:274-277`). `openai-completions` is a
+known api (`types.d.ts:25`) and validates.
+
+`thinkingLevelMap` accepts exactly the keys the Pi builder emits — `off`,
+`minimal`, `low`, `medium`, `high`, `xhigh`, `max` — each `string | null`
+(`model-config-schema.js:65-72`), so emitting `max: "ultra"` as a *value* is
+fine.
+
+`input` accepts `text`, `image`, `video` (`model-config-schema.js:170`). `audio`
+is rejected — and rejection is not local: a schema failure empties the whole
+`models.json` snapshot (`model-config.js:483-487`), so one bad row takes every
+custom provider down. This is Pi's failure mode exactly, and it is why
+`buildPiClientConfig` drops an audio-only row instead of claiming `text` for it.
+
+`cost` is optional, but a *partial* `cost` is a schema failure: all four rates
+are required (`model-config-schema.js:141-155`). The Pi builder omits `cost`
+entirely, which is the safe side of that line.
+
+## Verdict
+
+**The bytes `buildPiClientConfig` emits are accepted verbatim.** Nothing needs
+renaming, adding, or removing. That was confirmed by running the document
+through senpi's compiled validator, not inferred from the family resemblance.
+
+`compat.sendSessionAffinityHeaders` also validates
+(`model-config-schema.js:111,210`), so omo takes the builder's
+`sendSessionAffinityHeaders` flag as `true`, the way `pi` does and `prime` and
+`aside` do not.
+
+## Why omo is still loopback-only
+
+senpi's provider block *does* accept `headers`, and it interpolates `$ENV` and
+`${ENV}` in values (`provider-api-key-auth.js:107-117`), so unlike Aside there is
+somewhere an `x-opencodex-api-key` could live. What does not exist is a builder
+that emits it: `buildPiClientConfig` writes no `headers` at all
+(`src/clients/config-export.ts:854-866`), which is exactly why `pi` itself is
+loopback-only.
+
+So `loopbackOnly: true` for omo is OMP's and Prime's stance rather than Aside's:
+the field exists, the remote credential wiring is deferred, and a non-loopback
+bind refuses instead of generating a config that 401s. Adding `headers` to the
+shared Pi builder would change four clients at once and is out of this unit's
+scope.
+
+## Left unverified
+
+- Whether the dummy `apiKey` is copied into an `Authorization` header at stream
+  time (would need `pi-ai/dist/api/openai-completions.js`). Irrelevant for a
+  loopback bind, which admits without a key.
+- `oauth: "radius"` appears in senpi's `docs/models.md:139` but not in the live
+  schema. Not used here.
diff --git a/devlog/_plan/260912_omo_client_integration/002_registration_checklist.md b/devlog/_plan/260912_omo_client_integration/002_registration_checklist.md
new file mode 100644
index 0000000000..dcf057d8b8
--- /dev/null
+++ b/devlog/_plan/260912_omo_client_integration/002_registration_checklist.md
@@ -0,0 +1,132 @@
+# Every surface a new export client must reach, as of 2026-09-12
+
+The Aside unit wrote this list on 2026-08-31
+(`devlog/_fin/260831_aside_client_and_integrations_ux/002_registration_checklist.md`).
+Two things have moved since: `tests/` was reorganised into domain directories,
+and `raycast` landed as the thirteenth client, with its own app-side status block.
+The table below is re-derived against the current tree by word-boundary search
+for `raycast`, the freshest template.
+
+## Backend
+
+| file | what omo needs | how failure shows |
+|---|---|---|
+| `src/clients/config-export/contracts.ts` | `"omo"` in `ExportClientId` | typecheck, everywhere |
+| `src/clients/config-export.ts` | `omoAgentDir`, `omoConfigPath`, `buildOmoContribution`, `EXPORT_CLIENTS.omo` | typecheck |
+| `src/integrations/registry.ts` | `INTEGRATION_CLIENTS.omo` | typecheck |
+| `src/cli/registry.ts` | the `export` usage union and the prose summary | no exact-list gate; `tests/cli/cli-help.test.ts` checks only a prefix of the union |
+| `src/cli/help.ts:84` | the `(13 clients)` literal | `tests/cli/cli-help.test.ts:79` |
+
+The count literal lives in `help.ts`, not `registry.ts`, hand-written on purpose
+so `ocx --help` does not import the export registry.
+`tests/cli/cli-help.test.ts:79` asserts it in lockstep with
+`EXPORT_CLIENT_IDS.length`, so it is a focused-test obligation rather than a
+cosmetic edit.
+
+`/api/client-config` is served from `src/server/management/model-routes.ts:516`,
+not `config-routes.ts` as the 2026-08-31 doc says; it reads the registry and
+needs no per-client edit. `ExportClientId` likewise moved to
+`src/clients/config-export/contracts.ts:84`.
+
+`src/integrations/ownership-policy.ts`, `state.ts` and `writer.ts` need nothing:
+the first is a `zcode`-only exception, and the other two read the registry.
+`bun run skill:surface` is not implicated — a new `--client` value creates no
+capability.
+
+## GUI
+
+| file | what omo needs | how failure shows |
+|---|---|---|
+| `gui/src/components/apikeys-workspace/client-config-clients.ts` | `CLIENTS`, `CLIENT_LABEL_KEYS`, `CLIENT_MARKS`, possibly `MONOCHROME_CLIENT_MARKS` | invariant test + typecheck |
+| `gui/src/components/integration-marks.ts` | `INTEGRATION_MARKS.omo` | typecheck (exhaustive record) |
+| `gui/src/pages/integrations/integration-api.ts` | `INTEGRATION_CLIENT_IDS` | invariant test |
+| `gui/src/pages/integrations/integration-tabs.ts` | `TABS` and `FILE_CLIENTS` | **silent** — only `gui/tests/integrations-tab-coverage.test.ts` |
+| `gui/src/pages/integrations/overview-clients.ts` | `FILE_LABEL_KEY` | typecheck |
+| `gui/src/pages/integrations/FileIntegrationPage.tsx` | `SEMANTICS_KEY`, `TAB_LABEL_KEY`, `FILE_INTEGRATION_CLIENTS` | typecheck + invariant test |
+| `gui/src/app-routing.ts` | `integrations/omo` hash | **silent** |
+| `gui/src/i18n/{en,de,fr,ja,ko,ru,tr,zh,zh-TW}.ts` | three keys each | `locale-parity` |
+
+## Docs
+
+`docs-site/src/content/docs/reference/cli/agents.md` plus `fr`, `ja`, `ko`, `ru`,
+`tr`, `zh-cn`, `zh-tw`; `docs-site/src/content/docs/guides/integrations.md` plus
+`fr`, `tr`, `zh-tw`.
+
+## Tests that fail until updated
+
+`tests/config/client-config-export.test.ts`,
+`tests/config/client-config-export-new-clients.test.ts`,
+`tests/gui/integrations-invariants.test.ts`,
+`tests/clients/integrations-state.test.ts`,
+`tests/clients/sync-client-integrations.test.ts`,
+`tests/clients/integrations-merge.test.ts`,
+`tests/cli/cli-export-command.test.ts`,
+`tests/cli/cli-headless-parity.test.ts`,
+`tests/server/management-integration-routes.test.ts`,
+`tests/server/management-client-config-route.test.ts`,
+`gui/tests/{client-config-panel.test.tsx,integrations-api.test.ts,integrations-overview-rows.test.ts,integration-marks.test.ts,client-marks-assets.test.ts,locale-parity.test.ts,fr-localization.test.ts,integrations-tab-coverage.test.ts}`.
+
+Of these, the ones verified to hardcode a list or a count are:
+`tests/config/client-config-export.test.ts:812` (ordered thirteen ids),
+`tests/config/client-config-export-new-clients.test.ts:68` and
+`tests/clients/integrations-state.test.ts:799` (loopback-only set),
+`tests/gui/integrations-invariants.test.ts:94` (`toHaveLength(13)`, plus the
+typechecked `SEED` record), `tests/cli/cli-help.test.ts:79` (the client count),
+`gui/tests/integrations-api.test.ts:20` and
+`gui/tests/client-config-panel.test.tsx:174` (GUI literals), and
+`gui/tests/integrations-overview-rows.test.ts:293` (row count 18 to 19 — the
+overview carries five non-file rows on top of the clients).
+
+`gui/tests/integrations-tab-coverage.test.ts` still exists and still reads
+`TABS`, `FILE_CLIENTS` and the routable hashes, so the 2026-08-31 silent hole is
+covered — conditional on `FILE_INTEGRATION_CLIENTS` being updated, since that is
+what the coverage test compares against.
+
+## New files
+
+`tests/clients/omo-client.test.ts` needs an entry in both
+`scripts/test-layout/layout.json` `explicit` and
+`tests/fixtures/test-layout-expected.json`, or `tests/test-layout-tooling.test.ts`
+names the missing one.
+
+The explicit entries are not optional here: the `clients` domain regex does not
+match an `omo-` prefix, so the seed cannot place the file. Model the test on
+`tests/clients/prime-client.test.ts` rather than the Aside one — Aside's test
+lives under `providers` because of that same regex, which would be the wrong
+precedent to copy.
+
+## Deliberately not copied from the neighbours
+
+Aside's profile machinery (`aside-profile-*`, the per-profile journal routes) and
+Raycast's app-side install block and live-server export branch are client-specific
+surfaces, not part of registration. omo has neither.
+
+## One list that is a judgement, not a checklist item
+
+There is not one owned-catalog fan-out list, there are four, and they disagree:
+
+| call site | list | what triggers it |
+|---|---|---|
+| `src/integrations/catalog-refresh.ts` default, used by `model-routes.ts` | `pi, aside, raycast` | model visibility changed from the dashboard |
+| `src/server/management/config-routes.ts:240` | `mcode, pi, aside, raycast` | the `/api/sync` route |
+| `src/cli/dispatch.ts:455` | `mcode, pi, raycast` | `ocx sync` (Aside follows immediately through its own server owner) |
+| `src/cli/index.ts` | `raycast` | proxy start, via a helper literally named `refreshOwnedRaycastCatalog` |
+
+`prime` is in none of them. Updating one and not the others is the failure
+mode, so the decision is taken here rather than in passing.
+
+**Decision: omo joins the three general fan-outs — the `catalog-refresh`
+default, `config-routes.ts`, and `dispatch.ts` — and not the fourth.** The
+refresh only touches clients that are *already connected*
+(`catalog-refresh.ts:10`), so this costs a user who never enables omo exactly
+nothing, and it is what stops a connected omo catalog going stale the moment the
+user changes model visibility. The fourth is not a general list at all: it is a
+Raycast-specific startup helper, and adding an unrelated client to it would
+write a file on every `ocx start` for no reason.
+
+`tests/clients/sync-client-integrations.test.ts:68` pins the `config-routes.ts`
+list as source text and moves with it.
+
+That `prime` is in no list looks like an oversight from when it landed. Fixing
+it is not this unit's business; it is recorded here so the next person does not
+read prime's absence as a deliberate pattern to copy.
diff --git a/devlog/_plan/260912_omo_client_integration/003_brand_mark_provenance.md b/devlog/_plan/260912_omo_client_integration/003_brand_mark_provenance.md
new file mode 100644
index 0000000000..02cf7a9cfa
--- /dev/null
+++ b/devlog/_plan/260912_omo_client_integration/003_brand_mark_provenance.md
@@ -0,0 +1,43 @@
+# The omo mark
+
+## Source
+
+`gui/public/provider-icons/omo.svg` is `https://omo.dev/brand/omo-mark.svg`
+unmodified: 4021 bytes, MD5 `c33f72d7c4612c290834ba860f644557`,
+`viewBox="0 0 1024 1024"`. The identical file is committed as
+`.github/assets/omo-icon-light.svg` in `code-yeongyu/oh-my-openagent` and
+rendered as that README's logo, so the same artwork is both the site header mark
+and the repository logo. First-party either way.
+
+**Correction.** The first draft of this doc cited the GitHub raw path on `main`.
+That URL 404s: the repository's default branch is `dev`. The asset is real and
+the bytes match — verified by downloading both and comparing MD5 — but the
+branch in the citation was wrong, which is the kind of unreproducible provenance
+the README exists to prevent. Both citations now name a URL that resolves.
+
+The project's SUL-1.0 licence says trademark use is "subject to applicable law"
+and imposes no distribution ban of the kind that disqualified an earlier
+candidate elsewhere in this directory.
+
+## Rejected candidates
+
+- `https://omo.dev/icon.svg` — a single `<text>O</text>` glyph. The client-mark
+  asset test refuses `<text>`, the same rule that sent Hermes to a trace.
+- `omo-logo.png` — a superseded 3D rock illustration, and a raster.
+- `omo.png` — a landscape screenshot, not a mark.
+- The npm tarball carries no `.svg`, `.png`, or `.ico` at all.
+
+## Which maps it joins
+
+`CLIENT_MARKS.omo` — yes.
+
+`MONOCHROME_CLIENT_MARKS` — no. The artwork is two inks: an `#F4F4F4` rounded
+plate with an `#041617` face on it. Masking a plated mark discards the plate and
+the face together and renders a filled square at 20px, which is the failure the
+monochrome set exists to avoid rather than an instance of it.
+
+Provenance is recorded alongside the file in
+`gui/public/provider-icons/README.md`, in both the per-file source list and the
+masked/not-masked ledger. That was done in wp1 rather than wp3: the asset landed
+in this cycle, and an uncited file in that directory is exactly what the README
+exists to prevent.
diff --git a/devlog/_plan/260912_omo_client_integration/010_wp2_backend.md b/devlog/_plan/260912_omo_client_integration/010_wp2_backend.md
new file mode 100644
index 0000000000..3fc5ccf671
--- /dev/null
+++ b/devlog/_plan/260912_omo_client_integration/010_wp2_backend.md
@@ -0,0 +1,205 @@
+# wp2 — registration, as one atomic change
+
+## Why this phase is not backend-only
+
+The first draft split backend from GUI. An audit round failed it, correctly:
+`tests/gui/integrations-invariants.test.ts` asserts sorted equality between
+`EXPORT_CLIENT_IDS` and five GUI lists, so the moment the backend knows about a
+fourteenth client and the GUI does not, that test is red — and leaving it at
+thirteen is red against the backend instead. There is no ordering of the two
+halves that keeps the tree green.
+
+A further binding runs the same way, though not where it first looks.
+`CLIENT_LABEL_KEYS` is an `as const` map, not an annotated
+`Record<…, TKey>`; the type pressure comes from its use sites —
+`t(CLIENT_LABEL_KEYS[client])` and the exhaustive
+`Record<FileIntegrationClientId, TKey>` maps — where `TKey` is
+`keyof typeof en` and every other catalog is a `Record<TKey, string>`. So a new
+label key has to exist in `en` to compile and in all nine catalogs to keep
+parity. i18n is part of the same atomic change rather than a follow-up.
+
+So wp2 is the whole registration: backend, GUI source lists, marks wiring, the
+nine locale catalogs, **and every test literal and allowlist that moves with
+them** — including `gui/tests/client-config-panel.test.tsx`,
+`gui/tests/integrations-api.test.ts`, the row count in
+`gui/tests/integrations-overview-rows.test.ts`, `ZH_TW_KEEP_ENGLISH` in
+`gui/tests/locale-parity.test.ts` and `INTENTIONAL_ENGLISH` in
+`gui/tests/fr-localization.test.ts`. A second audit round caught the earlier
+version leaving those in wp3: CI runs `cd gui && bun test` unconditionally, so a
+finished wp2 would have been red on five GUI suites.
+
+The `integrations.semantics.omo` string is therefore written in wp2 too, in all
+nine locales — a placeholder would fail locale parity just as an absent key
+would. wp3 copy-edits it against the rendered page rather than creating it.
+
+**wp2's closing condition** is that all three are green together: `bun run
+typecheck`, the focused root tests, and `cd gui && bun test`.
+
+## Files and what each gains
+
+`src/clients/config-export/contracts.ts`
+: `"omo"` in the `ExportClientId` union. Every exhaustive `Record<ExportClientId, …>`
+  in the tree becomes a typecheck error until it is filled, which is the point.
+
+`src/clients/config-export.ts`
+: `omoAgentDir` and `omoConfigPath` helpers implementing omo's published
+  precedence (`OMO_CODING_AGENT_DIR`, `SENPI_CODING_AGENT_DIR`,
+  `PI_CODING_AGENT_DIR`, `~/.omo/agent`), a `buildOmoContribution` that stamps
+  omo's ownership on the shared Pi fragment, and the `EXPORT_CLIENTS.omo` spec
+  with all nine fields. `filename` is `omo-models.json` rather than a bare
+  `models.json`, for the Downloads-folder collision reason `prime-models.json`
+  and `aside-models.json` already record.
+
+  Each of the three variables is resolved separately and reports `ClientPathError`
+  under **its own name**, so a user who set `OMO_CODING_AGENT_DIR` is not told
+  that `PI_CODING_AGENT_DIR` is wrong. An empty or whitespace value falls through
+  to the next name, which is what `agent-dir.js` does.
+
+  One consequence is worth stating rather than discovering: a user who has set
+  `PI_CODING_AGENT_DIR` and neither of the other two now has Pi and omo
+  resolving the **same** `models.json`. Both write the same `providers.opencodex`
+  block through the same builder, so the bytes agree; what does not agree is
+  ownership, since two enable records would claim one file. That is omo's own
+  contract — it reads Pi's variable by design — and the honest response is to
+  document it, not to silently diverge from the client we are configuring.
+
+  One divergence is deliberate and worth naming: omo `resolve()`s its override
+  against the process cwd and does not expand `~`. We refuse a relative override
+  and do expand `~`, exactly as Pi, Prime, MCode and ZCode already do, because a
+  background proxy and a foreground client have different working directories.
+
+  `buildOmoContribution` calls `buildPiClientConfig(ctx, true)` — with the flag,
+  not the default. Prime and Aside pass the default in their contribution while
+  their `build` also passes the default, so they are consistent; splitting the
+  flag across `build` and `buildContribution` would make `ocx export` emit
+  `compat` while enable and refresh wrote a file without it.
+
+  **Slot: last, after `raycast`,** in both the union and the `EXPORT_CLIENTS`
+  object. `EXPORT_CLIENT_IDS` is `Object.keys(EXPORT_CLIENTS)`, so the object's
+  insertion order is the public order that three ordered assertions compare
+  against. The existing order is append-only landing order — `pi` is second and
+  `prime` eleventh — not a family grouping, so appending is the edit that leaves
+  the other thirteen positions untouched.
+
+`src/integrations/registry.ts`
+: `INTEGRATION_CLIENTS.omo` with `configPath` and `detectDir`. JSON, so no
+  `sourcePreservingYaml`; single-writer, so no `writerLock`; paths are a pure
+  function of env and home, so no `resolvePaths` and no `unresolvedPathHint`.
+  This matches `pi` and `prime` exactly.
+
+`src/cli/registry.ts`
+: the `export` entry's static usage string. Acceptance comes from
+  `EXPORT_CLIENT_IDS` through `isExportClientId`, so this is help text only —
+  but `tests/cli/cli-headless-parity.test.ts` reads it.
+
+`gui/src/…` and `gui/src/i18n/*`
+: the five lists the invariant compares, the two lists only the tab-coverage
+  test compares, the three exhaustive records the compiler forces, the mark
+  entry, the routing hash, and three keys in each of nine locales. `020`
+  enumerates them; they land here because of the binding above, not because wp3
+  was abandoned.
+
+`src/cli/help.ts`
+: the `(13 clients)` literal on line 84. Hand-written so `ocx --help` does not
+  import the export registry, and asserted in lockstep with
+  `EXPORT_CLIENT_IDS.length` by `tests/cli/cli-help.test.ts:79`.
+
+`src/integrations/catalog-refresh.ts`, `src/server/management/config-routes.ts`,
+`src/cli/dispatch.ts`
+: omo added to the three general owned-catalog fan-out lists, per the decision in
+  `002`. Not `src/cli/index.ts`, which is a Raycast-specific startup helper.
+  `tests/clients/sync-client-integrations.test.ts:68` pins one of those lists as
+  source text.
+
+## The detect directory question
+
+`detectDir` is the cheap "is this client installed at all" signal. For omo the
+honest directory is the agent directory itself rather than `~/.omo`: `~/.omo`
+exists on this machine carrying only `binary-runtime`, written by the v4 launcher
+wrapper, while `~/.omo/agent` does not exist yet. Detecting on `~/.omo` would
+report a v5 install that is not there. `agent-dir.js` creates the agent directory
+on first launch, so its presence is the fact we want.
+
+## Loopback-only
+
+`loopbackOnly: true`, on OMP's and Prime's grounds rather than Pi's and Aside's.
+
+The flag is a policy bit, not a schema observation: `isLoopbackOnly` is read by
+the writer, which refuses apply and refresh when the proxy is bound
+non-loopback. It does not block `ocx export` or `/api/client-config` for a
+Pi-family client.
+
+senpi's provider block *does* accept a `headers` map, so unlike Aside there is a
+place an `x-opencodex-api-key` could go. What does not exist is a builder that
+emits one — `buildPiClientConfig` writes no headers at all, which is why `pi`
+is loopback-only too. So the honest wording is deferred remote wiring, and
+`010` must not repeat Pi's "no header field" line, which `001` disproves.
+
+## Session affinity
+
+`buildPiClientConfig` takes a `sendSessionAffinityHeaders` flag. `pi` passes
+`true`; `prime` and `aside` leave it false. omo's value follows the same
+evidence rule: true only if senpi is verified to read `compat.sendSessionAffinityHeaders`.
+
+## Tests
+
+New: `tests/clients/omo-client.test.ts`, modeled on
+`tests/clients/raycast-client.test.ts` and the prime test before it — path
+precedence including the two inherited variables, relative-override refusal,
+emitted document shape, and the ownership stamp on the contribution.
+
+One assertion must **not** be copied from Prime.
+`tests/clients/prime-client.test.ts` asserts Prime's document carries no
+`compat` block. omo's asserts the opposite, the way the Pi case in
+`tests/config/client-config-export.test.ts` does, and it asserts it on both the
+`build` output and the contribution so the two cannot drift apart.
+
+Updated because they assert exact lists:
+`tests/config/client-config-export.test.ts` (ordered `EXPORT_CLIENT_IDS`),
+`tests/config/client-config-export-new-clients.test.ts` (loopback-only set),
+`tests/gui/integrations-invariants.test.ts` (client count and the
+`Record<IntegrationClientId, string>` seed, which forces an omo fixture in omo's
+own JSON shape), `tests/clients/integrations-state.test.ts` (loopback-only set),
+and the layout guards `scripts/test-layout/layout.json` plus
+`tests/fixtures/test-layout-expected.json` for the new file.
+
+## Focused test set for this phase
+
+`tests/clients/omo-client.test.ts`, `tests/config/client-config-export.test.ts`,
+`tests/config/client-config-export-new-clients.test.ts`,
+`tests/clients/integrations-state.test.ts`,
+`tests/clients/sync-client-integrations.test.ts`,
+`tests/cli/cli-help.test.ts`, `tests/gui/integrations-invariants.test.ts`,
+and the two layout guards.
+
+## Execution notes fixed at P
+
+**`omoAgentDir` semantics.** Three variables, in omo's order, each resolved the
+way `piAgentDir` resolves its one: `env.NAME?.trim()`, and a falsy result falls
+through to the next name. That reproduces `agent-dir.js`, which trims and then
+tests truthiness, so a variable set to the empty string or to whitespace is
+skipped rather than treated as a path. Each variable reports `ClientPathError`
+under **its own name** when it holds a relative path, because telling a user
+`PI_CODING_AGENT_DIR must be an absolute path` when they set
+`OMO_CODING_AGENT_DIR` is worse than no message.
+
+**The order matters and it is not cosmetic.** omo resolves its own variable
+first, so an opencodex that checked `PI_CODING_AGENT_DIR` first would write to a
+Pi directory omo will never read whenever a user has both set.
+
+**`sendSessionAffinityHeaders: true`.** The flag is not decoration: the
+generated provider tells the client to supply a stable session identity, from
+which opencodex derives canonical OpenCode Go affinity
+(`docs-site/.../guides/pi.md`). senpi validates the same `compat` key
+(`001`), so omo gets the same benefit pi does. `prime` and `aside` are left
+false because nobody verified their engines read it — that is an absence of
+evidence, not a decision to copy.
+
+**Slot.** `omo` goes last in `ExportClientId` and in `EXPORT_CLIENTS`, after
+`raycast`. The ordered assertion in `tests/config/client-config-export.test.ts`
+reads `Object.keys` order, and appending is the only edit that leaves the other
+thirteen positions untouched.
+
+**Layout.** The `clients` domain regex seeds only `^aside-profile(?!s-routes)`
+and `^(?:desktop|omp|pi|prime|remote|sync)-`, so `omo-client.test.ts` cannot be
+placed by pattern and needs the explicit entry in both tables.
diff --git a/devlog/_plan/260912_omo_client_integration/020_wp3_gui.md b/devlog/_plan/260912_omo_client_integration/020_wp3_gui.md
new file mode 100644
index 0000000000..74706af780
--- /dev/null
+++ b/devlog/_plan/260912_omo_client_integration/020_wp3_gui.md
@@ -0,0 +1,91 @@
+# wp3 — the Integrations page
+
+**Scope note after two audit rounds.** Everything above the line lands in wp2,
+not here. `tests/gui/integrations-invariants.test.ts` binds the GUI lists to the
+backend list; the locale keys are reached through `TKey` (`keyof typeof en`) at
+their use sites and every other catalog is a `Record<TKey, string>`, so a new key
+must exist in all nine locales to compile; and the GUI test literals and the two
+translation allowlists fail the moment the source lists move. This document is
+the map of those surfaces; wp2 executes all of it, including the test edits.
+
+wp3 keeps what genuinely cannot be done before the code exists: looking at it.
+
+The page the user named, `#integrations/`, reads five lists that are compared
+against `EXPORT_CLIENT_IDS` by `tests/gui/integrations-invariants.test.ts`, three
+exhaustive records the compiler forces, and two lists that are neither.
+
+## Compared against the backend list
+
+- `FILE_INTEGRATION_CLIENTS` in `gui/src/pages/integrations/integration-api.ts`
+  (the GUI's own list; `INTEGRATION_CLIENT_IDS` is the backend's, in
+  `src/integrations/registry.ts`)
+- `CLIENTS` in `gui/src/components/apikeys-workspace/client-config-clients.ts`
+- the keys of `CLIENT_LABEL_KEYS` in the same file
+- `FILE_INTEGRATION_CLIENTS`
+- the hashes in `INTEGRATION_TAB_HASHES`
+
+## Forced by typecheck
+
+- `FILE_LABEL_KEY` in `gui/src/pages/integrations/overview-clients.ts`
+- `SEMANTICS_KEY` and `TAB_LABEL_KEY` in `FileIntegrationPage.tsx`
+- `INTEGRATION_MARKS` in `gui/src/components/integration-marks.ts`, which is an
+  exhaustive `Record<OverviewClientId, string | null>` — so a new client cannot
+  reach the page without an explicit asset decision
+
+## The silent hazards
+
+`TABS` and `FILE_CLIENTS` in `gui/src/pages/integrations/integration-tabs.ts` are
+neither exhaustive records nor covered by the invariant test. Omitting omo from
+either leaves typecheck and the invariants green while the tab simply does not
+render — exactly the failure the user would see and we would not.
+`gui/tests/integrations-tab-coverage.test.ts` stands in that gap and must be
+confirmed still to do so.
+
+`gui/src/app-routing.ts` is not a third. `tests/gui/integrations-invariants.test.ts`
+already requires a routable hash per `EXPORT_CLIENT_IDS` entry, and the tab
+coverage test re-checks that every tab hash is routable. It still has to be
+edited; it just fails loudly rather than silently.
+
+## Mark
+
+`CLIENT_MARKS.omo` points at a first-party asset in
+`gui/public/provider-icons/`, with provenance recorded in that directory's
+`README.md` and in `003_brand_mark_provenance.md`. Membership in
+`MONOCHROME_CLIENT_MARKS` depends on the artwork having a single neutral ink:
+a single-ink mark is drawn as a themed mask so it does not vanish against one of
+the two themes, and a multi-ink or brand-colored mark stays an image so masking
+cannot flatten a palette or repaint a trademark.
+
+If omo publishes nothing usable, the honest outcome is `null` and the monogram
+tile — `integration-marks.test.ts` currently pins that no client is in that
+state, so the pin changes rather than a lookalike logo being invented.
+
+## i18n
+
+Three keys across nine locales (`en`, `de`, `fr`, `ja`, `ko`, `ru`, `tr`, `zh`,
+`zh-TW`): `integrations.tab.omo`, `integrations.semantics.omo`,
+`api.clientConfig.clientOmo`.
+
+"omo" is a product name and stays untranslated, which means adding the tab and
+client keys to `ZH_TW_KEEP_ENGLISH` in `gui/tests/locale-parity.test.ts` and
+`INTENTIONAL_ENGLISH` in `gui/tests/fr-localization.test.ts`. The semantics
+string is prose and is translated in all nine.
+
+## GUI tests to update
+
+`gui/tests/client-config-panel.test.tsx`, `gui/tests/integrations-api.test.ts`,
+`gui/tests/integrations-overview-rows.test.ts`, `gui/tests/integration-marks.test.ts`,
+`gui/tests/client-marks-assets.test.ts`, `gui/tests/locale-parity.test.ts`,
+`gui/tests/fr-localization.test.ts`, `gui/tests/integrations-tab-coverage.test.ts`.
+
+---
+
+## What wp3 still owns
+
+- Building this worktree's GUI and serving it, rather than reading whatever build
+  the long-running proxy already has.
+- Confirming the row, the tab and the mark actually render — the mark as the omo
+  face rather than a filled plate, at the size the row draws it.
+- Copy-editing `integrations.semantics.omo` against what the page shows. wp2
+  writes the string; wp3 is where it gets read in place and fixed if it reads
+  badly beside its thirteen neighbours.
diff --git a/devlog/_plan/260912_omo_client_integration/030_wp4_docs.md b/devlog/_plan/260912_omo_client_integration/030_wp4_docs.md
new file mode 100644
index 0000000000..48b4b0a3ae
--- /dev/null
+++ b/devlog/_plan/260912_omo_client_integration/030_wp4_docs.md
@@ -0,0 +1,19 @@
+# wp4 — documentation
+
+Two pages carry the client list, and both have translated copies that commit
+`42adf4996` established are synchronized rather than allowed to drift.
+
+`docs-site/src/content/docs/reference/cli/agents.md`
+: the `--client` union, the flag table, and the destination table. Translated
+  copies exist under `fr`, `ja`, `ko`, `ru`, `tr`, `zh-cn`, `zh-tw`.
+
+`docs-site/src/content/docs/guides/integrations.md`
+: the client table. Translated copies exist under `fr`, `tr`, `zh-tw`.
+
+The omo row names the destination `~/.omo/agent/models.json`, the download
+filename `omo-models.json`, and the loopback-only stance with its reason, in the
+same voice the neighbouring rows use.
+
+The Aside unit found the integrations guide missing a `zcode` row. wp4 re-checks
+that every registered client is present in both tables before adding omo, so a
+new row does not land next to a known hole.
diff --git a/devlog/_plan/260912_omo_client_integration/040_wp5_verification.md b/devlog/_plan/260912_omo_client_integration/040_wp5_verification.md
new file mode 100644
index 0000000000..e9a1956048
--- /dev/null
+++ b/devlog/_plan/260912_omo_client_integration/040_wp5_verification.md
@@ -0,0 +1,25 @@
+# wp5 — what counts as proof
+
+The goalplan's five criteria, and the evidence each one accepts.
+
+1. **The page shows it.** Not "the list contains omo" — a dashboard rendering an
+   omo row in the overview grid and an omo tab that opens `integrations/omo`,
+   captured from **this worktree's** built GUI rather than whatever build the
+   long-running proxy on `:10100` happens to be serving. The silent hazard in
+   `020` is precisely the failure that passes every other check, so a
+   source-level assertion cannot discharge this one.
+2. **The bytes are right.** `ocx export --client omo` emitting a document whose
+   provider block matches what senpi parses, naming the path
+   `omoConfigPath` resolves. Evidence is the emitted text plus the senpi parser
+   citation in `001`.
+3. **`bun run typecheck`** clean.
+4. **Focused tests.** The new omo test plus every exact-list test named in
+   `010` and `020`, run by path — including `tests/cli/cli-help.test.ts`, which
+   is the only thing that catches a stale `(13 clients)` literal. The full suite
+   is the PR gate, not this one.
+5. **Round trip.** Enable then disable omo through the integrations API against
+   a temporary home, and show the config file returns to its prior bytes — the
+   ownership claim, not just the write.
+
+Anything short of these is reported as it is. A rendered page is not inferred
+from a green test, and a green test is not inferred from a compiling record.
diff --git a/devlog/_plan/260912_omo_client_integration/050_wp6_gjc_rename.md b/devlog/_plan/260912_omo_client_integration/050_wp6_gjc_rename.md
new file mode 100644
index 0000000000..1b96990ade
--- /dev/null
+++ b/devlog/_plan/260912_omo_client_integration/050_wp6_gjc_rename.md
@@ -0,0 +1,67 @@
+# wp6 — Gajae Code reads as gjc
+
+The product shortened its name. The repository is `Yeachan-Heo/gajae-code`, the
+published package is `@gajae-code/coding-agent`, the command is `gjc`, and the
+config path this repo already writes is `~/.gjc/agent/models.yml` — the path
+rebranded before the label did, which is why "Gajae Code" now sits next to a
+`.gjc` directory in the same docs table.
+
+## The line this phase does not cross
+
+The client **id** stays `gajae`. It is not a caption: it is the key in
+`EXPORT_CLIENTS` and `INTEGRATION_CLIENTS`, the segment in
+`/api/client-integrations/gajae`, and the key an enable record is stored under.
+Renaming it orphans the stored state of every user who already connected the
+client — the integration silently reads "not applied", and the ownership record
+no longer matches the block we wrote into their config, so a later disable can
+no longer remove it cleanly. The user was asked and chose label-only.
+
+`OPENCODEX_GAJAE_API_KEY` stays for the same reason: it is a variable a user has
+already exported, and renaming it breaks a working setup silently.
+
+## Surfaces that change
+
+| file | from | to |
+|---|---|---|
+| `gui/src/i18n/*.ts` × 9, `integrations.tab.gajae` | `Gajae Code` | `gjc` |
+| `gui/src/i18n/*.ts` × 9, `api.clientConfig.clientGajae` | `Gajae Code` | `gjc` |
+| `src/cli/registry.ts` export summary | `Gajae Code` | `gjc` |
+| `docs-site/.../guides/integrations.md` + translations | `Gajae Code` rows and prose | `gjc` |
+| `docs-site/.../reference/cli/agents.md` + translations | `Gajae`/`Gajae Code` prose | `gjc` |
+| `docs-site/.../reference/configuration.md` + translations | `Gajae` in the Fast-rows client list | `gjc` |
+
+`gjc` is a product name, so it stays untranslated in all nine locales, which
+means the two keys keep their places in `ZH_TW_KEEP_ENGLISH` and
+`INTENTIONAL_ENGLISH` — they were already there under the old spelling, so this
+is a value change, not a list change.
+
+## What proves it
+
+No test asserts the literal `Gajae Code`, and the two translation allowlists key
+on key *names*, not values, so changing the value needs no list edit. The label
+is never derived from the id — every surface reaches it through an i18n key — so
+the two can honestly disagree.
+
+The proof is `rg -n "Gajae"` restricted to **user-visible text**: the nine locale
+catalogs, the CLI summary prose, and `docs-site`. A bare tree-wide search is the
+wrong check and would report itself failing forever, because the internal
+identifiers (`GajaeGeneratedConfig`, `gajaeConfigPath`, `buildGajaeClientConfig`,
+`OPENCODEX_GAJAE_API_KEY`) are exactly what this phase is not touching.
+
+## Verified after merge
+
+An independent audit read `origin/dev` and ran that check against what actually
+landed: zero `Gajae Code` across the nine locale catalogs, `src/cli/registry.ts`
+and `docs-site`. Every surviving `Gajae` is an identifier, the
+`OPENCODEX_GAJAE_API_KEY` env var, an i18n key *name* whose value is now `gjc`,
+an internal type, or a comment. The line this phase promised not to cross held:
+the client id is still `gajae`, the config path is still `~/.gjc/agent/models.yml`,
+the route is still `/api/client-integrations/gajae`, the download filename is
+still `gajae-models.yaml`, and the tab hash is still `integrations/gajae`. So an
+install that had already connected the client keeps resolving its stored enable
+record, which is the whole reason the id stayed put.
+
+The audit did find one mention this plan had missed: the header comment in
+`src/cli/export-command.ts` still said "Eight clients" and listed `Gajae` among
+the YAML dialects. It was stale on both counts — there were thirteen clients
+before omo — and it is corrected alongside the outcome note.
diff --git a/devlog/_plan/260912_omo_client_integration/060_wp3_rendered_proof.md b/devlog/_plan/260912_omo_client_integration/060_wp3_rendered_proof.md
new file mode 100644
index 0000000000..a66b407c54
--- /dev/null
+++ b/devlog/_plan/260912_omo_client_integration/060_wp3_rendered_proof.md
@@ -0,0 +1,75 @@
+# wp3 — what the page actually showed
+
+Built `gui/dist` from this worktree and served it from a proxy on port 10177.
+
+## The environment mistake, recorded because it cost something
+
+The first attempt ran `ocx start` with only `OPENCODEX_HOME` redirected. That is
+not isolation: `start` also syncs the Codex catalog and the Grok Build config,
+both of which resolve from the real home. It rewrote
+`~/.codex/opencodex-catalog.json` and pointed `~/.grok/config.toml` at port
+10177, which is a dead port the moment the test proxy stops.
+
+Both were restored: `ocx sync` against the live installation rebuilt the Codex
+catalog (29 models), and the Grok base URL was put back to 10100. A diff with
+the port normalised on both sides confirmed the port was the only difference.
+
+The second attempt redirected `HOME` and `CODEX_HOME` as well. The reviewer
+argued for keeping the real `HOME` instead, so the badge would act as an oracle
+against the machine's real `~/.omo`. That is rebutted rather than ignored: the
+condition under test is a `.omo` directory containing only `binary-runtime` and
+no `agent/`, and that condition was reproduced exactly inside the isolated home.
+It tests the same thing without a second chance to damage the user's setup.
+
+That the three agent-dir variables were unset is not asserted, it is visible:
+the page printed `/tmp/omo-vh/.omo/agent/models.json`, which is the
+home-relative default. Any of the three being set would have shown its value.
+
+## The oracle, pinned before the screenshot
+
+Muted **Not installed**, the literal config path, Apply **disabled**. "Not
+applied" or an enabled switch would mean `detectDir` had matched the bare
+`.omo` directory.
+
+## What was observed
+
+| check | result |
+|---|---|
+| omo tab in the strip, routing to `integrations/omo` | present, selectable, reachable |
+| overview row, `data-client="omo"` | present, last in the grid |
+| `.omo` holding only `binary-runtime`, no `agent/` | **Not installed**, Apply disabled — the v4 false positive is rejected |
+| `.omo/agent` created | flips to **Not applied**, Apply enabled |
+| Apply toggled | wrote `models.json`: `providers.opencodex` with `baseUrl`, `api: openai-completions`, the loopback placeholder, `compat.sendSessionAffinityHeaders: true`, and `models` as a 12-element array |
+| the written file, through senpi's own compiled validator | **valid: true** |
+| negative control, `input: ["audio"]` | valid: false |
+| negative control, `models` as a keyed object | valid: false |
+| Disable toggled | file returns to `{}` — only our block removed |
+| mark | `<img src="/provider-icons/omo.svg"`>, `mask-image: none`, at 14px (tab), 20px (row) and 24px (page); no monogram anywhere |
+| mark in dark and light themes | the dark face carries it on both surfaces; it is not a blank plate |
+| API Keys tab, the client-config row | `omo` label present, same unmodified 20px `<img>` mark |
+| both `integrations-tab-omo` and `integrations-tab-raycast` measured | non-zero box, top >= 0 — the tab is reachable in a twenty-tab strip, not merely in the DOM |
+
+The validator run is the one that matters most, because it is the difference
+between "the bytes look like Pi's" and "the engine omo actually ships accepts
+this file". The two negative controls are there so the check cannot be vacuous —
+a validator that returns true for everything would have passed them too.
+
+The last two rows close the reviewer's remaining non-blocking notes. The API
+Keys row matters because it is a second surface reading the same
+`CLIENT_MARKS.omo`, and it is reached through `CLIENTS` rather than through
+`FILE_INTEGRATION_CLIENTS` — a different list, so a different way to be missing.
+Tab reachability was measured rather than eyeballed, because "present in the
+DOM" and "the user can get to it" are not the same claim once a strip holds
+twenty tabs.
+
+## Semantics copy, read in place
+
+`integrations.semantics.omo` wraps to three lines where Prime's wraps to two,
+because it names three environment variables instead of one. Kept as is: the
+three names are the fact a user needs when omo and Pi can resolve the same file,
+and shortening it would mean dropping two of them.
+
+## Cleanup
+
+The test proxy is stopped and `/tmp/omo-vh`, `/tmp/omo-ocxhome` hold everything
+it wrote. Nothing under the user's home carries state from this run.
diff --git a/devlog/_plan/260912_omo_client_integration/090_outcome.md b/devlog/_plan/260912_omo_client_integration/090_outcome.md
new file mode 100644
index 0000000000..0afa6f993b
--- /dev/null
+++ b/devlog/_plan/260912_omo_client_integration/090_outcome.md
@@ -0,0 +1,65 @@
+# Outcome
+
+Shipped as PR #4290, merged into `dev` on 2026-09-12 as `eb314c53a0` at head
+`9689ee8ceb0d868faa0643b036f8e8d9be4bd03c`. CI on that exact head: 25 pass, 0
+fail, 2 conditional jobs skipped. Merged under the `MAINTAINERS.md` dev-only
+maintainer-integration exception, with the decision and CI evidence recorded on
+the PR.
+
+## What landed
+
+`omo` is the fourteenth export and file-integration client. It reuses the Pi
+builder, opted into session affinity, resolves `~/.omo/agent/models.json` under
+omo's own three-variable precedence, detects on the agent directory, and is
+loopback-only by deferral. `Gajae Code` now reads `gjc` everywhere a user looks,
+with the id, config path, API route and env var deliberately unchanged.
+
+## The evidence that mattered
+
+Three claims could not have been settled by inspection, and each was checked:
+
+1. **senpi accepts the Pi document.** The file a live Apply actually wrote
+   returned true from senpi's own compiled `validateModelsConfig`, while an
+   `audio` input modality and a keyed `models` object both returned false, so
+   the check could not be vacuous.
+2. **The v4 false positive is rejected.** With `~/.omo` holding only
+   `binary-runtime` and no `agent/` — the exact state of the machine this was
+   built on — the row reads *Not installed* with Apply disabled, and creating
+   `~/.omo/agent` flips it to *Not applied*.
+3. **The page renders.** Tab, row and mark captured from the built GUI;
+   `evidence/integrations-omo-tab.png`.
+
+## What the process caught
+
+Four independent audit rounds returned FAIL or NEAR-PASS and changed the work:
+
+- The backend/GUI split was abandoned after two rounds proved no ordering of
+  the halves leaves `tests/gui/integrations-invariants.test.ts` green.
+- `omo` moved to the end of `EXPORT_CLIENTS` rather than beside `prime`, because
+  `EXPORT_CLIENT_IDS` is `Object.keys` order and three tests assert it exactly.
+- `buildOmoContribution` gained the session-affinity flag, which `build` already
+  had; without it `ocx export` and an enabled integration would have written
+  different documents.
+- The catalog-refresh decision was forced to confront four disagreeing fan-out
+  lists instead of the one the checklist named.
+
+Two mistakes are worth keeping visible. The first attempt at the rendered proof
+ran `ocx start` with only `OPENCODEX_HOME` redirected, which is not isolation —
+it rewrote the user's real Codex catalog and pointed `~/.grok/config.toml` at a
+port that was about to die. Both were restored and the second attempt redirected
+`HOME` and `CODEX_HOME` too. And `privacy:scan` passed locally while failing on
+three CI jobs, because the file it objected to was still untracked when the
+local scan ran.
+
+## Left open
+
+- `docs-site/.../zh-tw/reference/management-api.md` lists the
+  `GET /api/client-config` clients only as far as `dsh`. That list already
+  omitted `zcode`, `prime`, `aside` and `raycast` before omo existed, so it is a
+  pre-existing translation gap rather than this unit's debt; widening it quietly
+  here would hide it.
+- `prime` is in none of the catalog-refresh fan-outs. That looks like an
+  oversight from when it landed, and is recorded in `002` so the next person
+  does not read it as a pattern to copy.
+- No CI check compares the docs client tables against `EXPORT_CLIENT_IDS`, so
+  the docs rows stay guarded by review alone.
diff --git a/devlog/_plan/260912_omo_client_integration/evidence/integrations-omo-tab.png b/devlog/_plan/260912_omo_client_integration/evidence/integrations-omo-tab.png
new file mode 100644
index 0000000000..36f9809e12
Binary files /dev/null and b/devlog/_plan/260912_omo_client_integration/evidence/integrations-omo-tab.png differ
diff --git a/devlog/_plan/260912_operations/000_plan.md b/devlog/_plan/260912_operations/000_plan.md
new file mode 100644
index 0000000000..f8ad96b84b
--- /dev/null
+++ b/devlog/_plan/260912_operations/000_plan.md
@@ -0,0 +1,34 @@
+# Operations delivery roadmap
+
+Operators need accurate startup failures, safe update retry cleanup, readable usage, and actionable connected-client guidance. This unit carries the remaining reviewed contributions and repairs their current callers. The original stop-refusal implementation is already present on dev; it is not applied twice.
+
+Loop: satisfy-spec HOTL, triggered by the operations lane assignment. Goal: reviewable PRs with final-tip hosted evidence and a durable handoff. Non-goals: merging, closing originals, releases, live service/config changes, local product suites/build/typecheck/install. Scope: this managed worktree and explicitly authorized GitHub PR writes; existing credentials only. No user token/time/agent-count cap. Stop only after every disposition, acceptance row and final-tip result is recorded, or an actual unavailable external gate is documented. Memory artifact: this unit and ignored .tmp/operations/handoff.md. Escalation: real tool/access denial or scope beyond assigned issues; main owns code and decisions. Native architect role is unavailable; supported inherited design reviews plus separate A audits follow explicit user direction.
+
+## Work-phase map
+
+| ID | Document | Outcome | Dependency |
+| --- | --- | --- | --- |
+| roadmap | 000 + all decade docs | Docs-only source-grounded roadmap | none |
+| update | 010_update.md | Retire observed exited pinned children (#4185) | roadmap |
+| listeners | 020_listeners.md | Name auxiliary bind failures and malformed edits (#4236 residual) | roadmap |
+| totals | 030_totals.md | Keep readable usage and disclose omissions (#4111) | roadmap |
+| client-usage | 040_client_usage.md | Hub usage scoped to connected client (#4205) | roadmap; preserve totals contract if shared |
+| pairing | 050_pairing.md | Hub identity and origin-specific browser authentication (#4206/#4208) | roadmap |
+| transport | 060_transport.md | Reviewed local management catalog read (#4315/#4317) | roadmap |
+| verification | 070_verification.md | Exact tips, hosted results, credits, handoff | all implementations |
+
+Independent changes use independent branches/PRs from the fetched dev baseline plus the common roadmap checkpoint. Only actual shared-code dependencies become an ordinary manual chain. No native stack registration. Intermediate auto-CI stays enabled; final cumulative tips are the acceptance unit.
+
+## Source disposition
+
+- #4170 OPEN at 4d72ef010363b80cd78f65148a5228d6797a3117, but dev contains 1ada8f5ff1 and further refusalNextStep behavior in src/lib/process-control.ts. No duplicate carry. Missing-message incident and actual scheduler behavior are not proven resolved by wording.
+- #4185 OPEN at 2602f3ceca4b93237436911dcd8dffc35b3b5e57; current src/update/job.ts still uses lastChild.pid alone.
+- #4111 OPEN at 2f07acb58b3e73f48cea38334f301b430a8634cd. Readable totals differ from connected-client routing.
+- #4317 OPEN / CHANGES_REQUESTED at 27f577aa795f3b968c070a50eded48411bd7e985. Independent security review and own caller-complete patch required. Sensitive analysis stays in ignored scratch.
+- #4236 latest public comment identifies only auxiliary listener bind diagnosis and malformed edit reporting as outstanding. #4249/#4250/#4251/#4252/#4254/#4255 are already landed and must not be replayed.
+
+## Evidence policy
+
+Local suites of every size, typecheck, builds and install: NOT RUN by explicit user instruction. Regression code goes to GitHub-hosted Cross-platform CI, whose pull_request trigger has no base filter (.github/workflows/ci.yml:3). Docs consistency uses git diff --check and file-map inspection, not claimed test coverage. Source review is not execution. Each final source SHA is paired with its actual run ID/URL/conclusion; skipped/cancelled runs are not passing proof. Every C/D records this limitation and defers behavioral acceptance to final hosted results.
+
+Existing tree conventions: src/cli owns commands, src/server owns listener/management boundaries, src/update owns update retries, gui/src owns React presentation, tests mirrors domains, structure/manifest.json maps owning docs. No new dependencies, service layer, or settings are needed.
diff --git a/devlog/_plan/260912_operations/001_roadmap_audit.md b/devlog/_plan/260912_operations/001_roadmap_audit.md
new file mode 100644
index 0000000000..d99db8768d
--- /dev/null
+++ b/devlog/_plan/260912_operations/001_roadmap_audit.md
@@ -0,0 +1,7 @@
+# Roadmap audit outcome
+
+Independent design reviewers accepted the update, listener, usage, pairing and local-catalog designs after reflection. Native architect selection was unavailable; user-directed inherited model review was used without a native-role claim. Two reflection calls initially reported model capacity errors; same-handle retries completed.
+
+Independent A reviewer identified nested managementIngress degradation hidden by schema catch and an incomplete CLI regression path. Both were folded in and re-audited. Final verdict: GO-WITH-FIXES (blockers=0); remaining deps.managementOrigin wording corrected before lock. This audit certifies the plan only, not implementation or test behavior.
+
+The first cycle is docs-only. All eight roadmap files exist, source/test paths were reviewed, and git diff --cached --check exits zero. Product suites/build/typecheck/install NOT RUN by explicit instruction. Next direction: implement the observed-child cleanup slice from 010, then the independent listener slice. Final-tip hosted CI owns behavior acceptance. No retired update architecture or already-carried stop implementation is replayed.
diff --git a/devlog/_plan/260912_operations/010_update.md b/devlog/_plan/260912_operations/010_update.md
new file mode 100644
index 0000000000..29a7cffd4d
--- /dev/null
+++ b/devlog/_plan/260912_operations/010_update.md
@@ -0,0 +1,13 @@
+# Pinned child retirement
+
+Class C4: process termination boundary. Dependency: roadmap. Reuse the existing RestartIo and restartAfterUpdate retry loop; no new process supervisor.
+
+MODIFY src/update/job.ts: RestartIo gains injectable spawnDetachedStartFn, preparePortForPinnedStartFn, waitForGhostListenClearFn and killProxyFn, matching existing functions. Replace Date.now in the pinned retry window with existing io.now. Replace both lastChild.pid-only kills with one closure accepting the ChildProcess: return when pid absent, exitCode non-null, or signalCode non-null; otherwise existing isAlive then kill. Capture the exact spawned child and attach once(exit) to clear lastChild only when lastChild === child. Keep healthy-probe early return. No persisted schema or serialization changes; these are process-local IO seams consumed in the retry loop only.
+
+MODIFY tests/update/update-job.test.ts: carry #4185 deterministic fake EventEmitter children through actual three retries, using injected clock and no real kill. Cases: successful exit, nonzero exit, signal exit, event retirement, live timeout cleanup, same-PID late old event, healthy last attempt. MODIFY tests/windows/windows-deploy-close-regressions.test.ts: replace obsolete exact PID-expression oracle with reference to behavior regression; keep wrapper ownership assertions. MODIFY structure/runtime.md to state observed-child retirement. Existing process code is otherwise unchanged.
+
+Exact starting patch: public PR #4185 head 2602f3ceca4b93237436911dcd8dffc35b3b5e57, reviewed source diff retained locally in .tmp/operations/pr-4185.diff. Before: numeric PID may remain after child exit. After: recorded exit/signal or matching exit event retires cleanup authority. This does not make all OS signalling atomic against PID reuse.
+
+Planned hosted activation checks (not yet executed): seven tests in update/update-job.test.ts exercise both cleanup sites. Local execution NOT RUN. Source check: both sites use the same child-aware closure; no unrelated test weakened. Co-authored-by: luvs01 <27862058+luvs01@users.noreply.github.com>.
+
+Follow-up080 extends exact-child retirement to error/close/exit and releases its own handlers; failed spawn error+close without exit is covered separately. Local tests remain NOT RUN.
diff --git a/devlog/_plan/260912_operations/020_listeners.md b/devlog/_plan/260912_operations/020_listeners.md
new file mode 100644
index 0000000000..393ba74e8a
--- /dev/null
+++ b/devlog/_plan/260912_operations/020_listeners.md
@@ -0,0 +1,13 @@
+# Auxiliary bind diagnosis and malformed edit reporting
+
+Class C3; dependency roadmap. Existing owners: src/server/ports.ts: isAddrInUse, src/server/index.ts: startup transaction, src/cli/index.ts: handleStart retry loop, src/config.ts: loadConfig warnings.
+
+MODIFY src/server/ports.ts: add AuxiliaryListenerBindError carrying listener name (unauthenticatedLoopbackListener or hub.managementIngress), port, hostname and original cause. Its message names the precise config key/address and directs correction of that effective auxiliary address (including a port-less companion). MODIFY src/server/index.ts: keep synchronous rollback of opened listeners, wrap only each auxiliary Bun.serve failure after rollback. MODIFY src/cli/index.ts: reject AuxiliaryListenerBindError before generic isAddrInUse retry logic. Public-listener EADDRINUSE retains soft/hard-pin behavior; auxiliary collisions never re-pick the public port. Fields are transient Error data, created by both auxiliary catches, consumed by CLI; no serialization.
+
+MODIFY src/config.ts: reuse load-time degraded-field warning family. When raw unauthenticatedLoopbackListener is present and validated value disappeared, emit field-specific warning without raw values; keep valid providers/keys and file bytes. The same pure warning is exposed by validFileConfigDiagnostics, so doctor/status also report degradation. Existing write-time loopbackListenerPortError stays strict. Whole-hub malformed blocks already warn, but nested hub.managementIngress can be silently swallowed before that check. Add a raw-versus-validated nested-ingress warning to the same owner and diagnostics. Cover string enabled and invalid port for BOTH listener blocks, preserving providers/file bytes.
+
+MODIFY existing tests/server/ports.test.ts and tests/server/loopback-listener-integration.test.ts : occupied loopback and management ports must report their config key and actual port, preserve cause and release every successful bind; non-EADDRINUSE errors identify bind failure without claiming the port is busy. Public conflict remains classified normally. Extend tests/config/config-load-degrade.test.ts and tests/server/loopback-listener-admission.test.ts with string enabled and out-of-range port: warning present, provider preserved, file unchanged. No local socket or service operation: tests only written, run remotely.
+
+MODIFY directly relevant structure/runtime.md, structure/config.md, structure/ops/service-and-sidecars.md and public hub/loopback guidance; link the canonical contract from other mapped ownership docs only where applicable. Review all conditional activation rows on hosted CI. Source inspection is not runtime proof.
+
+Design OPS-LIST-01..04 accepted with amendments. NEW tests/cli/cli-start-auxiliary-bind.test.ts, registered in both test-layout files, uses isolated CLI subprocess to cover soft and hard-pinned startup: failure names auxiliary key/address, exit nonzero, no public repick/wait branch. Existing management rollback fixture occupies management first then selects distinct public/loopback ports. Warning helper runs on all three load return paths plus read-only diagnostics; controls cover absent and valid-disabled entries and malformed secret-shaped input without echoing raw values.
diff --git a/devlog/_plan/260912_operations/030_totals.md b/devlog/_plan/260912_operations/030_totals.md
new file mode 100644
index 0000000000..71d2615772
--- /dev/null
+++ b/devlog/_plan/260912_operations/030_totals.md
@@ -0,0 +1,11 @@
+# Readable usage totals with explicit omissions
+
+Class C3; dependency roadmap. Adopt public #4111 final diff (2f07acb58b3e73f48cea38334f301b430a8634cd) after current-base and latest-review audit; preserve luvs01 credit. Source diff and metadata are in ignored .tmp/operations/pr-4111.diff/json, fetched directly from GitHub.
+
+MODIFY src/server/management/usage-aggregate-cache.ts: replace four oversizedRows throws with retained usageIncomplete boolean, set on full scan, OR on append, preserve in resultFrom; cache API-key snapshots with diagnostic. MODIFY api-key-usage.ts: keep readable accumulator output and attach usageIncomplete:true / usageIncompleteReason:oversized_rows instead of throwing. MODIFY logs-usage-routes.ts: serialize diagnostics on filtered and unfiltered summaries. MODIFY usage-summary-cache.ts CachedUsageSummary and oauth-account-routes.ts GET /api/keys to retain/serialize flags. Other IO/mutation errors still fail.
+
+MODIFY src/cli/usage-report.ts: warnings precede totals/no-match branch; incomplete no-match says skipped records may match. MODIFY gui/src/usage-summary-resource.ts shared optional diagnostic type; NEW components/usage-incomplete-notice.tsx; extend consumers Usage, dashboard overview, Models, AddProviderModal, ProviderWorkspaceShell, ApiKeysWorkspace/ListPanel and ApiKeys. Incomplete keys do not claim inactivity; warnings survive consumer caching. Add all locale keys. Full field chain: scanner oversizedRows -> retained aggregate boolean/API key snapshot -> route JSON/cache -> shared GUI/CLI input types -> every totals/ranking/key activity consumer.
+
+MODIFY existing tests/cli/cli-usage-report.test.ts, tests/server/api-usage.test.ts, tests/server/api-key-attribution.test.ts, tests/usage/usage-aggregate-cache.test.ts and GUI usage/custom-range/model-picker/key-workspace tests; NEW gui/tests/usage-incomplete-consumers.test.tsx. Activation: good + oversized + good rows yields readable sums and warning; append oversized sticky flag, full clean rewrite clears it, missing filter matches stays uncertain, loading/stale consumers retain warning. Do not turn IO errors into zero totals.
+
+MODIFY structure/gui-and-management-api.md and relevant mapped contract pointers; public management API, CLI agents and web-dashboard guides in all existing translated paths from original diff. Hosted full CI and dashboard evidence certify final tip; local suites/build/typecheck NOT RUN. This does not implement hub client-scoped CLI usage (#4205).
diff --git a/devlog/_plan/260912_operations/040_client_usage.md b/devlog/_plan/260912_operations/040_client_usage.md
new file mode 100644
index 0000000000..389c303f8b
--- /dev/null
+++ b/devlog/_plan/260912_operations/040_client_usage.md
@@ -0,0 +1,13 @@
+# Connected client usage
+
+Class C4 for credential scope; dependency roadmap and only shared usage contract if needed. Existing src/cli/observe.ts:155 usage currently calls runtimeRequest('/api/usage'), whose owner src/cli/runtime-api.ts always resolves a local endpoint. Connected machine listener does not expose that route.
+
+MODIFY observe.ts usage dispatch to inspect existing client connection state before choosing the endpoint; standalone keeps runtimeRequest unchanged. Reuse the existing client-to-hub request owner and add a dedicated client-authenticated /v1/usage read, with only the enrolled client credential. Fail closed on invalid/mismatched state. Retain range/surface/provider/model and inclusive custom-window options, JSON versus human output, endpoint error messages and hub key scope. Do not send the local admin token to the hub or expose global management usage. If the existing hub endpoint supports fewer selectors, reject unsupported options explicitly until it is extended with the same authenticated scope.
+
+MODIFY existing client/hub API owner only where the read contract requires it; extend CLI usage and hub admission regression owners. Activation: connected client succeeds with own-key data despite local /api/usage absence; second client data excluded; revoked/bad credentials refuse; standalone still uses local management; custom-window contract preserved. Exact file map: NEW src/server/hub-usage.ts route handler and src/remote/hub-usage.ts shared response contract; MODIFY src/server/index.ts dispatch near /v1/models, src/server/auth-cors.ts configured-key identity resolver, src/client/hub-client.ts authenticated client read, src/cli/observe.ts usage dispatch, src/cli/usage-report.ts source/scope label. The route requires explicit configured-key admission even on loopback, derives apiKeyId from that identity, rejects caller-selected key IDs, uses filtered aggregation and no hub-wide summary cache. It omits private account attribution from the client DTO. Authentication/route enforcement tier: server code; caller-selected IDs cannot override the authenticated key; local admin/host control remains a residual outside client isolation. Final layer: server authorization. No claim of protection against the host owner. No local credential provisioning or running client changes.
+
+MODIFY public connected-client/CLI usage guide and structure/runtime.md / gui-and-management-api.md canonical scope. Any pre-disclosure details stay in scratch. Hosted regressions only; local execution NOT RUN.
+
+Accepted design OPS-USAGE-02/03/04. NEW tests/server/hub-usage.test.ts and tests/clients/hub-usage.test.ts with entries in scripts/test-layout/layout.json explicit and tests/fixtures/test-layout-expected.json; NEW tests/cli/cli-usage-hub.test.ts. Tests use two client keys, loopback and remote admissions, invalid state, custom window, unsupported endpoint, bad response, expired/revoked credentials. Full implementation follows source confirmation before B.
+
+Reflection amendments: getFilteredUsageAggregate in src/server/management/usage-aggregate-cache.ts is the aggregation owner. Client DTO preserves #4111 incomplete flags; CLI suppresses advice to remove filters for account totals because that scope never exports accounts. Public files: docs-site/src/content/docs/guides/remote-hub.md and reference/cli/agents.md. All three new tests register in scripts/test-layout/layout.json and tests/fixtures/test-layout-expected.json.
diff --git a/devlog/_plan/260912_operations/050_pairing.md b/devlog/_plan/260912_operations/050_pairing.md
new file mode 100644
index 0000000000..2b05bff2ba
--- /dev/null
+++ b/devlog/_plan/260912_operations/050_pairing.md
@@ -0,0 +1,13 @@
+# Pending browser authentication guidance
+
+Class C3; dependency roadmap. Reuse existing connected-client state and browser-auth components. Target #4206 and #4208 together because both concern the same pending local-dashboard pairing journey.
+
+MODIFY owning dashboard pending-auth component and bootstrap state: distinguish a reachable connected machine awaiting hub browser authentication from a stopped standalone proxy. Show configured hub identity/origin, explain that machine enrollment and browser session are separate, offer the current origin-specific existing pairing/authentication action. Preserve revoked/expired/unreachable states and their existing retry actions; do not suggest ocx start while the local runtime is reachable. Derive the next action from current origin + configured hub instead of a hardcoded localhost URL. No credentials appear in visible copy/URLs.
+
+MODIFY all gui/src/i18n locale dictionaries with meaningful labels. Extend existing pending-auth/dashboard tests for local origin, remote hub origin, pending, authenticated, expired/revoked and unavailable standalone; positive browser auth transitions into connected dashboard. Exact files: gui/src/App.tsx, api.ts, pages/dashboard-core-poll.ts, pages/use-dashboard-data.ts and pages/Dashboard.tsx consume a classified authentication/error state instead of a boolean. Existing connect-pairing.ts and connect-pairing-transport.ts own hub identity and origin-specific action. Define the error classification in api.ts at response ingress; consume in polling and Dashboard; reset on authenticated success and pairing completion. No persistence/serialization for this UI state. Keep cached data with stale labeling when auth fails; do not erase a known hub into standalone offline. Public hub/browser-pairing guidance is updated with the same distinction. No service restart or live auth reconfiguration.
+
+Hosted component suite and screenshot artifact of the rendered pending state required for final delivery; local GUI tests/build NOT RUN. Static source or mockup is not rendered application evidence.
+
+Accepted OPS-PAIR-01/02. Cases include browser session expiry and post-pairing refresh, local and hub origin guidance, code versus API/admin-key explanation, and operator handoff text. Prefer existing component tests; new test files only where needed.
+
+Reflection amendments: reuse existing api.ts SESSION_UNAVAILABLE_EVENT and App sharedSessionReady; subscribe in App, emit on terminal 401 expiry (not aborted requests), reset/read refresh on successful pairing. Do not create duplicate auth state. Poll classification and pairing errors distinguish HTTP auth refusal, transport/network, and invalid responses; aborted work does not show a failure.
diff --git a/devlog/_plan/260912_operations/060_transport.md b/devlog/_plan/260912_operations/060_transport.md
new file mode 100644
index 0000000000..a884509d22
--- /dev/null
+++ b/devlog/_plan/260912_operations/060_transport.md
@@ -0,0 +1,7 @@
+# Local management catalog read
+
+Class C4; dependency roadmap. Scope #4315 and the current CHANGES_REQUESTED review on #4317. Public source starting points: src/cli/opencode.ts fetchOpencodeProxyModels/cmdOpencode, src/lib/admin-secrets.ts, src/lib/local-destinations.ts, associated providers/opencode-cli tests. Reuse existing transport owner after caller search; avoid an opencode-only ad hoc credential client.
+
+The executable security design and negative-case audit live only in ignored .tmp/operations/060_transport_private.md. That file must be completed and independently reviewed before B; no pre-disclosure reasoning is copied into public planning history. Public deliverable is the implementation, regression tests and shipped contract text only. Required review dimensions: local destination selection, redirect and proxy-environment behavior, credential separation and all current callers. Original contributor credit: Cortes Ventures <admin@cortesventures.com>. No fallback that substitutes a data credential for admin authentication.
+
+Hosted regression execution plus independent security source audit bind the final patch SHA. Review state is refreshed before handoff; this work cannot approve or merge the original PR. Local suites/build/typecheck/install NOT RUN.
diff --git a/devlog/_plan/260912_operations/070_verification.md b/devlog/_plan/260912_operations/070_verification.md
new file mode 100644
index 0000000000..e5af9101e3
--- /dev/null
+++ b/devlog/_plan/260912_operations/070_verification.md
@@ -0,0 +1,9 @@
+# Final tips and handoff
+
+Dependency: each implementation. No new behavior by default; append a separate PABCD repair cycle when actual final-tip CI failure identifies a necessary delta.
+
+For each independently mergeable branch: record git rev-parse HEAD, original source PR disposition, included commits, gh pr view headRefOid/baseRefName, successful native-membership read (or unknown), and gh run view for the exact Cross-platform CI run. Manual chains only when later work consumes earlier code; verify lower SHA ancestry at the final tip and record bottom-to-top order. Do not cancel auto-CI or change workflow/protection. No merge/auto-merge, closure, release or user service operation.
+
+A local receipt may run git diff --check and read-only hosted-result assertions; it is not a local test result. Local suites, typecheck/build/install are NOT RUN. Final behavior acceptance comes from GitHub-hosted test runs at the final SHA and independent review; author reports/old green CI are not substituted.
+
+Update ignored .tmp/operations/handoff.md as soon as each artifact exists. Include outstanding issue acceptance, original author trailers, unresolved maintainer objections, exact run links/conclusions and cycle ledger pointers. Publish template-complete PR bodies with truthful verification, screenshots for changed dashboard UI and no private investigation notes. Parent owns all integration decisions.
diff --git a/devlog/_plan/260912_operations/080_update_events.md b/devlog/_plan/260912_operations/080_update_events.md
new file mode 100644
index 0000000000..05896e305e
--- /dev/null
+++ b/devlog/_plan/260912_operations/080_update_events.md
@@ -0,0 +1,13 @@
+# Update child terminal-event follow-up
+
+User-requested review repair for PR4343 discussion3995158280. Previous totalsD directs this repair before client usage. Scope remains update cleanup; no live child/process operation locally. Class C4, satisfy-spec, existing credential scope, no time/token bound. Local tests/build/typecheck/install NOT RUN; source review now and hosted final4343 tip later. No merge.
+
+Source finding verified: src/update/job.ts spawnDetachedStart returns child_process.spawn result and records error, while retry ownership watches exit alone. Node child-process contract permits error without exit and guarantees close after failed spawn. Existing cleanup already skips absent PID; the defect is incomplete terminal-event retirement, not proof of a wrong-PID kill on failed spawn.
+
+MODIFY src/update/job.ts: one identity-checked retire handler clears lastChild only if it is still this child, and removes its own exit/error/close listeners to release closure references. Register once on all three. Existing spawn error logging, healthy probe behavior and live-child cleanup remain. This production owner does not call child.kill/send or supply AbortSignal; its error event is spawn failure. No global process supervisor or schema changes.
+
+MODIFY tests/update/update-job.test.ts: extend fake-child retry harness with failed spawn pid undefined, error then close without exit; assert retries continue and no liveness/kill calls, plus own terminal listeners are released. Parameterize late old-child terminal event across exit/error/close to prove object identity protects current live child. Keep live cleanup and healthy controls. A repeated terminal callback is idempotent.
+
+MODIFY structure/runtime.md observed-child paragraph and010 plan with terminal-event semantics. Publish --no-verify, independent source re-audit, reply with exact head and NOT RUN distinction, resolve the authorized review thread. Behavioral acceptance stays OPEN until final hosted CI.
+
+Source: https://nodejs.org/api/child_process.html#event-error and #event-close, opened2026-09-12. Public review: https://github.com/lidge-jun/opencodex/pull/4343#discussion_r3995158280.
diff --git a/devlog/_plan/260912_phantom_account_short_quota/000_plan.md b/devlog/_plan/260912_phantom_account_short_quota/000_plan.md
new file mode 100644
index 0000000000..d63f76fb04
--- /dev/null
+++ b/devlog/_plan/260912_phantom_account_short_quota/000_plan.md
@@ -0,0 +1,133 @@
+# Phantom account-level 5h row after Spark attribution (#4122 leftover) — plan
+
+## Reader summary
+
+Problem: one Codex Pro pool account still renders an account-level 5h bar
+(`5시간 리셋 9월 10일 02:24 4%`) even though Pro has no account-level 5h window and
+Issue #4122 already stopped new Spark 5h writes into that slot. Answer: stop
+`mergeAccountQuota` from carrying an elapsed `short*` tuple across a refresh that
+does not include a short window. What changes: the polluted Pro row drops the
+phantom bar on the next ordinary weekly/Spark refresh; Plus/Team accounts whose
+5h window is still open keep it.
+
+## Loop spec
+
+- Loop archetype: satisfy-spec (single work-phase wp1; not multi-cycle, so no
+  extra docs-first roadmap cycle).
+- Trigger: live 2026-09-12 dashboard report on http://localhost:10100/#codex-set
+  plus HOTL objective to land a merged PR on `dev`.
+- Goal: a Pro account whose refresh reports no account-level short window stops
+  showing a 5h row; the stale display tuple is removed while existing main-policy evidence remains protected; PR merged
+  to `dev` with exact-head CI.
+- Non-goals: GUI redesign; WHAM Spark-primary remapping (WHAM already files Spark
+  under customWindows and is not rewriting this account's shortObservedAt);
+  dropping still-open Plus/Team 5h windows; routing-policy redesign; release or
+  promotion; docs-site translation; local product suite/typecheck/build/install
+  (standing user rule: NOT RUN; remote CI is the gate).
+- Verifier: remote `.github/workflows/ci.yml` on the PR exact final head. The
+  `test` job's change filter includes `src/**` and `tests/**`;
+  `scripts/ci/run-bun-test-batches.sh` selects
+  `tests/codex-integration/codex-quota-parser-parity.test.ts`. Local
+  `bun test` / `bun run typecheck` / `bun run test` / `bun run build:gui`: NOT RUN
+  by standing user rule (command not executed; no exit code). Conditional paths:
+  (1) elapsed short + weekly/Spark refresh with no `short*` — activation: seed
+  past `shortResetAt`, apply weekly or Spark headers, observe `short*` absent;
+  (2) live short + weekly-only refresh — activation: seed future `shortResetAt`,
+  apply weekly headers, observe `short*` retained; (3) incoming explicit short
+  even if elapsed — activation: `setAccountQuotaFromParsed` with past reset,
+  observe the tuple stored so auto-refresh/scorer fixtures stay intact.
+- Stop condition: fetched `origin/dev` contains the PR commit and the live
+  phantom row is gone after the normal refresh path, or BLOCKED/NEEDS_HUMAN with
+  evidence.
+- Memory artifact: this unit directory plus
+  `.codexclaw/goalplans/hotl-fix-the-opencodex-dashboard-rendering-a-pha/`.
+- Expected terminal outcomes: DONE = c1–c4; BLOCKED = irreducible CI or
+  merge-policy denial; NEEDS_HUMAN = authority gap.
+- Escalation: local suite requirement, push without `--no-verify`, or expanding
+  into GUI/routing redesign returns to the user.
+- Architect consultation gap: this session has no bounded architect-subagent
+  transport (create_thread is user-owned and forbidden for subtasks). Design
+  decisions below are main-owned with file:line evidence.
+- HOTL resource bounds: this worktree shell/git/gh plus read-only local
+  management GETs; existing gh auth; write scope = this worktree and PRs on
+  lidge-jun/opencodex; no token/wall-clock budget set by the user.
+
+## Root cause (evidence)
+
+Live cache `~/.opencodex/codex-quota-cache.json`, entry for the affected Pro pool account, on
+2026-09-12 03:05 UTC (account identifiers deliberately omitted: this directory is public):
+
+- `shortPercent` 4 / `shortObservedAt` 1788956674678 (2026-09-09 12:24 UTC) /
+  `shortResetAt` 1788974652 (2026-09-09 17:24 UTC = KST 9월 10일 02:24) /
+  `shortWindowSeconds` 18000
+- `updatedAt` 1789182311711 (current)
+- current Spark customWindows (`GPT-5.3-Codex-Spark 5h` percent 0, reset in the
+  future) and weeklyPercent 29
+
+Peer Pro accounts in the same file have weekly + Spark customWindows and no
+account-level short. The one Team account there has a *fresh* short tuple
+(`shortObservedAt === updatedAt`, reset in the future) — a real Plus/Team 5h
+window that must be kept.
+
+`mergeAccountQuota` (`src/codex/quota.ts`) treats absence of `short*` as a partial
+update and copies the entire existing short tuple, then
+`setAccountQuotaFromParsed` always sets `updatedAt = Date.now()`. Disk hydration
+(`QUOTA_DISK_MAX_AGE_MS = 6h`) keys expiry on `updatedAt`
+(`src/codex/quota.ts:14-15,637-640`), so the carry prevents the TTL #4122 relied
+on. The carried `shortResetAt` is already in the past, so the rendered row is
+unreachable, not merely stale-but-plausible.
+
+Issue #4122 (`devlog/_fin/260909_spark_short_quota_attribution`) stopped *new* Spark
+header writes into the account short slot
+(`parseUpstreamQuotaHeaders` Spark branch, `src/codex/quota.ts:466-473`) and
+explicitly left polluted entries to the six-hour TTL. That assertion is false
+once carry rewrites `updatedAt`.
+
+### Alternatives refuted
+
+- GUI inventing the row: `normalizeQuotaForPlan` /
+  `buildQuotaRows` map `shortPercent` to a five-hour row with no expiry check
+  (`gui/src/codex-quota-utils.ts:38-45`, `gui/src/components/QuotaBars.tsx:73-82`).
+  They display what the cache already holds. The KST timestamp matches
+  `shortResetAt`, not a GUI clock bug.
+- WHAM still writing a Pro account-level short: `parseUsageQuota` still files an
+  explicit sub-day *primary* as short (`src/codex/quota.ts:811-814`) and Spark
+  additional limits as customWindows (`src/codex/quota.ts:871`). This account's
+  `shortObservedAt` is frozen on 2026-09-09 while weekly and Spark customWindows
+  keep moving, so current WHAM refreshes are not rewriting `short*`.
+- auth-api synthesizing a 5h row: DTO mapping copies stored short fields
+  (`src/codex/auth-api.ts:296`) and only filters Spark *custom* windows for
+  display. It does not invent `short*`.
+
+## File-change map
+
+See `010_phase1_drop_elapsed_short_carry.md`.
+
+## Accepted consequence
+
+A merge that drops an elapsed tuple also clears `fiveHourAvailable` in
+`codexQuotaAutoRefreshStatus` (`src/codex/quota-auto-refresh.ts:62-65`) until the
+window is observed again, because that flag reads `shortWindowSeconds` and
+`shortResetAt` from the same slot. Bounded on both sides: the scheduler keeps its
+own boundary (`rememberWindows` persists `nextFiveHourResetAt` and
+`dueCodexQuotaAutoRefreshWindows` prefers it over the stored quota,
+`src/codex/quota-auto-refresh.ts:78-101`), and any real Plus/Team response
+re-observes the window as an explicit incoming short, which this change never
+drops. The gap therefore only spans a credits-only or weekly-only refresh
+arriving between a reset instant and the next observation — and for a Pro
+account, where the window does not exist, clearing the flag is the correct
+outcome.
+
+## SoT
+
+The canonical current rule is in `structure/providers/openai-tiers.md`, with links from the
+other Codex structure owners and dashboard documentation. Display expiry never removes main
+hard-lock evidence. Reset-notification history retains omitted short observations separately.
+
+## Final audit refinement
+
+The initial design also expired identity-bound policy evidence. Independent review rejected
+that behavior: an elapsed deadline plus a credits-only update is not quota recovery. The final
+patch preserves policy evidence and removes only obsolete display/rotation carry. A second
+review found that notification history needed separate retention across those display updates;
+Codex now opts into that retention without changing other provider writers.
diff --git a/devlog/_plan/260912_phantom_account_short_quota/010_phase1_drop_elapsed_short_carry.md b/devlog/_plan/260912_phantom_account_short_quota/010_phase1_drop_elapsed_short_carry.md
new file mode 100644
index 0000000000..873bbde4e7
--- /dev/null
+++ b/devlog/_plan/260912_phantom_account_short_quota/010_phase1_drop_elapsed_short_carry.md
@@ -0,0 +1,34 @@
+# Phase 1: expire display carry without losing policy or notification evidence
+
+## Final implementation
+
+- `src/codex/quota.ts`: `assignCarriedShort` drops expired omitted short tuples only for
+  display/rotation merges; credits-only and legacy `updateAccountQuota` use the same rule.
+  `policyEvidence` preserves the previous short tuple, including its observation clock.
+  Explicit incoming short readings retain the original merge semantics.
+- `src/codex/routing.ts`: shares `resetAtToMs` with the carry expiry comparison.
+- `src/quota/reset-observer.ts` and `src/quota/reset-seen-store.ts`: Codex-only opt-in retains
+  absent short history for reset detection without manufacturing an incoming observation.
+  Its original timestamp survives repeated partial updates and persistence. Explicit clear
+  still removes the baseline; provider replacement behavior is unchanged.
+- Structure owners document the cache contract and link to its canonical statement.
+
+## Regression coverage
+
+- Parser parity: Spark and WHAM weekly refresh remove stale display short fields; weekly-only,
+  credits-only, future resets, explicit incoming resets, and legacy updates in seconds/ms.
+- Main hard-lock policy: expired short 99 remains blocked across credits-only, weekly-only,
+  and short metadata-only updates. A fresh short zero releases the block.
+- Reset observation: two partial writes after expiry emit nothing, the next real short
+  rollover emits exactly one scheduled notification, and explicit clear removes the baseline.
+- Reset store: retained observation time survives persistence; non-opted-in writers still
+  replace omitted windows.
+
+## Audit corrections
+
+Independent inherited-model reviewers found two regressions in the earlier patch: display
+expiry leaked into the main-policy cache, and dropping display short fields also discarded
+notification history. Both are corrected in the final implementation above.
+
+No red run, local suite, typecheck, build, or install was executed. Remote CI must verify the
+final pushed head; static comparison alone is not a passing execution result.
diff --git a/devlog/_plan/260912_provider_catalog_unified_search/000_plan.md b/devlog/_plan/260912_provider_catalog_unified_search/000_plan.md
new file mode 100644
index 0000000000..7daed3a935
--- /dev/null
+++ b/devlog/_plan/260912_provider_catalog_unified_search/000_plan.md
@@ -0,0 +1,33 @@
+# 000 — Add-provider catalog: unified search, note clamp, Local tab
+
+Three in-app comments on the add-provider modal (2026-09-12), delivered as one docs-
+first unit and a manual stacked PR chain onto `dev`.
+
+| doc | scope |
+|---|---|
+| `010_context.md` | the surface as it is, the three requirements, the standing constraints |
+| `015_codesign_grok.md` | co-design with `xai/grok-4.6`; accepted and rejected decisions |
+| `016_audit_corrections.md` | independent NEAR-PASS audit; **overrides the docs below where they disagree** |
+| `020_r3_local_tab.md` | wp2 — a dedicated Local tab |
+| `030_r2_note_clamp.md` | wp3 — two-line clamp plus a detail popup |
+| `040_r1_unified_search.md` | wp4 — unified search above the tabs |
+| `050_delivery.md` | wp5 — the stacked PR chain |
+| `evidence/grok-4.6-codesign.md` | the co-design report verbatim |
+
+## Work phases
+
+- **wp1** roadmap (this unit) — closed.
+- **wp2** R3 Local tab. First, because every later phase needs the tier set: R1's chip
+  counts and group order, and R2's row renderer, both sit on top of it.
+- **wp3** R2 note clamp and popup. Second, because it restructures the preset row that
+  R1 then has to render in groups.
+- **wp4** R1 unified search, plus the `structure/` and `docs-site/` updates the whole
+  unit owes once the final shape of the surface is known.
+- **wp5** stack finalization and remote-CI evidence.
+
+## Standing rules
+
+No local test suite (`bun run test`, `bun test`, `bun run test:changed`). A GUI build
+or `vite dev` **is** allowed — the user drew the line at the suite — which is what makes
+the mandatory `gui` screenshot on each PR possible. Every push is `--no-verify`.
+Remote CI on each PR's final head is the only test evidence.
diff --git a/devlog/_plan/260912_provider_catalog_unified_search/010_context.md b/devlog/_plan/260912_provider_catalog_unified_search/010_context.md
new file mode 100644
index 0000000000..4341122a38
--- /dev/null
+++ b/devlog/_plan/260912_provider_catalog_unified_search/010_context.md
@@ -0,0 +1,59 @@
+# 010 — Context and requirements
+
+Source: three in-app browser comments left on `http://localhost:10100/#providers`
+with the add-provider modal open (2026-09-12), plus the follow-up instruction to
+co-design R1 with `xai/grok-4.6` through Aside and land the work as a manual
+stacked PR chain.
+
+## The surface today
+
+`gui/src/components/provider-catalog/ProviderCatalog.tsx` renders, in order:
+
+1. a tablist of three tiers — Accounts / Free / Paid;
+2. an Accounts-only hint line;
+3. a search input **below** the tabs;
+4. one scrolling `.provider-catalog-rows` list for the active tier;
+5. a footer with the "not listed? add a custom one" link.
+
+View state is local: `tier` and `query` in `useState`. Switching tiers resets the
+query to `""`. `filterPresets` (in `provider-presets.ts`) matches case-insensitively
+on `label` and `id` only, and is applied to `buckets[tier]` — one tier at a time.
+
+Tier assignment is delegated: `presetTier` calls `providerTier` in
+`gui/src/provider-workspace/catalog.ts`, which is a three-way classifier shared with
+the providers workspace (rail sort modes, badges, section binning). `isFreeProvider`
+there folds `authMode === "local"` and loopback base URLs into **free**.
+
+## R1 — unified search (highest priority)
+
+> 이거 검색을 상단에 통합할수 는없나 검색창을 통합검색으로 바꾸기
+
+Move the search to the top and make it search every tab at once. The user asked the
+design question explicitly: when a match lives in a tab that is not selected, what
+does the tab strip do? Candidate behaviours are compared in `40_r1_unified_search.md`
+against the grok-4.6 co-design recorded in `15_codesign_grok.md`.
+
+## R2 — long notes
+
+> 이런 설명 너무 긴거 두줄 잘림 클릭하면 팝업에서 보이기
+
+The `.sub` line is `<code>{adapter}</code> · {note}`. `opencode-free` carries a
+~900-character note that renders as ~20 lines and consumes the entire 360px scroll
+viewport, so the row it belongs to is the only row a user can see. Clamp to two lines;
+reveal the rest on demand.
+
+## R3 — local providers
+
+> 로컬 쪽은 확실하게 새로운탭으로 구분하기
+
+Ollama, vLLM, LM Studio and any loopback-base-URL preset currently sit in **Free**,
+interleaved with hosted free tiers. They have a different setup story (nothing to sign
+up for, a runtime to install) and deserve their own tab.
+
+## Constraints carried from the request
+
+- No local test suite, typecheck, or build runs in this worktree. Verification is
+  remote CI on each PR head. Local checks are reported as NOT RUN.
+- Every push uses `--no-verify`.
+- Delivery is a manual dependent PR chain: each PR is based on the previous PR's head
+  branch, retargeted to `dev` after its parent lands.
diff --git a/devlog/_plan/260912_provider_catalog_unified_search/015_codesign_grok.md b/devlog/_plan/260912_provider_catalog_unified_search/015_codesign_grok.md
new file mode 100644
index 0000000000..42731ab3a9
--- /dev/null
+++ b/devlog/_plan/260912_provider_catalog_unified_search/015_codesign_grok.md
@@ -0,0 +1,90 @@
+# 015 — Co-design with xai/grok-4.6, and what we took from it
+
+Full report: `evidence/grok-4.6-codesign.md` (verbatim). Run:
+`aside exec --permission full-access -m opencodex/xai/grok-4.6`, session `5NwmGQtOxFLx50YI`,
+2026-09-12. It read the real files (`ProviderCatalog.tsx`, `provider-presets.ts`,
+`catalog.ts`, `kind.ts`, `provider-catalog.css`, the i18n tables and
+`tests/gui/provider-workspace-data.test.ts`) before answering.
+
+Worth noting because it changes how much weight the verdict carries: mid-run the
+model's scratch reasoning picked **B** (tabs keep filtering, auto-switch to the first
+tab with matches). Its final answer reverses that and argues against its own earlier
+pick. The reversal is the useful part, so the reasoning is reproduced below rather
+than just the conclusion.
+
+## Accepted
+
+**R1 = option A: search mode replaces browse mode.** While `query.trim()` is non-empty
+the list shows every match across all tiers, grouped with headings, and the selected
+tab is frozen rather than moved. The argument that settled it: a jump from Free to
+Accounts on `"openai"` does not just change which rows are listed, it changes the
+*kind* of row — a preset-select button becomes a login row with Log in / Add account
+buttons. Auto-switching between those is the VS Code Extensions-view
+Marketplace/Installed/Updates failure. And scroll position cannot be restored honestly
+across a jump because the destination is a different dataset.
+
+**The tab strip stops being a tablist during search.** Empty query: real tablist,
+`aria-selected`, `aria-controls` on the rows container (which needs an `id` it does not
+have today). Non-empty query: the same controls become jump chips —
+`role="button"`, no `aria-selected`, a count each, `disabled` at zero, and a click
+scrolls to that group heading instead of setting `tier`. This is the honest answer to
+"how does the tab move": it does not move, it becomes an index.
+
+**Stop clearing the query on tab click.** `setQuery("")` inside the tab `onClick` is
+the existing bug that makes the current search feel broken.
+
+**Keep the haystack at label + id.** The `filterPresets` comment ("never
+adapter/baseUrl") is load-bearing: `openai-chat` is the adapter on Ollama, vLLM,
+LM Studio, Groq, Cerebras and PackyCode, so matching adapters would dump half the
+catalog on `"openai"`; `localhost` would hit every local row. Widen only through
+explicit rules — an **exact** adapter-id equality match, and local-runtime aliases
+(`ollama`, `vllm`, `lmstudio`, `lm studio`, `localhost`) resolved through
+`isLocalProvider` rather than substring matching.
+
+**Ranking inside a group, never across groups:** exact id/label, then label prefix,
+then the existing sponsor pin, then usage rank, then label. Global re-ranking would let
+a paid sponsor sit above free NVIDIA on `"nim"`, which reads as an ad slot. Group order
+Accounts → Free → Local → Paid.
+
+**Accounts rows participate in search**, rendered as account rows under an Accounts
+group. When a login row and a preset share an id (`openai`), the login row wins and the
+preset is omitted. The Accounts hint and the "provider not listed?" footer are browse
+copy and hide during search.
+
+**R3 = catalog-only fourth bucket.** `providerTier` stays three-way; `bucketPresets`
+peels local out after classification via `isLocalProvider`; `CatalogTier` becomes
+four-way and stops being an alias of `ProviderTier`. The blast radius of the
+alternative is concrete: `sortWorkspaceItems` rank tables, `buildProviderWorkspace`
+ready-item tiers, `ProviderSortMode`, `AddProviderModal.initialTier`, every
+`modal.tab.*` string, `tests/gui/provider-workspace-data.test.ts`, and the workspace
+`freeCount` would silently stop counting Ollama — a product change nobody asked for.
+Tab order Accounts · Free · Local · Paid; default stays Free.
+
+## Rejected, with reasons
+
+**R2: grok says inline disclosure (`aria-expanded` + `aria-controls`, a sibling region
+under the row), explicitly "not a popup and not a stacked modal". We are shipping the
+popup anyway.** Two reasons outrank the advice. First, the user asked for one in
+plain words — "클릭하면 팝업에서 보이기" — and an explicit instruction beats a
+consultant's preference. Second, grok's own objection does not survive contact with
+this container: `.provider-catalog-rows` is `max-height: 360px; overflow-y: auto`, so
+expanding a 1157-character note *inline* pushes every row below it out of view and
+drops the reader's place in the exact list they were scanning. Its nested-dialog
+objection is also weaker than it looks here, because `AddProviderModal` already stacks
+a second `role="dialog"` overlay — `OAuthTosWarningModal` — as a sibling, so the
+pattern is established, reviewed and working in this file.
+
+What we keep from the advice: the two-line clamp is CSS, the reveal control is a nested
+`<button type="button">` with `stopPropagation` so it never selects the provider, the
+control only renders when the note actually overflows, and the full note never goes
+into `title` (not keyboard reachable, and far too long for a tooltip).
+
+**Escape ordering** follows grok: note popup first, then a non-empty query, then the
+dialog. `AddProviderModal` already guards its Escape handler with `oauthTosPending`;
+the note popup joins that guard.
+
+## Failure modes adopted as test targets
+
+Its five are taken as-is and are restated per work-phase in `020`/`030`/`040`. The
+sharpest one is #5: a tab/chip interaction during an in-flight Accounts login must not
+unmount the row that owns the paste field and `LoginHint`.
diff --git a/devlog/_plan/260912_provider_catalog_unified_search/016_audit_corrections.md b/devlog/_plan/260912_provider_catalog_unified_search/016_audit_corrections.md
new file mode 100644
index 0000000000..12c9b7f431
--- /dev/null
+++ b/devlog/_plan/260912_provider_catalog_unified_search/016_audit_corrections.md
@@ -0,0 +1,141 @@
+# 016 — Audit corrections (independent review, grok-4.6 explorer)
+
+A read-only reviewer audited the committed roadmap against the tree and returned
+**NEAR-PASS**. Its blocking findings are folded in here and this doc overrides 015,
+020, 030, 040 and 050 wherever they disagree.
+
+## Blocking: the reveal control cannot be a nested button
+
+A preset row is already `<button type="button" className="list-row">`
+(`ProviderCatalog.tsx:151`). A `<button>` inside a `<button>` is invalid HTML and the
+parser may hoist it out of the row, so `stopPropagation` never gets a chance to run.
+
+Correction: wrap each preset row in
+`<div className="provider-catalog-row-wrap">`, keep the row button as its first child,
+and render the reveal control as the row button's **sibling** inside that wrapper —
+never inside it. The wrapper is the flex item; the extra line appears only on rows
+whose note overflows.
+
+## Blocking: OAuthTosWarningModal is a native dialog, not a role=dialog div
+
+015 and 030 described it wrongly. `OAuthTosWarningModal.tsx:35-45` opens a native
+`<dialog>` with `showModal()` and handles Escape through the dialog `cancel` event;
+`AddProviderModal.tsx:247` is the `div role="dialog"`. The difference matters: only
+`showModal()` restores focus to the control that opened it.
+
+Correction: the note popup copies the real `OAuthTosWarningModal` implementation —
+native `<dialog>`, `showModal()` on mount, `onCancel` forwarding — and is rendered as
+a fragment sibling from `AddProviderModal` (`AddProviderModal.tsx:328`), not from
+`ProviderCatalog`, which sits inside `.modal-card` and cannot produce a sibling
+without a portal. The open flag therefore lives in `AddProviderModal` state and
+`ProviderCatalog` reports the request upward through a callback prop.
+
+## Blocking: the Escape guard must be lifted
+
+`AddProviderModal.tsx:127-132` listens on `window` and does not check
+`defaultPrevented`, which is exactly why the `!oauthTosPending` guard exists. The note
+popup joins it (`&& !noteOpen`), and R1's clear-the-query-on-Escape has to live in the
+same handler: `query` is `ProviderCatalog` state, child effects register after the
+parent, and the parent would close the whole dialog first.
+`gui/tests/add-provider-modal-backdrop.test.tsx:147` still expects a bare Escape to
+close an empty catalog, so the guard must be conditional, not unconditional.
+`tests/gui/oauth-tos-warning.test.ts:62` source-scans for `!oauthTosPending`,
+`showModal()` and `onCancel={handleCancel}`; those substrings must survive.
+
+## Blocking: chip focus can destroy an in-flight login
+
+040 focused the group heading on chip click. During an Accounts login that steals
+focus from the paste field, and a query that does not match the busy provider unmounts
+the row outright — `shouldShowLoginHint` cannot rescue a row that is not rendered.
+
+Correction: a busy Accounts row (`busyProvider`) is pinned into the Accounts group
+regardless of the query, and chip click scrolls without moving focus while a login is
+in flight.
+
+## Correction: bucketPresets types and peel order
+
+`bucketPresets` is `Record<ProviderTier, CatalogPreset[]>` (`provider-presets.ts:77`)
+and cannot grow a `local` key. `CatalogTier` moves into `provider-presets.ts` as the
+four-way type and the return becomes `Record<CatalogTier, CatalogPreset[]>`;
+`ProviderCatalog.tsx:29` stops redeclaring it. 015's claim that `CatalogTier` is an
+alias of `ProviderTier` was wrong — it is a separate three-string redeclaration.
+
+Peel order is accounts first, then local: otherwise a loopback-hosted canonical forward
+provider would leave the Accounts tab.
+
+`tests/gui/provider-workspace-data.test.ts:523` does not go red on its own — its
+fixture is venice/openai/nvidia/groq, so adding `local: []` keeps it green and only
+its name ("all three tiers") goes stale. The peel is locked by adding an ollama row to
+that fixture and asserting `buckets.local` is `["ollama"]` while `buckets.free` stays
+`["nvidia"]`. Line 518's `presetTier(ollama) === "free"` must keep passing untouched.
+
+## Correction: do not widen filterPresets, and do not widen initialTier
+
+`tests/gui/provider-workspace-data.test.ts:538` asserts `filterPresets` never matches
+adapter or baseUrl. The exact-adapter and local-alias rules from 040 go into a **new**
+search function; `filterPresets` keeps its contract for browse mode. Accounts rows are
+`AccountLoginRow`, a different type built in `providers-page-utils.ts`, so they need
+their own label/id filter.
+
+`AddProviderIntent.tier` (`ProviderWorkspaceShell.tsx:42`) and
+`AddProviderModal.initialTier` (line 40) stay three-way. Widening them would let
+empty-state tiles pass `"local"` by accident. Known consequence: the empty-state
+"browse free" tile (`ProviderWorkspaceShell.tsx:620`) opens Free, which no longer
+contains Ollama. A Local entry point there is follow-up work, not part of this unit.
+
+## Correction: clamp selector and note measurements
+
+`.provider-catalog-rows .list-row .sub` also hits account rows
+(`provider-catalog.css:58`). The clamp is scoped away from
+`.provider-catalog-account-row`.
+
+Real note lengths, from `src/providers/registry.ts`: `opencode-free` 1126 characters
+(not ~900), `meta-muse` 1157, `cursor` 663. The short-note fixture is
+`Local — key usually blank` with an em dash (`registry.ts:2102`).
+
+## Correction: i18n is nine catalogs with parity gates
+
+`modal.tab.paid` exists in en, de, fr, ko, zh, zh-TW, ru, ja, tr.
+`gui/tests/i18n-locales.test.ts:35` requires an exact English key set and
+`gui/tests/locale-parity.test.ts` fails a locale that leaves the English string in
+place without an allowlist entry. Every new key — tab label, reveal control, popup
+title and close, the live-region sentence, the group headings — needs a real
+translation in all nine. `gui/AGENTS.md:12` forbids hardcoded UI text.
+
+## Correction: test placement
+
+No new file under `tests/` is needed. Pure tier and search assertions extend the
+existing `tests/gui/provider-workspace-data.test.ts`, which avoids the
+`scripts/test-layout/layout.json` + `tests/fixtures/test-layout-expected.json`
+double registration that `tests/test-layout-tooling.test.ts:248` enforces. React and
+click behaviour goes in `gui/tests/*.tsx`, where the existing catalog component tests
+already live.
+
+## Correction: docs obligations the plan omitted
+
+`structure/gui-and-management-api.md:304` describes the catalog browser and
+`structure/AGENTS.md` obliges updating an owned area's doc when that area changes.
+`gui/AGENTS.md:33` asks for `docs-site/` updates on user-facing dashboard changes.
+Both land with wp4, once the final shape of the surface is known.
+
+## Resolved: the gui screenshot gate versus the no-local-build rule
+
+`.github/PULL_REQUEST_TEMPLATE.md:8` and `AGENTS.md:283` require a screenshot when a
+PR mentions `gui`, and `localhost:10100` serves the installed build's `gui/dist`, not
+this worktree's source — so a screenshot taken there would show the old UI.
+
+Asked and answered (2026-09-12): **a GUI build or `vite dev` in this worktree is
+allowed; the prohibition covers the test suite only.** So each UI-affecting PR gets a
+real screenshot from a dev server running this branch's source. `bun run test`,
+`bun test`, and `bun run test:changed` remain forbidden; remote CI is the only test
+evidence.
+
+## Also noted
+
+- LM Studio's preset id is `lm-studio`, so the `lmstudio` / `lm studio` aliases are
+  required rather than cosmetic.
+- Moving search above the tabs changes first focus on open: `AddProviderModal.tsx:111`
+  focuses the first focusable element, today the Accounts tab, afterwards the search
+  field. That is the desired outcome and is called out so it is not read as a bug.
+- Accounts browse ignores `rows` entirely and always maps `accountRows`
+  (`ProviderCatalog.tsx:175`); search mode is the first time account rows get filtered.
diff --git a/devlog/_plan/260912_provider_catalog_unified_search/020_r3_local_tab.md b/devlog/_plan/260912_provider_catalog_unified_search/020_r3_local_tab.md
new file mode 100644
index 0000000000..4ab547d63e
--- /dev/null
+++ b/devlog/_plan/260912_provider_catalog_unified_search/020_r3_local_tab.md
@@ -0,0 +1,57 @@
+# 020 — R3: a dedicated Local tab (work-phase wp2)
+
+First implementation cycle, because every later phase depends on the tier set. R1's
+chip counts and group order need Local to exist; R2 touches the same row renderer.
+
+## Change
+
+`gui/src/components/provider-catalog/provider-presets.ts`
+
+- `export type CatalogTier = "accounts" | "free" | "local" | "paid"` — declared here,
+  deliberately **not** an alias of `ProviderTier`. `ProviderCatalog.tsx` re-exports it
+  for existing importers.
+- `isLocalCatalogPreset(preset)` delegates to `isLocalProvider(presetTierInput(preset))`
+  from `gui/src/provider-workspace/kind.ts`, so loopback base URLs and
+  `authMode === "local"` are classified by the one helper the rail already uses.
+- `bucketPresets` returns four buckets. Local is peeled off **after** `presetTier`
+  runs, so `presetTier` keeps returning `"free"` for Ollama and the existing unit test
+  that asserts it stays green. Accounts still wins over local: a canonical forward
+  provider is an account row regardless of its URL.
+
+`ProviderCatalog.tsx`: the tab array becomes `["accounts", "free", "local", "paid"]`.
+
+i18n: `modal.tab.local` in every locale file that carries `modal.tab.paid`.
+
+## Not changed
+
+`providerTier`, `isFreeProvider`, `sortWorkspaceItems`, `ProviderSortMode`,
+`buildProviderWorkspace`, the workspace free count, and the amber Local badge. A local
+preset keeps whatever badges it has today; the tab is an additional axis, not a
+relabelling.
+
+## Risks
+
+- `AddProviderModal.initialTier` is typed `"accounts" | "free" | "paid"` and is passed
+  from `providers-page-modals.tsx`. Widening it to `CatalogTier` must not make any
+  caller start passing `"local"` implicitly.
+- An empty Local tab on a machine with no local runtime configured is fine — the
+  catalog is a preset list, and Ollama/vLLM presets are always present.
+
+## What actually moves (verified against `src/providers/registry.ts`)
+
+Four catalog rows change tab, all Free → Local: `ollama`, `vllm` and `lm-studio`
+(`authKind: "local"` plus a loopback base URL) and `litellm` (`authKind: "key"` with
+`keyOptional` and `localhost:4000`). LiteLLM is the non-obvious one — people browse it
+under Free today as a self-hosted key-optional gateway — and moving it is intended: it
+runs on the user's machine, which is what the tab is for. `presetTier` still returns
+`"free"` for all four, so the workspace Free count and the rail are unchanged.
+`openai` stays Accounts, `ollama-cloud` stays Paid (it is not loopback), and `devin-cli`
+is local but is not a catalog preset at all.
+
+## Verification (remote CI only)
+
+`tests/gui/provider-catalog-tiers.test.ts` (new, pure): local presets bucket to
+`local` and are absent from `free`; `presetTier` still returns `"free"` for them; a
+loopback-base-URL preset with `authMode: "key"` still lands in `local`; the canonical
+forward provider still buckets to `accounts`. New test files need an entry in
+`scripts/test-layout/layout.json` and `tests/fixtures/test-layout-expected.json`.
diff --git a/devlog/_plan/260912_provider_catalog_unified_search/030_r2_note_clamp.md b/devlog/_plan/260912_provider_catalog_unified_search/030_r2_note_clamp.md
new file mode 100644
index 0000000000..40c2e3352a
--- /dev/null
+++ b/devlog/_plan/260912_provider_catalog_unified_search/030_r2_note_clamp.md
@@ -0,0 +1,57 @@
+# 030 — R2: two-line note clamp with a detail popup (work-phase wp3)
+
+## Problem, measured
+
+The `.sub` line renders `<code>{adapter}</code> · {note}`. The `opencode-free` note is
+~900 characters, Muse Code ~1157, Cursor ~663. At the modal width that is 15-20 lines
+inside a `max-height: 360px` scroller, so one row fills the whole list and the catalog
+stops being browsable. That is the screenshot the user attached.
+
+## Change
+
+**Clamp (CSS).** `.provider-catalog-rows .list-row .sub` gets `display: -webkit-box`,
+`-webkit-line-clamp: 2`, `-webkit-box-orient: vertical`, `overflow: hidden`. The text
+block already carries `min-width: 0`, so this needs no layout change. Account rows keep
+their existing single-line ellipsis; the clamp is scoped to preset rows.
+
+**Reveal control.** A nested `<button type="button">` rendered only when the note
+exceeds the clamp threshold. It calls `stopPropagation()` so the enclosing `.list-row`
+button never fires `onSelectPreset`. Overflow is decided from note length, not from a
+layout read: `scrollHeight > clientHeight` would need a ref per row plus a resize
+observer and would make the decision untestable without a DOM. The threshold lives in
+`provider-presets.ts` as a named constant with its own unit test.
+
+> Superseded twice. `016` replaced the nested button with a sibling inside
+> `.provider-catalog-row-wrap`, because `.list-row` is already a `<button>`. And the
+> threshold shipped at **90**, not 120: at the modal width two lines hold roughly 110
+> characters minus the adapter chip, so 120 left notes in the 95-111 range visually
+> clamped with no way to read the rest. Erring short only costs a reveal on a row that
+> did not strictly need one.
+
+**Popup.** A sibling overlay with the same shape as `OAuthTosWarningModal`: a
+`role="dialog" aria-modal="true"` card rendered next to the add-provider overlay rather
+than inside it, holding the provider label, the adapter chip, the full note, and a close
+button. The argument for a popup over grok's inline disclosure is in `015`.
+
+**Escape ordering.** `AddProviderModal`'s handler is
+`if (e.key === "Escape" && !oauthTosPending) onClose()`. The note popup joins that
+guard, so Escape closes the note first and the add-provider modal second.
+
+## The cascade trap, hit again
+
+`gui/src/styles/provider-catalog.css` is `@import`ed at the **top** of `styles.css`,
+while `.link-btn` is declared far below it at equal specificity. A bare
+`.provider-catalog-note-more` therefore loses `background`, `border`, `padding` and
+`font-size` to `.link-btn`, while the `:has()` rule that strips the row's bottom border
+does win — so the row opened at the bottom and the reveal rendered as a full-width
+underlined link floating between two rows. Vite HMR hides this by injecting the edited
+file last; a production bundle does not. The rule is qualified as
+`.link-btn.provider-catalog-note-more`, exactly as
+`.list-row.provider-catalog-account-row--waiting` already had to be.
+
+## Verification (remote CI only)
+
+- pure: the overflow predicate is true for the opencode-free note and false for
+  `Local - key usually blank`.
+- the reveal control's click does not reach `onSelectPreset`.
+- the popup body carries the full note, not the clamped text.
diff --git a/devlog/_plan/260912_provider_catalog_unified_search/040_r1_unified_search.md b/devlog/_plan/260912_provider_catalog_unified_search/040_r1_unified_search.md
new file mode 100644
index 0000000000..45a7f084dc
--- /dev/null
+++ b/devlog/_plan/260912_provider_catalog_unified_search/040_r1_unified_search.md
@@ -0,0 +1,97 @@
+# 040 — R1: unified search across every tab (work-phase wp4)
+
+The design is option A from `015`: while the query is non-empty, search mode replaces
+browse mode and the selected tab is frozen instead of moved.
+
+## Layout
+
+The search input moves **above** the tab strip and stays mounted in both modes. It no
+longer resets on tab click.
+
+```
+[ search input                     ]   <- always first
+[ Accounts | Free | Local | Paid   ]   <- tablist when browsing, jump chips when searching
+[ rows ...                          ]
+```
+
+## Browse mode (query empty)
+
+Exactly today's behaviour plus the Local tab. The strip is a real tablist:
+`role="tablist"`, `role="tab"`, `aria-selected`, and `aria-controls` pointing at the
+rows container, which gains the `id` it does not have today.
+
+## Search mode (query non-empty)
+
+- The rows container renders **every** match, grouped, in the fixed order Accounts →
+  Free → Local → Paid, each group preceded by a heading carrying the tier name and its
+  count.
+- The strip drops `role="tablist"`. Each control becomes a plain button with a count,
+  `aria-controls` on its group heading, no `aria-selected`, and `disabled` at zero.
+  Clicking a non-zero chip scrolls its heading into view and moves focus there
+  (`tabIndex={-1}` then `focus()`); it does not change `tier`.
+- One `aria-live="polite" aria-atomic="true"` node announces the result count and the
+  tiers involved. It is not retargeted on chip click.
+- Accounts login rows are searchable and render as account rows under the Accounts
+  group. When a login row and a preset share an id, the login row wins and the preset
+  is dropped so `openai` cannot appear twice.
+- The Accounts hint line and the `modal.notListed` footer are browse copy and hide.
+- Zero matches: `modal.noMatch` in the list, every chip disabled, the live region says
+  the same thing.
+
+Clearing the query restores the frozen tab, scrolls the container to top, and brings
+the hint and footer back. Scroll offset is deliberately not restored: the list was
+replaced, so restoring an offset would land somewhere meaningless.
+
+## Matching
+
+Haystack stays label + id. Widening to adapter or base URL would dump half the catalog
+on `openai` (the adapter of Ollama, vLLM, LM Studio, Groq, Cerebras, PackyCode) and
+every local row on `localhost`. Two explicit widenings instead:
+
+1. equality-only adapter match, so `cursor` finds Cursor but `openai` does not match
+   `openai-chat`;
+2. local-runtime aliases (`ollama`, `vllm`, `lmstudio`, `lm studio`, `localhost`)
+   resolved through `isLocalProvider`, not through substring matching.
+
+Ranking inside a group: exact id or label, then label prefix, then the existing sponsor
+pin, then usage rank, then label. Never re-ranked across groups — a paid sponsor above
+free NVIDIA on `nim` reads as an ad slot.
+
+## Keyboard
+
+The input keeps focus while typing. ArrowDown from the input moves to the first result
+row, not to a chip. Escape clears a non-empty query before the dialog closes, and after
+the note popup if one is open (`030`).
+
+## Verification (remote CI only)
+
+Pure functions first: grouping, ordering, the login-row/preset dedupe, the ranking
+comparator, and the alias rules all live in `provider-presets.ts` and are unit-tested
+without React. The component test covers: a query with zero hits in the active tab
+leaves `tier` untouched; tab click with a non-empty query does not clear the query; an
+in-flight Accounts login keeps its `LoginHint` and paste field across a chip click.
+
+## What changed against this doc during the build
+
+Five things the plan did not anticipate, each found by an independent reviewer or by
+driving the surface:
+
+- **The group heading is not sticky.** A sticky bar needs an opaque background, and
+  `.modal-card` is a translucent glass panel, so it seamed against the card behind it —
+  and it read as a grey slab. It is now a small-caps `<h4>` with a hairline rule that
+  scrolls with the content; the chips above are already the index.
+- **The chip lookup cannot use `CSS.escape`.** Group ids come from `useId`, which emits
+  colons, so selecting on one needs `CSS.escape` — and `CSS` does not exist in the
+  happy-dom environment the GUI tests run in, so a chip click would have thrown
+  `ReferenceError` on CI rather than merely being untested. The heading carries a
+  `data-catalog-group` attribute instead.
+- **The jump scrolls the list itself**, and focuses with `preventScroll`. `.modal-card`
+  is also a scroll container, so both `scrollIntoView` and a plain `focus()` could drag
+  the search field out of view while jumping between groups.
+- **Loading and empty states key off what is actually on screen.** Using the total match
+  count meant the unfiltered Accounts bucket — which almost always holds an OpenAI login
+  row — kept a still-loading Free tab from ever saying it was loading. `visibleCount` is
+  the selected tab's own row count while browsing.
+- **The login/preset dedupe is a named helper**, `dropPresetsCoveredByAccounts`, rather
+  than a `Set` inside the memo, so the rule that a login row outranks a preset of the
+  same id has its own unit test.
diff --git a/devlog/_plan/260912_provider_catalog_unified_search/050_delivery.md b/devlog/_plan/260912_provider_catalog_unified_search/050_delivery.md
new file mode 100644
index 0000000000..e1ee9bb773
--- /dev/null
+++ b/devlog/_plan/260912_provider_catalog_unified_search/050_delivery.md
@@ -0,0 +1,29 @@
+# 050 — Delivery: stacked PR chain (work-phase wp5)
+
+## Chain
+
+Four branches, each based on the previous one's head, all eventually targeting `dev`:
+
+| PR | branch | base | content |
+|---|---|---|---|
+| 1 | `codex/provider-catalog-plan` | `dev` | this plan unit |
+| 2 | `codex/provider-catalog-local-tab` | PR 1 head | R3 (`020`) |
+| 3 | `codex/provider-catalog-note-popup` | PR 2 head | R2 (`030`) |
+| 4 | `codex/provider-catalog-unified-search` | PR 3 head | R1 (`040`) |
+
+Ordinary dependent PRs, not a GitHub native stack. `enforce-target` skips the
+wrong-base gate for a child whose base is another open PR's head; each child is
+retargeted to `dev` once its parent lands.
+
+## Rules carried from the request
+
+- Every push is `--no-verify`.
+- No local test suite, typecheck, or build runs in this worktree. Local checks are
+  reported as NOT RUN; remote CI on each PR's final head is the evidence.
+- Every PR fills `.github/PULL_REQUEST_TEMPLATE.md` in full. PRs 2-4 mention `gui`, so
+  each needs a screenshot of the UI change in its description.
+
+## Screenshot capture
+
+The proxy is already running on `http://localhost:10100`, so the GUI change can be
+driven in a browser against a dev build of the dashboard for the required screenshots.
diff --git a/devlog/_plan/260912_provider_catalog_unified_search/060_delivery_record.md b/devlog/_plan/260912_provider_catalog_unified_search/060_delivery_record.md
new file mode 100644
index 0000000000..3a8528892b
--- /dev/null
+++ b/devlog/_plan/260912_provider_catalog_unified_search/060_delivery_record.md
@@ -0,0 +1,52 @@
+# 060 — Delivery record
+
+Four dependent pull requests onto `dev`, one per work phase, every push `--no-verify`,
+no local test suite run at any point. Verified 2026-09-12.
+
+| PR | branch | base | head | live CI run |
+|---|---|---|---|---|
+| #4324 | `codex/provider-catalog-plan` | `dev` | `67657b9655` | `34666254983` success |
+| #4325 | `codex/provider-catalog-local-tab` | #4324 head | `7ae08971c7` | `34668670304` success |
+| #4328 | `codex/provider-catalog-note-popup` | #4325 head | `e3fdf8fd26` | `34668670844` success |
+| #4331 | `codex/provider-catalog-unified-search` | #4328 head | `68e6b028d7` | `34668669980` success |
+
+Ancestry is a real chain, checked with `git merge-base --is-ancestor`:
+`67657b9655` ⊂ `7ae08971c7` ⊂ `e3fdf8fd26` ⊂ `68e6b028d7`. Each PR's diff against its
+own base carries only that phase's work; no parent commit is replayed.
+
+## Two CI facts that are easy to misread
+
+**Cancelled duplicate runs leave FAILURE rows on a live head.** Pushing the rebased
+chain started overlapping workflow runs, and the concurrency group cancelled the older
+ones. A cancelled run's `ci` aggregator concludes *failure* with
+`needed job(s) did not pass: changes=cancelled`, and that row stays attached to the same
+head SHA as the live green run. On `e3fdf8fd26` the failing `ci` is job `103485691739`
+on cancelled run `34668670665`; the live aggregator `103488063420` on `34668670844`
+succeeded. Read the run, not the rollup.
+
+**A cancelled required check is not a passing one.** All three `enforce-target`
+attempts on `e3fdf8fd26` were cancelled the same way, which left #4328 `UNSTABLE` even
+though its product CI was green — `gh pr checks` maps a cancelled required check to
+fail. Re-running `34668680065` produced a success on that exact head and the PR went
+`CLEAN`. This was found by an independent auditor, not by reading the rollup.
+
+#4324 reports `BLOCKED` because `dev` requires a pull-request review; that is branch
+protection, not a check failure.
+
+## What CI proved that local runs did not
+
+The test suite was never run in this worktree, by instruction. Two defects were caught
+that a local run would have caught instantly, and both were found by static review
+instead:
+
+- `CSS.escape` in the chip jump would have thrown `ReferenceError` under bun/happy-dom,
+  taking the new chip test red. Replaced with a `data-catalog-group` attribute lookup
+  before it ever reached CI.
+- A third defect did reach CI: `gui/tests/fr-localization.test.ts` rejects a French
+  value identical to its English source, and `modal.tab.local` is `"Local"` in both.
+  "Local" is genuinely the same word in French and the Local *badge* was already on that
+  allowlist, so the tab joined it. Fixed at the root of the stack and the two children
+  were rebased onto it, which is why #4328 and #4331 were force-pushed once.
+
+Local checks that were run: `bun x tsc --noEmit`, `cd gui && bun x tsc --noEmit -p
+tsconfig.json`, and `bun run structure:check`. Everything else is **NOT RUN** locally.
diff --git a/devlog/_plan/260912_provider_catalog_unified_search/evidence/grok-4.6-codesign.md b/devlog/_plan/260912_provider_catalog_unified_search/evidence/grok-4.6-codesign.md
new file mode 100644
index 0000000000..9d9a02019d
--- /dev/null
+++ b/devlog/_plan/260912_provider_catalog_unified_search/evidence/grok-4.6-codesign.md
@@ -0,0 +1,82 @@
+# grok-4.6 co-design report (verbatim)
+
+Produced by: aside exec --permission full-access -m opencodex/xai/grok-4.6, 2026-09-12.
+Session 5NwmGQtOxFLx50YI. Answers the R1/R2/R3 design brief in 10_context.md.
+
+Pick **A**. Do not auto-switch the selected tab.
+
+The current surface is a browse catalog, not a command palette: tabs are pricing/ownership buckets (`accounts` / `free` / `paid`), search currently filters only the active bucket and is wiped on tab click, and Accounts rows are login rows rather than presets. Unified search has to leave that browse model intact when the query is empty, and replace it with a result list when it is not.
+
+**Why not B.** Chrome Settings and JetBrains Settings do count-badges-plus-auto-jump because their tabs are sibling pages of the same object. Here a jump from Free to Paid on `"cursor"` (or from Free to Accounts on `"openai"`) changes the row *kind*: a preset-select button becomes a login row with Log in / Add account. That is the VS Code Extensions-view failure mode (Marketplace vs Installed vs Updates) if search were allowed to steal the selected tab. Keyboard users who Arrow-Right across tabs then type will also lose their place. Zero-match on the active tab plus a silent jump hides the empty state they just caused. Scroll position cannot be restored honestly because the destination list is a different dataset.
+
+**Why not C.** "Other tabs" as a trailing section is Linear/Slack quick-switcher residue: those UIs have one result list and no tablist. Here it keeps `aria-selected` on a tab whose rows are no longer what is on screen, so a screen reader announces "Free, selected" over a Paid Cursor row. It also buries the actual hit under a possibly empty active-tab block. That is the current bug with extra chrome.
+
+**A, with one hard rule the candidate text left soft:** while `query.trim()` is non-empty, the tab strip is no longer a tablist. It becomes in-list jump chips (Raycast category chips, GitHub Marketplace "Filters" counts, Chrome Settings left-nav counts). The selected browse tab is frozen in React state and not visually selected. Clearing the query restores that tab, its scroll container to top, and the Accounts hint / custom-provider footer that belong to it. Do not restore scroll-into-the-old-offset; the list was replaced.
+
+Precedence that actually maps:
+
+- VS Code Extensions: search is global; the Marketplace/Installed/Updates tabs do not jump under you. Results are one list with section headers (`INSTALLED`, `RECOMMENDED`). That is A.
+- Chrome / macOS / JetBrains Settings: search replaces the page with a grouped result list; the previous pane is remembered. Chrome's left nav turns into jump targets with counts. That is A.
+- Raycast / Linear / Slack switcher: no tabs, one ranked list. Use their ranking, not their chrome.
+- GitHub Marketplace category tabs: a query keeps the category as a filter. That is B, and it is wrong here because Accounts is not a category of the same row type.
+
+**Tab strip during search**
+
+- Empty query: keep `role="tablist"` / `role="tab"` / `aria-selected` / `aria-controls` pointing at the rows container. Current markup is already a tablist with no `aria-controls` and no `id` on the panel; add those in this change. Tab click still switches bucket. Stop clearing the query on tab click; that is what makes today's search feel broken.
+- Non-empty query: drop `role="tablist"` from the strip. Each control becomes `role="button"` (or a link) with `aria-controls` on the matching group heading. No `aria-selected`. A `0` count is `disabled` and not focusable. Clicking a non-zero chip `scrollIntoView`s that `<h4>` inside `.provider-catalog-rows`; it does not set `tier`. Visual: remove `.active` underline; show `Free 3` / `Paid 1` / `Local 2` / `Accounts 0`.
+- Live region: one `aria-live="polite"` node, `aria-atomic="true"`, text like `7 providers across Free, Paid, Local`. Do not retarget it on chip click. On zero matches: `No providers match “cursor”` in the list, live region says the same, tab chips all disabled.
+- Accounts in search: include login rows that match on `label` / `id`. Render them under an Accounts group *as account rows*, not as preset-select buttons. If a preset and a login row share an id (`openai`), show the login row in Accounts and omit the preset from other groups. The Accounts hint string stays hidden in search mode; it is browse copy.
+- Footer: hide "Provider not listed?" during search. Custom-add is a browse escape hatch, not a search hit.
+- Focus: search input stays focused while typing. Chip click moves focus to the group heading (`tabIndex={-1}` then `.focus()`). Escape in the input clears the query if non-empty, else closes the dialog (existing dialog Escape). Do not put ArrowDown from the input onto chips; put it onto the first result row, like Raycast / VS Code.
+
+**Search fields and ranking**
+
+Keep label + id as the only default haystack. That comment in `filterPresets` ("never adapter/baseUrl") is load-bearing: `openai-chat` is the adapter on Ollama, vLLM, LM Studio, Groq, Cerebras, PackyCode. Searching `"openai"` would dump half the catalog. Base-url host is worse (`localhost` hits every local row; `api` hits most paid rows). Note-body match is how you get the 1157-char Muse Code note or the 663-char Cursor note lighting up on `"sandbox"` / `"key"` / `"login"`.
+
+Do add three explicit aliases, not substring-in-note:
+
+1. Exact adapter match only when the query equals the adapter id (`cursor`, `ollama-native`), not when it is a prefix of `openai-chat`.
+2. Local-runtime aliases: `ollama`, `vllm`, `lm studio`, `lmstudio`, `localhost` map to the Local group via `isLocalProvider`, not via haystack.
+3. Highlight the matched span on label/id only.
+
+Ranking inside a group, then group order Accounts → Free → Local → Paid:
+
+1. Exact id or exact label, case-insensitive.
+2. Label prefix (Chrome/Raycast "starts with").
+3. Sponsor pin, Main before Standard, then alphabetical among sponsors. Same contract as `pinSponsors`; usage rank must not bury a paid sponsor when the query is `"orca"`.
+4. Usage rank, then label.
+
+Do not globally re-rank across groups. A paid sponsor sitting above Free NVIDIA on `"nim"` is how you get the "search is an ad slot" complaint. Sponsors already have a badge and a pin *inside* their group.
+
+**R2: clamp + disclosure, not a nested dialog**
+
+The row is a `<button class="list-row">` that selects the provider. A 2-line CSS clamp (`-webkit-line-clamp: 2` on `.list-row .sub`, already `min-width: 0`) is the default. Full text is a disclosure, not a popup and not a stacked modal.
+
+- Pattern: `aria-expanded` + `aria-controls` on a nested `<button type="button">` labelled `More` / `Show full note`, with `stopPropagation`. The expanded region is a sibling under the row, `id` tied to `aria-controls`, not `role="dialog"`. Clicking More does not call `onSelectPreset`.
+- Why not popover: the catalog list is `max-height: 360px; overflow-y: auto`. An anchored popover either clips or portals out of the dialog's focus trap. `@floating-ui` in a modal is more code than the note is worth.
+- Why not a nested modal: `AddProviderModal` is already `role="dialog" aria-modal="true"`. A second dialog means nested inert/focus-trap (the OAuth TOS warning already does this once). A 900-character note is not a new task.
+- Why not inline expand of the whole row button: expanding inside the select button makes the click target's height jump and fires selection when the user was reading. Split the targets.
+- Truncate only when the note exceeds ~2 lines (roughly 120 characters, or `scrollHeight > clientHeight`). Short notes (`"Local — key usually blank"`) stay fully visible with no More control.
+- Do not put the full note in `title`. Title is not keyboard accessible and the Cursor/Muse notes are longer than any tooltip.
+
+**R3: catalog-only fourth bucket. Do not touch `providerTier`.**
+
+`ProviderTier` is documented as a three-way pricing/ownership tag from the 2026-07-17 interview: accounts (canonical OpenAI forward) wins over free, else paid. `isFreeProvider` intentionally returns true for `authMode === "local"` and loopback URLs so the workspace Free/Paid filter and `free-paid` sort keep treating Ollama as free. `ProviderRail` already splits that further with `isLocalProvider` from `kind.ts` (`authMode === "local" || hasLoopbackBaseUrl`). The add-provider tabs over-collapsed that distinction; the rail did not.
+
+So:
+
+- Add `isLocalCatalogPreset(preset)` in `provider-presets.ts` that delegates to `isLocalProvider(presetTierInput(preset))`.
+- Change `bucketPresets` to return `{ accounts, free, paid, local }`. Local is peeled out *after* `presetTier`, before the free push. `presetTier()` itself stays three-way. Tests that assert `presetTier(ollama) === "free"` stay green.
+- Catalog tab type (`CatalogTier`) becomes four-way and is *not* `ProviderTier`. Today's alias is the bug.
+- Workspace `isFreeProvider`, rail suffix, `sortWorkspaceItems`, badges: unchanged. Local rows keep the amber Local badge they already have; they do not grow a Free badge.
+- Blast radius if you instead add `"local"` to `ProviderTier`: `sortWorkspaceItems` rank tables, `buildProviderWorkspace` ready-item `tier`, `ProviderSortMode` `"free-paid"` / `"accounts-first"`, `AddProviderModal` `initialTier`, every i18n `modal.tab.*`, and `tests/gui/provider-workspace-data.test.ts`. Local Ollama would also drop out of the workspace Free count (`ProviderWorkspaceShell` `freeCount`), which is a product change nobody asked for.
+
+Default tab remains Free. Local is the fourth tab, after Free, before Paid: Accounts · Free · Local · Paid. That matches how people think ("is it logged-in, is it free cloud, is it my machine, is it billed").
+
+**Failure modes to test**
+
+1. Query `"openai"` on the Free tab: results group is Accounts (login row) only, or Accounts plus any preset whose *label/id* contains openai, never every `openai-chat` adapter. Clearing the query returns to Free, not Accounts. Live region does not say "Free, selected".
+2. Query `"cursor"` with Free active and zero Free hits: no auto-jump, Paid group visible with the Cursor row, Free chip disabled at `0`, browse `tier` still `"free"`. ArrowDown from the input lands on Cursor, not on a chip.
+3. Query `"local"` / `"ollama"` / `"localhost"`: Local group contains ollama/vllm/lm-studio; Free no longer lists them. `presetTier(ollama)` remains `"free"` in unit tests. Workspace Free count unchanged.
+4. Note clamp: Cursor (~663) and Muse Code CLI (~1157) rows stay ~2 lines. Clicking More expands in-row and does not select the preset. Clicking the row body still selects. Escape closes the disclosure first if open, then clears search, then closes the dialog. No second `role="dialog"`.
+5. Accounts + search + in-flight login: a matching Accounts row still renders `LoginHint` / paste field. Switching a jump-chip to Paid and back does not unmount that row's local paste state. A zero-match query does not destroy `busyProvider`. Tab click with a non-empty query does not clear the query (today's `setQuery("")` is the regression).
diff --git a/devlog/_plan/260912_provider_catalog_unified_search/evidence/wp2-local-tab.png b/devlog/_plan/260912_provider_catalog_unified_search/evidence/wp2-local-tab.png
new file mode 100644
index 0000000000..b606f4d767
Binary files /dev/null and b/devlog/_plan/260912_provider_catalog_unified_search/evidence/wp2-local-tab.png differ
diff --git a/devlog/_plan/260912_provider_catalog_unified_search/evidence/wp3-note-clamp.png b/devlog/_plan/260912_provider_catalog_unified_search/evidence/wp3-note-clamp.png
new file mode 100644
index 0000000000..ac86ca3bce
Binary files /dev/null and b/devlog/_plan/260912_provider_catalog_unified_search/evidence/wp3-note-clamp.png differ
diff --git a/devlog/_plan/260912_provider_catalog_unified_search/evidence/wp3-note-popup.png b/devlog/_plan/260912_provider_catalog_unified_search/evidence/wp3-note-popup.png
new file mode 100644
index 0000000000..24dc27b4f9
Binary files /dev/null and b/devlog/_plan/260912_provider_catalog_unified_search/evidence/wp3-note-popup.png differ
diff --git a/devlog/_plan/260912_provider_catalog_unified_search/evidence/wp4-browse-mode.png b/devlog/_plan/260912_provider_catalog_unified_search/evidence/wp4-browse-mode.png
new file mode 100644
index 0000000000..d311c5d86f
Binary files /dev/null and b/devlog/_plan/260912_provider_catalog_unified_search/evidence/wp4-browse-mode.png differ
diff --git a/devlog/_plan/260912_provider_catalog_unified_search/evidence/wp4-search-accounts.png b/devlog/_plan/260912_provider_catalog_unified_search/evidence/wp4-search-accounts.png
new file mode 100644
index 0000000000..8b4d963812
Binary files /dev/null and b/devlog/_plan/260912_provider_catalog_unified_search/evidence/wp4-search-accounts.png differ
diff --git a/devlog/_plan/260912_provider_catalog_unified_search/evidence/wp4-search-groups.png b/devlog/_plan/260912_provider_catalog_unified_search/evidence/wp4-search-groups.png
new file mode 100644
index 0000000000..cf77ac92b8
Binary files /dev/null and b/devlog/_plan/260912_provider_catalog_unified_search/evidence/wp4-search-groups.png differ
diff --git a/devlog/_plan/260912_release_regression_train/000_plan.md b/devlog/_plan/260912_release_regression_train/000_plan.md
new file mode 100644
index 0000000000..2a2dd0502c
--- /dev/null
+++ b/devlog/_plan/260912_release_regression_train/000_plan.md
@@ -0,0 +1,55 @@
+# Release regression train
+
+dev has drifted 79 commits past its last verified state and nothing has published since
+2.51.0. This unit takes dev back to a proved-green head, sweeps every commit in the
+unverified window for regressions, and then promotes preview and main with real
+push-event CI evidence behind each publish.
+
+## Baseline
+
+- `main` `c155cc7923`, version 2.51.0.
+- `preview` `69207f1b08`, version 2.52.0-preview.20260911.
+- `dev` `c27a4831a9`, package.json 2.52.0, no CI run recorded for this exact head.
+- Last `dev` run with `conclusion=success`: `e432cf565a` (2026-09-12 03:51 UTC).
+- Unverified window `e432cf565a..dev`: 79 commits, 57 non-merge, 58 `src/` files,
+  +3616/-229 inside `src/` alone.
+- Eleven dev push runs after that green ended `cancelled`, because `ci.yml` sets
+  `concurrency: cross-platform-ci-${{ github.ref }}` with `cancel-in-progress: true`
+  and the merges arrived faster than a run could finish. The twelfth, `f9815da21f` at
+  08:15 UTC, was allowed to finish and concluded `failure`. dev is red, not merely
+  unverified, and the current head `c27a4831a9` has no run at all.
+- `release.yml` refuses to publish a SHA without a successful push-event `ci.yml`
+  run on the release branch itself, so a red or unrun dev cannot reach a release.
+
+## Why the feature backlog stays out
+
+Twenty-seven open 60plus PRs are implemented and reviewed but unlanded. Adding them now
+would enlarge an already unverified window and make any regression bisect useless.
+They ship in the next cycle. Only two classes of change enter dev here: the shared
+CI repair in #4390, and fixes for regressions this sweep actually finds.
+
+## Cycles
+
+| Work phase | Document | Outcome |
+|---|---|---|
+| wp1 | this file | roadmap locked, later units pre-written |
+| wp2 | 010_ci_repair.md | #4390 green, merged, dev push CI success |
+| wp3 | 020_regression_sweep.md | every commit in the window reviewed |
+| wp4 | 030_defect_landing.md | blocking findings fixed and re-greened |
+| wp5 | 040_preview_release.md | preview promoted and published |
+| wp6 | 050_main_release.md | main promoted and published |
+
+## Constraints carried from the campaign
+
+Local product tests, builds, typecheck, and installs are not run. Verification is
+remote CI only and local checks are reported as NOT RUN. Pushes use `--no-verify`.
+Subagents are read-only verifiers dispatched on `xai/grok-4.6` at the user's explicit
+instruction; the stored subagent role configuration is left untouched. No account,
+credential, or model settings change. Already merged PRs are never recreated or
+reverted.
+
+## Stop conditions
+
+Stop and escalate if the sweep finds a defect in authentication, credential handling,
+or release automation. Stop if a policy gate outside maintainer control blocks the
+same step three times. Hitting a stated resource bound is BUDGET_EXHAUSTED, not DONE.
diff --git a/devlog/_plan/260912_release_regression_train/010_ci_repair.md b/devlog/_plan/260912_release_regression_train/010_ci_repair.md
new file mode 100644
index 0000000000..f701c9cc2d
--- /dev/null
+++ b/devlog/_plan/260912_release_regression_train/010_ci_repair.md
@@ -0,0 +1,42 @@
+# wp2 — CI repair and dev re-green
+
+PR #4390 (`codex/260912-finish-integration-fixtures`, head `d8335f75b4`) carries the
+shared repair that makes the Cline registration and Codex restore fixtures pass again.
+Twenty-one checks including `gates` pass on that head, which is what proves the Cline
+failure class is resolved. Four report failure: `test 4/4`, `macos 2/2`,
+`enforce-target`, and the `ci` aggregate that reflects the first two.
+
+## Failure 1 — `test 4/4`
+
+`tests/codex-integration/codex-inject-integration.test.ts` receives `matchedReads: 0`
+on Linux and on macOS alike, which rules out a path-string difference: the same file
+fails as `test 4/4` and `macos 2/2` with identical output.
+
+The interception never worked. `src/codex/inject-coordination.ts:8` binds
+`readFileSync` as an ESM named import, and `readOrNull`/`captureCodexPreImages` read
+`CODEX_PROFILE_PATH` through that binding, so `spyOn(fs, "readFileSync")` on the child's
+`require("node:fs")` handle reaches nothing. Every assertion in that test therefore ran
+against an undenied filesystem. The `matchedReads` counter added on this branch did not
+create the defect; it made an already-false test visible.
+
+That matters beyond this PR: the test arrived in #4342, which merged into dev with its
+own CI red, so dev has carried the failure since.
+
+Repair: drop the mock and make the profile genuinely unreadable with `chmod 0`, proving
+the precondition through a new `unreadable` field before any later assertion depends on
+it. The EACCES, outcomes, compensation, and preservation expectations are unchanged.
+Windows chmod only toggles the read-only bit and root ignores mode 0, so both are
+skipped.
+
+## Failure 2 — `enforce-target`
+
+The description mentions `gui` and carries no UI screenshot, which the gate rejects.
+Resolve it by supplying the screenshot when the change really touches the UI, or by
+removing the incidental `gui` mention when it does not. Disguising the mention to slip
+past a path-based gate is not an option.
+
+## Exit
+
+Every required check green at the final head, merged to dev with maintainer-integration
+recorded, ancestry and tree verified against fresh `origin/dev`, and one push-event
+`ci.yml` run allowed to finish on that dev head with no competing merge.
diff --git a/devlog/_plan/260912_release_regression_train/020_regression_sweep.md b/devlog/_plan/260912_release_regression_train/020_regression_sweep.md
new file mode 100644
index 0000000000..a91ef24f63
--- /dev/null
+++ b/devlog/_plan/260912_release_regression_train/020_regression_sweep.md
@@ -0,0 +1,58 @@
+# wp3 — regression sweep
+
+The sweep covers `e432cf565a..dev`, the window that never had a finished CI run. It
+also revisits the higher-risk subsystems across the full `main..dev` range, because
+that whole delta is what a 2.51.0 user receives.
+
+## Method
+
+Parallel read-only lanes on `xai/grok-4.6`. Each lane owns a disjoint read scope and
+returns findings as exact `file:line` or SHA citations, separating confirmed facts
+from suspicion. Lanes never write, never run local product commands, and never touch
+git state. The main session synthesizes, accepts or rebuts each finding, and decides.
+
+## Risk ranking
+
+Account pool and quota routing sit directly on the request path. Codex config injection
+and restore write the user's own `config.toml`. Remote workspace and remote control add
+new surface but default off behind `OCX_REMOTE_WORKSPACE_ENABLED`. Provider catalog,
+integrations and clients change what the CLI exposes. GUI, docs and i18n are visible but
+rarely release-blocking.
+
+## Exit
+
+Every commit in the window assigned to at least one lane with a recorded verdict, and a
+defect register that classifies each finding as release-blocking, user-visible minor, or
+harmless.
+
+## Window composition
+
+Of the 57 non-merge commits, 20 touch `src/`, 13 of those reach the user request path, and
+the remaining 37 are GUI, tests, docs, or devlog. `src/router.ts` and
+`src/server/lifecycle.ts` are untouched; the hub is `src/server/responses/core.ts`, which
+six commits share. That file belongs to one lane alone so the read scopes stay disjoint.
+
+## Lanes
+
+| Lane | Read scope | Commits |
+|---|---|---|
+| 1 | `src/codex/routing.ts`, `src/combos/resolve.ts`, `src/providers/quota*.ts`, `src/server/management/provider-routes.ts` | d42a1363dc (routing), f18541b8f5, 7418ef8eb2, 0bcb43e266 |
+| 2 | `src/server/responses/core.ts`, `chat-completions.ts`, `claude-messages.ts`, `adapter-resolve.ts`, `src/responses/custom-tool-compat.ts`, `src/bridge.ts`, `src/vision/plan.ts`, `src/web-search/index.ts` | d42a1363dc (core), de2042628d, d608d7fb0a, 17b3d3fe99, d6723f7f3b, d27db6dd56, b09ef15c6f (partial), 843486a3b8, 8949fd073f |
+| 3 | `src/claude/inbound*.ts`, `src/types/config.ts` | e114bc97b5, 954c1f28fc |
+| 4 | `src/codex/inject.ts`, `inject-coordination.ts`, `history-provider.ts` | 7f76d736c2, 1338e96c10, be203dd4a4 |
+| 5 | `src/oauth/**`, `src/adapters/**`, `src/providers/registry.ts`, devin-cli migration | fa4226a9ba, b09ef15c6f (partial), d6fb87197a, 96041e7833 |
+| 6 | `src/remote-control/**`, `src/update/job.ts` | 71857fac92, 726ddc7fc0, f378947111, e090ad65cd |
+| 7 | `src/integrations/**`, `src/clients/config-export*`, `src/cli/**`, management config/integration routes | 90975e9fea, 1feec1bdc0, 75a8ec8f78 |
+| 8 | `gui/src/**`, `gui/tests/**` | catalog stack, Combo clock and draft, Cline dialog |
+
+Lane 2 runs first because everything else can then ignore the hub file.
+
+## Already on the register
+
+Lane 4's own fixture was the first finding, and it came from CI rather than the sweep:
+`tests/codex-integration/codex-inject-integration.test.ts` asserts that an unreadable
+pre-image aborts capture, but it created that condition with
+`spyOn(fs, "readFileSync")` on the child's `require("node:fs")` handle. Production binds
+`readFileSync` as an ESM named import, so the mock intercepted nothing and the test ran
+entirely undenied. It fails identically on Linux and macOS, which means #4342 landed red
+and dev has been red ever since. The repair replaces the mock with a real `chmod`.
diff --git a/devlog/_plan/260912_release_regression_train/025_sweep_results.md b/devlog/_plan/260912_release_regression_train/025_sweep_results.md
new file mode 100644
index 0000000000..f35f4f98a5
--- /dev/null
+++ b/devlog/_plan/260912_release_regression_train/025_sweep_results.md
@@ -0,0 +1,74 @@
+# wp3 — sweep results
+
+Eight read-only lanes covered every non-merge commit in `e432cf565a..c27a4831a9`. Six
+returned CLEAN, one returned MINOR, and one returned BLOCKING. Every finding below was
+re-derived against source by a second reviewer before it was accepted.
+
+| Lane | Scope | Verdict |
+|---|---|---|
+| 1 | codex routing, combo resolve, provider quota | BLOCKING |
+| 2 | responses/chat/claude-messages/bridge/vision/search | CLEAN |
+| 3 | Claude inbound cache prefix | CLEAN |
+| 4 | Codex inject, restore, history | CLEAN |
+| 5 | OAuth, adapters, Devin CLI credentials | CLEAN |
+| 6 | remote-control, update job | CLEAN |
+| 7 | integrations, client export, CLI | MINOR |
+| 8 | GUI catalog, Combo, Cline dialog | CLEAN |
+
+## Release-blocking: the quota-avoid window skips the main account
+
+#4368 (`d42a1363dc`) split a quota refusal into two durations. The cooldown still caps at
+fifteen minutes, and a new `quotaAvoidUntil` records the window the refusal actually
+announced, bounded at six hours. Pool candidates honour it at
+`src/codex/routing.ts:1409`. The main account does not.
+
+`isSelectableCodexPoolAccount` rejects `__main__`, so the main login reaches the
+candidate list only through the re-insertion block at `src/codex/routing.ts:1414`, and
+that block checks `isCodexAccountSoftAvoided` but never `isCodexQuotaAvoided`.
+`getCodexQuotaHealthSnapshot` reads `cooldownUntil` alone, so once the fifteen-minute
+cooldown lapses the main account is a first-class candidate again while its announced
+window still has hours left.
+
+A user with the main login plus a pool sees exactly the failure #4368 was written to
+stop: pool accounts stay avoided for up to six hours, the main account returns after
+fifteen minutes, and the quota strategy ranks it coolest because it ranks on a weekly bar
+a burst limit never touches. A bound thread drops its affinity and is re-pinned to the
+same exhausted account. With no pool the symptom is unchanged, because the last-resort
+branch would hand back the only account anyway.
+
+## Same commit, same omission, two more paths
+
+The commit states that "an operator clearing the cooldown or naming the account overrules
+it". Neither does.
+
+`resetCodexRoutingForManualSelection` (`src/codex/routing.ts:988`) drops
+`quotaAvoidUntil` from `upstreamHealth` and returns early when that map has no entry. A
+reset-derived 429 writes to `quotaScopedHealth` instead and returns at
+`src/codex/routing.ts:2763`, so naming the account clears nothing in the case the commit
+actually introduced.
+
+`clearCodexAccountCooldown` (`src/codex/routing.ts:1066`) destructures the cooldown and
+probe-lease fields and carries `quotaAvoidUntil` through in `...rest`. Probe recovery at
+`src/codex/routing.ts:863` deliberately drops it, with a comment saying that leaving it
+would make the escape hatch stop escaping. The operator's escape hatch has the defect the
+automatic one avoids.
+
+An exhaustive scan found `quotaAvoidUntil` and `isCodexQuotaAvoided` used only in
+`src/codex/routing.ts`, and no fourth omission.
+
+## Non-blocking
+
+Lane 7 found only the top-level help text advertising `(14 clients)` against a registry
+of fifteen, which #4390 already corrected. The count never reaches dispatch;
+`ocx export --client cline` and the dashboard switch both read the registry.
+
+Lane 6 noted that `RemoteControlHost` defaults to the full capability set when a caller
+omits `allowedCapabilities`. No runtime file imports `src/remote-control`, so nothing
+reaches it; the documented `OCX_REMOTE_WORKSPACE_ENABLED` flag does not exist in `src/`
+yet. That is a default to settle when the activation layer lands, not a regression here.
+
+## What the lanes did not do
+
+No lane executed the product. Every verdict is a source and diff reading, cross-checked
+against the tests each commit shipped. Local product tests, builds, typecheck and install
+were NOT RUN.
diff --git a/devlog/_plan/260912_release_regression_train/030_defect_landing.md b/devlog/_plan/260912_release_regression_train/030_defect_landing.md
new file mode 100644
index 0000000000..ecdfad70c1
--- /dev/null
+++ b/devlog/_plan/260912_release_regression_train/030_defect_landing.md
@@ -0,0 +1,19 @@
+# wp4 — defect landing
+
+Findings the sweep confirms as release-blocking or user-visible get repair branches off
+fresh `dev`, one branch per defect class so each stays independently reviewable. Every
+repair goes through its own PR with exact-head CI, and dev is allowed to finish one
+push-event run afterwards.
+
+The known entry already on the register is the top-level help text in
+`src/cli/help.ts`, which still advertises `(14 clients)` after Cline made it fifteen.
+That one is carried by #4390 rather than a separate branch.
+
+A finding classified as non-blocking is recorded with the reason it does not block, not
+silently dropped. A finding in authentication, credential handling, or release
+automation stops the train instead of being landed quickly.
+
+## Exit
+
+No open release-blocking finding, and dev green at a head that already contains every
+repair.
diff --git a/devlog/_plan/260912_release_regression_train/040_preview_release.md b/devlog/_plan/260912_release_regression_train/040_preview_release.md
new file mode 100644
index 0000000000..a16a113159
--- /dev/null
+++ b/devlog/_plan/260912_release_regression_train/040_preview_release.md
@@ -0,0 +1,37 @@
+# wp5 — preview promotion and prerelease
+
+Preview goes first because 248 commits is too large a step to take straight onto
+`main`. The prerelease is the only place the changed config-injection path meets a real
+user config before the stable channel does.
+
+## Sequence
+
+Decide the prerelease version and bump the dev version line so `release.yml`'s
+`assert-ahead` check passes, promote dev into `preview` through a pull request because
+the branch ruleset requires one, wait for the `preview` push-event `ci.yml` run to
+report success, then dispatch the Release workflow with the preview dist-tag and the
+exact release SHA pinned in `expected-sha`.
+
+The workflow also demands a successful `service-lifecycle` run when service-related
+files changed since the previous merged tag. That condition has to be checked against
+the actual diff, not assumed.
+
+## Exit
+
+`npm dist-tag` `preview` points at the new prerelease and the publishing run is green.
+
+## Resolved numbers
+
+The prerelease is `2.52.0-preview.20260912`. `nextPreviewRelease` refuses a patch bump
+while the higher-core preview `2.52.0-preview.20260911` is open, so the bump kind is
+minor, and the UTC stamp is newer than the incumbent's so no ordinal suffix is added.
+dev already carries 2.52.0, which outranks that prerelease, so `assert-ahead` passes with
+no dev pre-move.
+
+Promotion is a pull request. The `Protect preview` ruleset gives admin a
+`pull_request` bypass only, so even an owner cannot push the branch directly; the
+`DeployKey` bypass exists for `scripts/release.ts`'s version-bump push and nothing else.
+
+The dispatch is
+`gh workflow run release.yml --ref preview -f version=2.52.0-preview.20260912 -f tag=preview -f expected-sha=<40-char preview SHA> -f dry-run=false`.
+Omitting `--ref` sends it to `main`.
diff --git a/devlog/_plan/260912_release_regression_train/050_main_release.md b/devlog/_plan/260912_release_regression_train/050_main_release.md
new file mode 100644
index 0000000000..3a2984a22f
--- /dev/null
+++ b/devlog/_plan/260912_release_regression_train/050_main_release.md
@@ -0,0 +1,37 @@
+# wp6 — main promotion and stable release
+
+Stable publishes only after the prerelease has been exercised. The same gates apply
+with the stable dist-tag, and `release.yml` additionally refuses a prerelease version
+string on `main`.
+
+## Sequence
+
+Confirm the preview channel showed no new defect, promote dev into `main` through a
+pull request, wait for the `main` push-event `ci.yml` run to succeed, then dispatch the
+Release workflow with the stable version, the `latest` dist-tag, and the pinned SHA.
+Verify the published version through `npm view` rather than trusting the run summary.
+
+Because PRs here target `dev` rather than the default branch, GitHub never auto-closes a
+linked issue. `AGENTS.md` puts that manual close at the point the change reaches `dev`,
+not `main`.
+
+## Exit
+
+`npm dist-tag` `latest` points at the new stable version, the `main` release SHA has a
+successful push-event CI run, and the sweep results are recorded in this unit.
+
+## Resolved numbers
+
+The stable version is `2.52.0`. `assert-ahead` compares `origin/dev`'s package version
+against it and requires a strict win, and 2.52.0 does not outrank 2.52.0, so dev has to
+move to `2.53.0` before this release can publish. That move is its own pull request,
+opened by dispatching `dev-version-bump.yml` from `main`; the workflow never pushes dev
+itself.
+
+Because the release SHA changes `package.json`, the service-lifecycle condition in
+`release.yml` fires, so that SHA also needs a successful `service-lifecycle` run.
+
+The dispatch is
+`gh workflow run release.yml --ref main -f version=2.52.0 -f tag=latest -f expected-sha=<40-char main SHA> -f dry-run=false`.
+`release.yml` serializes on a `release` concurrency group, so preview and main cannot
+publish at the same time.
diff --git a/devlog/_plan/260912_remote_workspace_carry/000_plan.md b/devlog/_plan/260912_remote_workspace_carry/000_plan.md
new file mode 100644
index 0000000000..7edf86510b
--- /dev/null
+++ b/devlog/_plan/260912_remote_workspace_carry/000_plan.md
@@ -0,0 +1,37 @@
+# Remote Workspace carry roadmap
+
+Remote Hub routes model requests to credentials on another computer. Remote Workspace adds an opt-in executor that owns approved project files while model sessions remain on the Hub. This unit carries the public foundation in PR #3458 into current dev as a dependency-ordered manual PR chain. It does not declare a production rollout or close the original draft.
+
+## Loop specification
+
+Satisfy-spec, triggered by the authorized remote carry lane. Goal: reviewable protocol, executor/runtime, then dashboard integration with author attribution. Non-goals: merge, release, deployment, live pairing or remote operations, user runtime changes. Local suites of every size, builds, typechecks and installation are NOT RUN by instruction. Existing workflows and branch protection remain unchanged; hosted final-tip evidence is required and any unavailable native confinement job is an explicit acceptance gap.
+
+Verifier: source/diff inspection in each cycle; existing GitHub hosted CI at the final cumulative SHA, plus explicit negative-case coverage. No local suite result is claimed. Stop condition: all scoped deltas audited, published, final evidence captured; unresolved security review or unavailable evidence remains an open acceptance item, never an invented success. Artifacts: this unit and ignored task scratch for sensitive review and execution receipts. Escalation: actual credential/tool gates; no added access, role setup or purchases. Main implements; independent subagents only review. No user token, time or agent-count limit. Existing tool/account scope only.
+
+## Source and architecture
+
+Source PR #3458: ba6f822cae53fcc4c91575a4c78f86f9944b6644. Original author: Ingwannu <ingwannu@users.noreply.github.com>. Latest author comment supersedes earlier failed-job notes; those old results are not evidence for this carry.
+
+Existing owners: src/remote for provider gateway identity, src/server for admission and management dispatch, src/cli for capabilities, gui/src for navigation, structure/manifest.json for ownership, scripts/test-layout/layout.json for tests. Reuse the original bounded workspace module instead of replacing the Remote Hub. No-op/config-only cannot provide executor tools; original implementation is the carry source.
+
+## Work phases
+
+0. Roadmap only: write and independently audit every decade document before production edits.
+1. Protocol/identity/permissions: inert codecs, signed handshake, capability contracts and bounded framing. No server route or import/startup timer, process or listener activation. Explicit reassembly calls may own expiry timers.
+2. Executor/runtime: file roots, command runner, hub/device state, encrypted transport and runtime bridges. No server/UI activation. Existing helper behavior remains fail-closed.
+3. Integration: opt-in Hub admission, authenticated dashboard management, CLI and navigation. Preserve current server decomposition and current test layout.
+4. Final hosted validation: final cumulative head only; repair actual final-head failures in separate cycles as needed. Capture chain order, exact head, CI runs and remaining acceptance in ignored handoff.
+
+Every stage revalidates the pinned source map. New code follows the original file bodies at the immutable source; adaptations are specified in decade documents and amended before execution. Source bodies are linked rather than duplicated into a 15k-line planning copy.
+
+## Process limitations
+
+The exposed spawn API does not support native architect role selection. User-authorized inherited design review and reflection satisfy the requested review method; native architect selection is not claimed. Session binding is verified, hooksVerified is false. These gaps are recorded separately from product verification.
+
+## Acceptance still outside the foundation
+
+Interactive PTY streaming, central hosted relay, signed Windows artifacts, safe macOS command containment, and real three-computer acceptance remain follow-up work explicitly excluded by the original foundation. Required maintainer security/architecture review stays open. Original PR is not closed by a carry draft.
+
+## Roadmap lock
+
+The roadmap passed independent design reflection for the bounded foundation and separate A review after correcting existing-file classifications and evidence reachability. Phase 2 must resolve concrete connection dependencies and required secret-store primitives before implementation. Explicit adaptation paragraphs override whole-body carry defaults. This cycle changes documentation only; product behavior and CI are not claimed verified. Next direction: execute phase 1, then revalidate phase 2 against the resulting tree.
diff --git a/devlog/_plan/260912_remote_workspace_carry/010_protocol.md b/devlog/_plan/260912_remote_workspace_carry/010_protocol.md
new file mode 100644
index 0000000000..193a2b592b
--- /dev/null
+++ b/devlog/_plan/260912_remote_workspace_carry/010_protocol.md
@@ -0,0 +1,42 @@
+# Phase 1: protocol
+
+Depends on: phase 0. Source: `ba6f822cae53fcc4c91575a4c78f86f9944b6644`. Main owns implementation; tests execute only on hosted CI.
+
+## Exact file map
+
+| Change | Source | Destination |
+| --- | --- | --- |
+| NEW | [src/remote-control/protocol.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/remote-control/protocol.ts) | `src/remote-control/protocol.ts` |
+| NEW | [src/remote-control/crypto.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/remote-control/crypto.ts) | `src/remote-control/crypto.ts` |
+| NEW | [src/remote-control/host.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/remote-control/host.ts) | `src/remote-control/host.ts` |
+| NEW | [src/remote-control/relay.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/remote-control/relay.ts) | `src/remote-control/relay.ts` |
+| NEW | [src/remote-control/workspace-tools.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/remote-control/workspace-tools.ts) | `src/remote-control/workspace-tools.ts` |
+| NEW | [src/remote-control/workspace-agent-protocol.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/remote-control/workspace-agent-protocol.ts) | `src/remote-control/workspace-agent-protocol.ts` |
+| NEW | [src/remote-control/workspace-rpc-framing.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/remote-control/workspace-rpc-framing.ts) | `src/remote-control/workspace-rpc-framing.ts` |
+| NEW | [src/remote-control/workspace-utf8.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/remote-control/workspace-utf8.ts) | `src/remote-control/workspace-utf8.ts` |
+| NEW | [tests/remote-control-prototype.test.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/tests/remote-control-prototype.test.ts) | `tests/clients/remote-control-prototype.test.ts` |
+| NEW | [tests/remote-workspace-rpc-framing.test.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/tests/remote-workspace-rpc-framing.test.ts) | `tests/clients/remote-workspace-rpc-framing.test.ts` |
+
+## Transformation contract
+
+NEW files carry the complete immutable source body. For moved tests, rewrite source imports `../src/` to `../../src/`, helper imports `./helpers/` to `../helpers/`, and obsolete fake-server paths to their current fixture owner. Register every new test in both layout.json explicit and test-layout-expected.json. Source-file reads and subprocess fixture paths use tests/helpers/repo-root.ts. Shared existing files take only source PR hunks, preserving all newer dev behavior; resolve conflicts against the named owner before writing. All original adopted implementation receives the coauthor trailer.
+
+Create a narrow src/remote-control/index.ts exporting only the eight foundation modules. Add structure/remote-workspace.md describing the inactive protocol library; register its ownership of src/remote-control/ in structure/manifest.json and regenerate INDEX using the existing generator. No runtime activation import belongs in this layer.
+
+Reachable negatives: forged handshake key/signature, replayed sequence, malformed relay/frame length, unknown capability, out-of-order/overlarge RPC fragments. Existing prototype/framing tests cover authentication, replay and bounds; add protocol-only cases where the split omitted coverage. Observe thrown rejection and absence of plaintext delivery in hosted CI.
+
+## Data and enforcement chain
+
+Required acceptance (not an established property of the pinned source): identity/capability creation comes from protocol builders and device root approval; serializers carry bounded versioned messages; strict parsers recover them; handshake/coordinator/executor consumers enforce capabilities and roots. GUI only displays public state. Tier: runtime boundary; executing surface: parser/auth/executor code. Known bypass: a process with the operator account can invoke host tools directly. Residual: local operator compromise is outside this process boundary. Wording: bounded remote tools, no claim of host-user isolation. Final layer for commands: OS confinement probe; unavailable means exec is not advertised.
+
+## Verification and rollback
+
+Local tests/build/typecheck/install NOT RUN by user instruction. Text comparison and git diff --check observe this change but are not product tests. Existing hosted CI command definitions are inspected before dispatch; final SHA evidence is recorded in phase 4. Revert this layer before its parent; no persistent state migrations are performed by this carry task.
+
+## Scope decision REMOTE-ARCH-004
+
+Retain the eight-module public source and its existing prototype tests: host.ts and relay.ts preserve author protocol coverage. These are inactive adapters. RemoteControlHost may call an explicitly supplied terminal factory only after authenticated traffic; this carry does not supply or connect a production terminal factory. Phase 1 delivers cryptographic identity primitives and protocol contracts, not complete device authorization.
+
+## Phase-1 revalidation
+
+Previous D: roadmap locked; continue with inactive protocol library. Base HEAD is 3d5e7037b5, source library still absent. Original eight source files and prototype/framing assertions were read; no path drift affects their self-contained dependency closure. New protocol contract tests will exercise agent codec rejection and UTF-8 byte boundaries directly. Existing clients test domain and both manifest registration maps confirmed. Structure generator is scripts/structure-ssot.ts --fix; it writes INDEX from the manifest and is permitted documentation generation, not a product build or test suite.
diff --git a/devlog/_plan/260912_remote_workspace_carry/020_executor_runtime.md b/devlog/_plan/260912_remote_workspace_carry/020_executor_runtime.md
new file mode 100644
index 0000000000..550b2a5bb5
--- /dev/null
+++ b/devlog/_plan/260912_remote_workspace_carry/020_executor_runtime.md
@@ -0,0 +1,84 @@
+# Phase 2: executor_runtime
+
+Depends on: phase 1. Source: `ba6f822cae53fcc4c91575a4c78f86f9944b6644`. Main owns implementation; tests execute only on hosted CI.
+
+## Exact file map
+
+| Change | Source | Destination |
+| --- | --- | --- |
+| NEW | [native/remote-workspace-helper/Cargo.lock](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/native/remote-workspace-helper/Cargo.lock) | `native/remote-workspace-helper/Cargo.lock` |
+| NEW | [native/remote-workspace-helper/Cargo.toml](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/native/remote-workspace-helper/Cargo.toml) | `native/remote-workspace-helper/Cargo.toml` |
+| NEW | [native/remote-workspace-helper/src/main.rs](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/native/remote-workspace-helper/src/main.rs) | `native/remote-workspace-helper/src/main.rs` |
+| NEW | [native/remote-workspace-helper/src/protocol.rs](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/native/remote-workspace-helper/src/protocol.rs) | `native/remote-workspace-helper/src/protocol.rs` |
+| NEW | [native/remote-workspace-helper/src/sandbox/macos.rs](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/native/remote-workspace-helper/src/sandbox/macos.rs) | `native/remote-workspace-helper/src/sandbox/macos.rs` |
+| NEW | [native/remote-workspace-helper/src/sandbox/mod.rs](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/native/remote-workspace-helper/src/sandbox/mod.rs) | `native/remote-workspace-helper/src/sandbox/mod.rs` |
+| NEW | [native/remote-workspace-helper/src/sandbox/windows.rs](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/native/remote-workspace-helper/src/sandbox/windows.rs) | `native/remote-workspace-helper/src/sandbox/windows.rs` |
+| NEW | [native/remote-workspace-helper/tests/live_confinement.rs](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/native/remote-workspace-helper/tests/live_confinement.rs) | `native/remote-workspace-helper/tests/live_confinement.rs` |
+| NEW | [src/cli/remote-workspace.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/cli/remote-workspace.ts) | `src/cli/remote-workspace.ts` |
+| MODIFY | [src/remote-control/index.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/remote-control/index.ts) | `src/remote-control/index.ts` |
+| NEW | [src/remote-control/workspace-agent-connection.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/remote-control/workspace-agent-connection.ts) | `src/remote-control/workspace-agent-connection.ts` |
+| NEW | [src/remote-control/workspace-claude-runtime.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/remote-control/workspace-claude-runtime.ts) | `src/remote-control/workspace-claude-runtime.ts` |
+| NEW | [src/remote-control/workspace-codex-runtime.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/remote-control/workspace-codex-runtime.ts) | `src/remote-control/workspace-codex-runtime.ts` |
+| NEW | [src/remote-control/workspace-codex-sandbox.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/remote-control/workspace-codex-sandbox.ts) | `src/remote-control/workspace-codex-sandbox.ts` |
+| NEW | [src/remote-control/workspace-command-runner.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/remote-control/workspace-command-runner.ts) | `src/remote-control/workspace-command-runner.ts` |
+| NEW | [src/remote-control/workspace-coordinator.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/remote-control/workspace-coordinator.ts) | `src/remote-control/workspace-coordinator.ts` |
+| NEW | [src/remote-control/workspace-device.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/remote-control/workspace-device.ts) | `src/remote-control/workspace-device.ts` |
+| NEW | [src/remote-control/workspace-executable.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/remote-control/workspace-executable.ts) | `src/remote-control/workspace-executable.ts` |
+| NEW | [src/remote-control/workspace-executor.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/remote-control/workspace-executor.ts) | `src/remote-control/workspace-executor.ts` |
+| NEW | [src/remote-control/workspace-hub.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/remote-control/workspace-hub.ts) | `src/remote-control/workspace-hub.ts` |
+| NEW | [src/remote-control/workspace-pi-runtime.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/remote-control/workspace-pi-runtime.ts) | `src/remote-control/workspace-pi-runtime.ts` |
+| NEW | [src/remote-control/workspace-process.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/remote-control/workspace-process.ts) | `src/remote-control/workspace-process.ts` |
+| NEW | [src/remote-control/workspace-rpc.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/remote-control/workspace-rpc.ts) | `src/remote-control/workspace-rpc.ts` |
+| NEW | [src/remote-control/workspace-runtime.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/remote-control/workspace-runtime.ts) | `src/remote-control/workspace-runtime.ts` |
+| NEW | [src/remote-control/workspace-sessions.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/remote-control/workspace-sessions.ts) | `src/remote-control/workspace-sessions.ts` |
+| NEW | [src/remote-control/workspace-tool-bridge.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/remote-control/workspace-tool-bridge.ts) | `src/remote-control/workspace-tool-bridge.ts` |
+| NEW | [tests/remote-workspace-agent-wire.test.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/tests/remote-workspace-agent-wire.test.ts) | `tests/clients/remote-workspace-agent-wire.test.ts` |
+| NEW | [tests/remote-workspace-app-server.integration.test.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/tests/remote-workspace-app-server.integration.test.ts) | `tests/clients/remote-workspace-app-server.integration.test.ts` |
+| NEW | [tests/remote-workspace-claude.integration.test.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/tests/remote-workspace-claude.integration.test.ts) | `tests/clients/remote-workspace-claude.integration.test.ts` |
+| NEW | [tests/remote-workspace-cli-runtimes.test.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/tests/remote-workspace-cli-runtimes.test.ts) | `tests/clients/remote-workspace-cli-runtimes.test.ts` |
+| NEW | [tests/remote-workspace-cli.test.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/tests/remote-workspace-cli.test.ts) | `tests/clients/remote-workspace-cli.test.ts` |
+| NEW | [tests/remote-workspace-codex-runtime.test.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/tests/remote-workspace-codex-runtime.test.ts) | `tests/clients/remote-workspace-codex-runtime.test.ts` |
+| NEW | [tests/remote-workspace-command-runner.test.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/tests/remote-workspace-command-runner.test.ts) | `tests/clients/remote-workspace-command-runner.test.ts` |
+| NEW | [tests/remote-workspace-device.test.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/tests/remote-workspace-device.test.ts) | `tests/clients/remote-workspace-device.test.ts` |
+| NEW | [tests/remote-workspace-hub.test.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/tests/remote-workspace-hub.test.ts) | `tests/clients/remote-workspace-hub.test.ts` |
+| NEW | [tests/remote-workspace-linux-confinement.test.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/tests/remote-workspace-linux-confinement.test.ts) | `tests/clients/remote-workspace-linux-confinement.test.ts` |
+| NEW | [tests/remote-workspace-platform.test.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/tests/remote-workspace-platform.test.ts) | `tests/clients/remote-workspace-platform.test.ts` |
+| NEW | [tests/remote-workspace-sessions.test.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/tests/remote-workspace-sessions.test.ts) | `tests/clients/remote-workspace-sessions.test.ts` |
+| NEW | [tests/remote-workspace-tool-bridge.test.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/tests/remote-workspace-tool-bridge.test.ts) | `tests/clients/remote-workspace-tool-bridge.test.ts` |
+| NEW | [tests/remote-workspace.test.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/tests/remote-workspace.test.ts) | `tests/clients/remote-workspace.test.ts` |
+| MODIFY | [src/lib/windows-atomic-replace.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/lib/windows-atomic-replace.ts) | `src/lib/windows-atomic-replace.ts` |
+| MODIFY | [tests/fake-codex-server.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/tests/fake-codex-server.ts) | `tests/fake-codex-server.ts` |
+| NEW | [tests/fixtures/fake-claude-stream.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/tests/fixtures/fake-claude-stream.ts) | `tests/fixtures/fake-claude-stream.ts` |
+| MODIFY | [package.json](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/package.json) | `package.json` |
+| MODIFY | [.gitignore](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/.gitignore) | `.gitignore` |
+| MODIFY | [.npmignore](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/.npmignore) | `.npmignore` |
+
+## Transformation contract
+
+NEW files carry the complete immutable source body. For moved tests, rewrite source imports `../src/` to `../../src/`, helper imports `./helpers/` to `../helpers/`, and obsolete fake-server paths to their current fixture owner. Register every new test in both layout.json explicit and test-layout-expected.json. Source-file reads and subprocess fixture paths use tests/helpers/repo-root.ts. Shared existing files take only source PR hunks, preserving all newer dev behavior; resolve conflicts against the named owner before writing. All original adopted implementation receives the coauthor trailer.
+
+Expand the public module exports to the immutable source index (plus any omitted workspace-runtime export only when a consumer requires it). Keep workspace-runtime lazily constructed and unattached to the core. Export win atomic-replace helper only if current owner remains unexported. Preserve newer package metadata and add only native source packaging entries/helper script names. Native source and lockfile are carried; no workflow modification is authorized.
+
+Reachable negatives: unapproved root and traversal; symlink/hardlink alias; changed helper digest; absent confinement provider; cancelled pending RPC; offline executor with no local fallback; revoked token; expired/used pairing code; rate-limit threshold. Runtime session/fake-provider tests exercise interruption/reconnect and cleanup. Existing final hosted suite is the executable verifier. Native OS confinement not run by existing workflows stays an explicit unmet acceptance item.
+
+## Data and enforcement chain
+
+Required acceptance (not an established property of the pinned source): identity/capability creation comes from protocol builders and device root approval; serializers carry bounded versioned messages; strict parsers recover them; handshake/coordinator/executor consumers enforce capabilities and roots. GUI only displays public state. Tier: runtime boundary; executing surface: parser/auth/executor code. Known bypass: a process with the operator account can invoke host tools directly. Residual: local operator compromise is outside this process boundary. Wording: bounded remote tools, no claim of host-user isolation. Final layer for commands: OS confinement probe; unavailable means exec is not advertised.
+
+## Verification and rollback
+
+Local tests/build/typecheck/install NOT RUN by user instruction. Text comparison and git diff --check observe this change but are not product tests. Existing hosted CI command definitions are inspected before dispatch; final SHA evidence is recorded in phase 4. Revert this layer before its parent; no persistent state migrations are performed by this carry task.
+
+## Session contract adaptation
+
+The executor endpoint receives explicit immutable sessionId, rootId and granted capabilities from the session owner. The agent connection constructs these options from the selected session and accepted capability set. The RPC boundary compares each request with that binding before invoking file or command tools. Test constructors provide the same explicit bindings; negative fixtures cover each mismatch and capability reduction. Keep detailed review evidence in ignored scratch.
+
+## Design reflection amendments
+
+REMOTE-ARCH-001/002: Add required per-session capabilities to HubAgentConnection.openSession; initial SessionService.create and ensureRemoteTransport pass their session capability subset. The signed hello carries that subset; accepted.hello.capabilities is copied into endpoint state. Selected root is conveyed by authenticated WSS under the explicitly trusted paired Hub; endpoint snapshots rootId and sessionId and validates locally approved root before session acceptance. Encrypted requests must match session/device/root and tool capability. Zero-executor-invocation negatives vary each independently, including an otherwise-approved second root. No opaque untrusted relay is introduced for workspace control frames.
+
+REMOTE-ARCH-003: Separate persisted enrollment capabilities from current connection availability. Presence may reduce effective connection authority but cannot expand the enrollment grant. Preserve the enrollment set in persisted device state, compute public effective capabilities as its intersection with current connection capabilities, and intersect new presence before acknowledgement. Device advertisement and acknowledgement accept reduced capabilities. Test downgrade, reconnect restoration inside grant, and attempted expansion beyond grant.
+
+REMOTE-ARCH-006: Use existing required private-file/Windows ACL primitives for new identity and bearer stores. Check permission setup failures and refuse loading/saving secrets when enforcement fails. Do not change global config-store behavior. Record exact selected existing helper in phase-2 P after reading the owner; no best-effort function is accepted as proof.
+
+REMOTE-ARCH-007: Codex real App Server tests depend on OCX_CODEX_BIN; Claude real integration on OCX_CLAUDE_BIN; Pi on OCX_PI_BIN. The Linux confinement case can return without execution unless OCX_REQUIRE_LINUX_REMOTE_WORKSPACE_CONFINEMENT=1 or bwrap is available. Current generic CI alone does not prove those paths. Mock tests prove lifecycle and tool-routing contracts only; native Hub isolation and executor confinement stay explicit final acceptance gaps when not activated. For each adapter separately record denied local tools, inherited plugins/hooks/config, offline refusal and teardown; inspect source plus hosted mocks, no claims of live CLI confinement from flags alone.
diff --git a/devlog/_plan/260912_remote_workspace_carry/030_integration.md b/devlog/_plan/260912_remote_workspace_carry/030_integration.md
new file mode 100644
index 0000000000..5c126f5987
--- /dev/null
+++ b/devlog/_plan/260912_remote_workspace_carry/030_integration.md
@@ -0,0 +1,69 @@
+# Phase 3: integration
+
+Depends on: phase 2. Source: `ba6f822cae53fcc4c91575a4c78f86f9944b6644`. Main owns implementation; tests execute only on hosted CI.
+
+## Exact file map
+
+| Change | Source | Destination |
+| --- | --- | --- |
+| MODIFY | [docs-site/astro.config.mjs](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/docs-site/astro.config.mjs) | `docs-site/astro.config.mjs` |
+| MODIFY | [docs-site/src/content/docs/guides/remote-hub.md](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/docs-site/src/content/docs/guides/remote-hub.md) | `docs-site/src/content/docs/guides/remote-hub.md` |
+| NEW | [docs-site/src/content/docs/guides/remote-workspace.md](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/docs-site/src/content/docs/guides/remote-workspace.md) | `docs-site/src/content/docs/guides/remote-workspace.md` |
+| MODIFY | [docs-site/src/content/docs/reference/cli.md](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/docs-site/src/content/docs/reference/cli.md) | `docs-site/src/content/docs/reference/cli.md` |
+| MODIFY | [docs-site/src/content/docs/reference/management-api.md](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/docs-site/src/content/docs/reference/management-api.md) | `docs-site/src/content/docs/reference/management-api.md` |
+| MODIFY | [gui/src/App.tsx](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/gui/src/App.tsx) | `gui/src/App.tsx` |
+| MODIFY | [gui/src/app-routing.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/gui/src/app-routing.ts) | `gui/src/app-routing.ts` |
+| MODIFY | [gui/src/i18n/de.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/gui/src/i18n/de.ts) | `gui/src/i18n/de.ts` |
+| MODIFY | [gui/src/i18n/en.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/gui/src/i18n/en.ts) | `gui/src/i18n/en.ts` |
+| MODIFY | [gui/src/i18n/fr.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/gui/src/i18n/fr.ts) | `gui/src/i18n/fr.ts` |
+| MODIFY | [gui/src/i18n/ja.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/gui/src/i18n/ja.ts) | `gui/src/i18n/ja.ts` |
+| MODIFY | [gui/src/i18n/ko.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/gui/src/i18n/ko.ts) | `gui/src/i18n/ko.ts` |
+| MODIFY | [gui/src/i18n/ru.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/gui/src/i18n/ru.ts) | `gui/src/i18n/ru.ts` |
+| MODIFY | [gui/src/i18n/tr.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/gui/src/i18n/tr.ts) | `gui/src/i18n/tr.ts` |
+| MODIFY | [gui/src/i18n/zh-TW.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/gui/src/i18n/zh-TW.ts) | `gui/src/i18n/zh-TW.ts` |
+| MODIFY | [gui/src/i18n/zh.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/gui/src/i18n/zh.ts) | `gui/src/i18n/zh.ts` |
+| NEW | [gui/src/pages/RemoteWorkspace.tsx](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/gui/src/pages/RemoteWorkspace.tsx) | `gui/src/pages/RemoteWorkspace.tsx` |
+| NEW | [gui/src/remote-workspace-command.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/gui/src/remote-workspace-command.ts) | `gui/src/remote-workspace-command.ts` |
+| NEW | [gui/src/styles-remote-workspace.css](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/gui/src/styles-remote-workspace.css) | `gui/src/styles-remote-workspace.css` |
+| MODIFY | [gui/src/styles.css](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/gui/src/styles.css) | `gui/src/styles.css` |
+| MODIFY | [gui/tests/fr-localization.test.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/gui/tests/fr-localization.test.ts) | `gui/tests/fr-localization.test.ts` |
+| MODIFY | [gui/tests/locale-parity.test.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/gui/tests/locale-parity.test.ts) | `gui/tests/locale-parity.test.ts` |
+| NEW | [gui/tests/remote-workspace.test.tsx](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/gui/tests/remote-workspace.test.tsx) | `gui/tests/remote-workspace.test.tsx` |
+| MODIFY | [gui/tests/sidebar-rows.test.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/gui/tests/sidebar-rows.test.ts) | `gui/tests/sidebar-rows.test.ts` |
+| MODIFY | [src/cli/dispatch.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/cli/dispatch.ts) | `src/cli/dispatch.ts` |
+| MODIFY | [src/cli/help.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/cli/help.ts) | `src/cli/help.ts` |
+| MODIFY | [src/cli/registry.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/cli/registry.ts) | `src/cli/registry.ts` |
+| MODIFY | [src/server/index.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/server/index.ts) | `src/server/index.ts` |
+| MODIFY | [src/server/management-api.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/server/management-api.ts) | `src/server/management-api.ts` |
+| MODIFY | [src/server/management/context.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/server/management/context.ts) | `src/server/management/context.ts` |
+| NEW | [src/server/management/remote-workspace-routes.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/server/management/remote-workspace-routes.ts) | `src/server/management/remote-workspace-routes.ts` |
+| MODIFY | [src/server/management/route-registry.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/server/management/route-registry.ts) | `src/server/management/route-registry.ts` |
+| MODIFY | [src/server/ws-bridge.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/src/server/ws-bridge.ts) | `src/server/ws-bridge.ts` |
+| MODIFY | [tests/cli-headless-parity.test.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/tests/cli-headless-parity.test.ts) | `tests/cli/cli-headless-parity.test.ts` |
+| MODIFY | [tests/loopback-listener-integration.test.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/tests/loopback-listener-integration.test.ts) | `tests/server/loopback-listener-integration.test.ts` |
+| NEW | [tests/remote-workspace-management.test.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/tests/remote-workspace-management.test.ts) | `tests/clients/remote-workspace-management.test.ts` |
+| NEW | [tests/remote-workspace-server.test.ts](https://github.com/lidge-jun/opencodex/blob/ba6f822cae53fcc4c91575a4c78f86f9944b6644/tests/remote-workspace-server.test.ts) | `tests/clients/remote-workspace-server.test.ts` |
+
+## Transformation contract
+
+NEW files carry the complete immutable source body. For moved tests, rewrite source imports `../src/` to `../../src/`, helper imports `./helpers/` to `../helpers/`, and obsolete fake-server paths to their current fixture owner. Register every new test in both layout.json explicit and test-layout-expected.json. Source-file reads and subprocess fixture paths use tests/helpers/repo-root.ts. Shared existing files take only source PR hunks, preserving all newer dev behavior; resolve conflicts against the named owner before writing. All original adopted implementation receives the coauthor trailer.
+
+Port original src/server/index.ts admission and WebSocket handlers into current owners after reading current decomposition. Keep runtimeRole=hub and no-Origin checks before lazy workspace imports. Browser mutations require gui-session. Pair exchange retains 32KiB bounded read, kernel-peer limiter and one-time device token. Add remote-workspace branch to all WsData consumers (open/message/close) with disconnect cleanup. Shutdown only touches already initialized workspace instances. Never import workspace modules from router.ts, lifecycle.ts or responses/core.ts.
+
+CLI registration now also needs src/cli/capabilities.ts and generated skills/ocx surface sync. GUI follows current App routing, nav structure and all locale dictionaries; preserve existing browser consent and error handling. User docs distinguish provider gateway Remote Hub from executor Remote Workspace. Current structure ownership docs receive concise source-appropriate updates without copying obsolete numbered docs.
+
+Reachable negatives: non-hub invocation; Origin-bearing pair/upgrade; missing/malformed/revoked bearer; admin-token attempt at dashboard mutation; excessive pairing body; ten invalid code attempts; unknown session/device/root; offline status and unavailable runtime. Original management/server tests plus new activation-isolation source guard must observe refusals and no optional activation. UI uses deterministic mocked API rendering, no live pairing. Screenshot must be generated/observed by an authorized renderer; absent render evidence is recorded as NOT VERIFIED, never borrowed from original screenshot.
+
+## Data and enforcement chain
+
+Required acceptance (not an established property of the pinned source): identity/capability creation comes from protocol builders and device root approval; serializers carry bounded versioned messages; strict parsers recover them; handshake/coordinator/executor consumers enforce capabilities and roots. GUI only displays public state. Tier: runtime boundary; executing surface: parser/auth/executor code. Known bypass: a process with the operator account can invoke host tools directly. Residual: local operator compromise is outside this process boundary. Wording: bounded remote tools, no claim of host-user isolation. Final layer for commands: OS confinement probe; unavailable means exec is not advertised.
+
+## Verification and rollback
+
+Local tests/build/typecheck/install NOT RUN by user instruction. Text comparison and git diff --check observe this change but are not product tests. Existing hosted CI command definitions are inspected before dispatch; final SHA evidence is recorded in phase 4. Revert this layer before its parent; no persistent state migrations are performed by this carry task.
+
+## Explicit activation REMOTE-ARCH-005
+
+NEW src/remote-control/workspace-activation.ts exports a side-effect-free guard requiring runtimeRole=hub AND process.env.OCX_REMOTE_WORKSPACE_ENABLED === "1". This guard imports only the config type. Pair and agent branches call it before dynamic import; disabled requests return 404. Management namespace returns a disabled status before importing runtime. Shutdown uses already retained workspace references or initialized-only lazy import only when explicitly enabled; a disabled Hub never creates identity or probes model CLIs. CLI pairing remains explicit Executor-local authorization and never modifies server environment. Document the opt-in variable and require an explicit environment choice to enable the feature. Test disabled Hub, non-Hub with flag, and enabled Hub, with no ambient inheritance in fixtures.
+
+Existing-file conflicts observed by git apply --check: management-api.ts, management/context.ts and ws-bridge.ts. Port the namespace-dispatch addition into current management handler, append only type/dependency seam fields after current imports, and extend current WebSocket discriminator/handlers without replacing newer fields. The check was text applicability only, not a product test.
diff --git a/devlog/_plan/260912_remote_workspace_carry/040_hosted_validation.md b/devlog/_plan/260912_remote_workspace_carry/040_hosted_validation.md
new file mode 100644
index 0000000000..d8a749b72c
--- /dev/null
+++ b/devlog/_plan/260912_remote_workspace_carry/040_hosted_validation.md
@@ -0,0 +1,20 @@
+# Phase 4: final hosted validation
+
+Depends on phase 3. Inspect final chain ancestry and fresh PR heads, base identities and review state. No workflow, branch protection or cancellation changes. Push only with --no-verify and create draft template-complete ordinary PRs. Existing hosted workflows run on final cumulative tip; request their supported all lane through existing dispatch only if applicable. Record workflow event/ref, head SHA, run ID/URL and result. Missing/skipped/cancelled native confinement is not passing evidence.
+
+No product implementation is planned in this validation phase. If final CI reveals a regression, amend this roadmap with a named repair cycle and source/test map before editing. Keep source-only checks distinct from executable CI. Record original PR #3458 disposition, coauthor trailer, current chain, full commits/heads, outstanding maintainer reviews, and original foundation exclusions in ignored durable handoff. Parent alone decides merge or original closure.
+
+Acceptance: final hosted typecheck/suite and applicable native confinement outcomes at the same SHA, no fake pass from old source runs; UI render observation at current tree or explicit unresolved gap. No local suite is permitted. No live devices, remote files or deployment are part of verification. DONE requires evidence; otherwise retain unfinished criteria and report the precise missing requirement.
+
+## Evidence reachability matrix
+
+| Path | Activation needed | Generic suite meaning |
+| --- | --- | --- |
+| Codex real runtime | OCX_CODEX_BIN configured in isolated hosted job | Missing env is skipped, not verified |
+| Claude real runtime | OCX_CLAUDE_BIN configured | Missing env is skipped, not verified |
+| Pi real runtime | OCX_PI_BIN configured | Missing env is skipped, not verified |
+| Linux confinement | bwrap + OCX_REQUIRE_LINUX_REMOTE_WORKSPACE_CONFINEMENT=1 | Early return is not confinement proof |
+| Windows native helper | cargo build + live AppContainer probe | Not invoked by current workflow |
+| macOS native helper | cargo fail-closed probe/direct-run | Not invoked by current workflow |
+
+Hosted mock lifecycle tests and source review retain their narrower meaning. Any unavailable path stays in final handoff acceptance, even if aggregate CI is green. No workflow changes or live-machine pairing are authorized.
diff --git a/devlog/_plan/260912_zcode_protocol_and_catalog/000_plan.md b/devlog/_plan/260912_zcode_protocol_and_catalog/000_plan.md
new file mode 100644
index 0000000000..18f2236231
--- /dev/null
+++ b/devlog/_plan/260912_zcode_protocol_and_catalog/000_plan.md
@@ -0,0 +1,45 @@
+# 000 — ZCode 프로토콜 정렬 + GLM-5.3 모달리티 정정
+
+## 목표
+
+ZCode 연동에서 확인된 세 가지 결함을 1차 근거와 함께 고친다.
+
+1. ocx가 ZCode에 내보내는 프로바이더 블록이 `kind: "openai-compatible"`(Chat Completions)로 붙는다.
+   ocx는 Responses-우선 프록시라 Chat 인바운드는 Responses로 번역된 뒤 다시 Chat으로 역번역된다.
+   ZCode는 `kind: "openai"`로 `{baseURL}/responses`를 직접 호출할 수 있으므로 번역을 0회로 줄인다.
+2. `zai`와 `zhipu-bigmodel-coding` 행이 `glm-5.3-flash`의 입력 모달리티를 음수 선언
+   (`noVisionModels` 제외)으로만 다뤄서, 클라이언트 export 피커에 네이티브 VLM이 text-only로 나간다.
+3. `zai` 행이 Chat Completions 한 갈래에 고정되어 있다. Z.AI 는 같은 키로 Responses 도 서빙하고
+   (`https://api.z.ai/api/v1`) 실사용에서 Chat 경로가 불안정하다. Responses 를 기본으로 돌리고
+   Chat 은 opt-in 으로 남긴다.
+
+## 제약
+
+- 로컬 상태(`~/.opencodex`, `~/.zcode`, `zcode-ocx-sidecar`)는 건드리지 않는다. 사용자 지시.
+- `zai` 행은 제자리에서 Responses 로 전환한다. 별도 행을 추가하지 않는다 — 사용자 결정
+  ("다 통합하고 chat optin 으로, 기존 사용자도 response 전환"). 초안에 있던 로스터 손실 우려는
+  실측으로 반증됐다: glm-5.2 / glm-5.1 / glm-5 / glm-4.6 / glm-5-turbo 전부 Responses 에서 200 이다
+  (030 라이브 표). 030 이 wp4 의 SSOT 다.
+- 프로토콜 전환은 조용히 일어나므로 릴리스 노트에 적는다. Chat 전용 키를 가진 사용자는
+  `modelAdapters` 로 모델마다 `openai-chat` 을 지정해야 한다. 마이그레이션 코드는 넣지 않는다.
+- wp2 와 wp3 는 서로 독립이다. wp4 는 wp3 가 넣는 `ZAI_GLM_5X_INPUT_MODALITIES` 상수에 의존하므로
+  wp3 가 `dev` 에 들어간 뒤에 올린다. 각 수정은 자기 이슈를 닫는 PR 로 가고 베이스는 `dev` 다.
+
+## 작업 단계
+
+| work-phase | 내용 | 이슈 | 문서 |
+|---|---|---|---|
+| wp1 | 조사 + 로드맵 + 이슈 3건 등록 (docs-only) | — | 000-003 |
+| wp2 | ZCode export를 `kind: "openai"`(Responses)로 | [#4295](https://github.com/lidge-jun/opencodex/issues/4295) | 010 |
+| wp3 | `glm-5.3-flash` 양수 모달리티 선언 | [#4296](https://github.com/lidge-jun/opencodex/issues/4296) | 020 |
+| wp4 | `zai` 를 Responses 기본으로 전환 + `chatCompletionsPath` 로 Chat opt-in | [#4297](https://github.com/lidge-jun/opencodex/issues/4297) | 030 |
+
+wp2 는 독립이다. wp4 는 wp3 뒤에 온다(위 제약).
+
+## 검증
+
+- `bun run typecheck`
+- `bun test tests/providers/zcode-client.test.ts tests/config/client-config-export.test.ts`
+- `bun test tests/providers/provider-registry-parity.test.ts`
+- `bun run structure:check` (structure/clients/integrations.md 소유 영역 변경 시)
+- PR-ready 게이트로 `bun run test`
diff --git a/devlog/_plan/260912_zcode_protocol_and_catalog/001_research_zai_model_facts.md b/devlog/_plan/260912_zcode_protocol_and_catalog/001_research_zai_model_facts.md
new file mode 100644
index 0000000000..359a102743
--- /dev/null
+++ b/devlog/_plan/260912_zcode_protocol_and_catalog/001_research_zai_model_facts.md
@@ -0,0 +1,61 @@
+# 001 — Z.AI GLM-5.3 계열 1차 근거 (Aside 세션 조사)
+
+수집 경로: `aside exec --permission full-access` (CLI 1.26.902, 세션 `cye9q0tV093bZeFJ`), 2026-09-12.
+아래 인용은 Aside 에이전트가 실제로 연 공식 문서 페이지에서 그대로 가져온 문장이다.
+
+## 입력 모달리티
+
+| 모델 | 입력 모달리티 | 컨텍스트 | 최대 출력 | reasoning 사다리 | 출처 |
+|---|---|---|---|---|---|
+| GLM-5.3 | text only | 1M | 128K | low / high / max (비활성화 불가) | https://docs.z.ai/guides/llm/glm-5.3 |
+| GLM-5.3-Flash | video / image / text / file | 1M | 128K | low / high / max (비활성화 불가) | https://docs.z.ai/guides/vlm/glm-5.3-flash |
+
+verbatim:
+
+> "GLM-5.3 currently supports text-only inputs, with a 1M-token context window and a maximum output length of 128K tokens."
+> — https://docs.z.ai/guides/llm/glm-5.3
+
+> "GLM-5.3 目前仅支持处理文本模态信息，支持 1M 上下文窗口，最大输出 Tokens 为 128K。"
+> — https://docs.bigmodel.cn/cn/guide/models/text/glm-5.3
+
+> "GLM-5.3-Flash is the first native multimodal model in the GLM-5 series"
+> "Input Modality: Video / Image / Text / File"
+> — https://docs.z.ai/guides/vlm/glm-5.3-flash
+
+> "GLM-5.3 is a text-only model, so uncheck Support Images; GLM-5.3-FLASH is a multimodal model, so Support Images can be checked"
+> — https://docs.z.ai/devpack/latest-model
+
+이미지 입력 전달 방식:
+
+> "Image Parameters: Add a content block with type: image_url to messages[].content[], and pass the image URL (recommended) or a Base64 Data URL through image_url.url."
+> — https://docs.z.ai/guides/vlm/glm-5.3-flash
+
+## reasoning effort
+
+> "reasoning_effort: Controls the degree of reasoning within the thought chain... Available values: max (default and recommended, deep inference), high (enhanced inference), low (mild inference, only supported by GLM-5.3 and GLM-5.3-FLASH)"
+> "For GLM-5.3 and GLM-5.3-FLASH, only max, high and low are supported. Any other input will result in an error."
+> — https://docs.z.ai/guides/capabilities/thinking
+
+리포지토리의 `ZAI_GLM_53_REASONING_EFFORTS = ["low", "high", "max"]` 와 일치한다.
+
+## 프로토콜 엔드포인트 (세 갈래)
+
+> "| Protocol | Base URL |
+> | OpenAI Chat Completion Protocol | https://api.z.ai/api/coding/paas/v4 |
+> | OpenAI Response Protocol | https://api.z.ai/api/v1 |
+> | Anthropic Message Protocol | https://api.z.ai/api/anthropic |"
+> — https://docs.z.ai/guides/llm/glm-5.3
+
+> "Claude Code / Goose (Anthropic-compatible): https://api.z.ai/api/anthropic
+> Codex: https://api.z.ai/api/v1
+> Other OpenAI-compatible tools: https://api.z.ai/api/coding/paas/v4"
+> — https://docs.z.ai/devpack/latest-model
+
+상충하는 단서 하나 (해결 필요):
+
+> "If you have previously subscribed to a GLM Coding Plan, including an expired subscription, you can currently access the model API only through the OpenAI Chat Completion-compatible protocol."
+> — https://docs.z.ai/guides/llm/glm-5.3
+
+즉 Coding Plan 구독 이력이 있는 키는 Responses 엔드포인트에서 거절될 수 있다. Responses 전환을
+제안하기 전에 실제 키로 확인이 필요하다.
+
diff --git a/devlog/_plan/260912_zcode_protocol_and_catalog/002_research_zcode_bundle_schema.md b/devlog/_plan/260912_zcode_protocol_and_catalog/002_research_zcode_bundle_schema.md
new file mode 100644
index 0000000000..94aa236ca4
--- /dev/null
+++ b/devlog/_plan/260912_zcode_protocol_and_catalog/002_research_zcode_bundle_schema.md
@@ -0,0 +1,87 @@
+# 002 — ZCode 3.11.2 번들 스키마 (app.asar 추출)
+
+조사 대상: `/Applications/ZCode.app/Contents/Resources/app.asar` (307MB, `rg -a`로 추출).
+버전 확인: 실행 로그 `[arms] electron initialized env=prod version=3.11.2`.
+리포지토리 주석은 3.7.7 / 3.8.1 기준이라 3.11.2 재확인이 필요했다.
+
+## kind enum — 정확히 3값
+
+```js
+bt=t.enum(["anthropic","openai","openai-compatible"])
+mh=t.enum(["anthropic-messages","openai-chat-completions","openai-responses"])
+```
+
+`mh`는 내부 `apiFormat` 표현이고 `bt`가 사용자 config의 `kind`다.
+
+## kind → 요청 경로
+
+```js
+function fL(e){switch(e){case"anthropic":return"/v1/messages";case"openai":return"/responses";case"openai-compatible":return"/chat/completions"}}
+s(fL,"getDefaultModelProviderEndpointPathForKind")
+
+function IHe(e,t){let n=t.replace(/\/+$/,"");switch(e){case"anthropic":return`${n}/v1/messages`;case"openai_chat":return`${n}/chat/completions`;case"openai_responses":return`${n}/responses`;case"gemini":return n}}
+s(IHe,"buildConnectivityRequestUrl")
+```
+
+baseURL 정규화는 kind별 접미사를 자동으로 떼어낸다:
+
+```js
+function lp(e,o){let r={anthropic:["/v1/messages","/messages"],openai:["/responses"],"openai-compatible":["/chat/completions"]},...}
+s(lp,"normalizeModelProviderBaseUrlForKind")
+```
+
+따라서 `kind:"openai"` + `baseURL:"http://127.0.0.1:10100/v1"` → `POST http://127.0.0.1:10100/v1/responses`.
+ocx는 그 경로를 실제로 서빙한다(`src/server/index.ts:1994`).
+
+## reasoning 필드
+
+사용자 config 모델 엔트리는 `variants`/`defaultVariant` 형태다:
+
+```js
+XWe=Q.object({enabled:Q.boolean().optional(),variants:Q.array(Q.string().min(1)).optional(),defaultVariant:Q.string().min(1).optional(),aliases:Q.record(Q.string(),Q.string()).optional()}).passthrough()
+```
+
+내부 카탈로그는 `levels`/`defaultLevel`이고 양방향 변환기(`openCodeReasoningToModelReasoning`)가 있다.
+즉 현재 export가 쓰는 `variants`/`defaultVariant`는 kind를 바꿔도 그대로 유효하다.
+
+wire 변환은 kind마다 다르다:
+
+| kind | 요청 필드 |
+|---|---|
+| openai-compatible | `reasoning_effort` |
+| openai | `reasoning: { effort }` |
+| anthropic | `output_config: { effort }` (+ 선택 `thinking`) |
+
+`kind:"openai"`가 보내는 `reasoning.effort`는 ocx `/v1/responses`가 네이티브로 읽는 필드다.
+
+## 모달리티
+
+```js
+Zse=Q.enum(["text","image","video","audio","pdf"])
+modalities:Q.object({input:Q.array(Zse).optional(),output:Q.array(Zse).optional()}).optional()
+```
+
+kind별 제한이 없고, `image`가 있으면 `supportsImages` 케파빌리티로 투영된다:
+
+```js
+w.supportsImages=y.modalities.input.includes("image")
+```
+
+## options / apiKeyRequired
+
+`options`는 `Q.record(Q.string(),Q.unknown())` 자유형이고, `apiKeyRequired:false`면 크리덴셜 요구를
+건너뛴다:
+
+```js
+function yA(e){if(e.apiKeyRequired===!1)return!0;...}s(yA,"hasRuntimeCredential")
+```
+
+## anthropic kind의 추가 요구사항 — 없음
+
+```js
+function rje(e){return e.kind?e.kind:...}s(rje,"resolveOpenCodeProviderDefaultKind")
+```
+
+명시된 `kind`가 최우선이고 `defaultKind`/`apiFormat`/`providerMappings`는 전부 optional 폴백이다.
+세 kind 어느 쪽으로 내보내도 추가 필드는 필요 없다.
+
diff --git a/devlog/_plan/260912_zcode_protocol_and_catalog/003_research_ocx_internals.md b/devlog/_plan/260912_zcode_protocol_and_catalog/003_research_ocx_internals.md
new file mode 100644
index 0000000000..0307a1ea56
--- /dev/null
+++ b/devlog/_plan/260912_zcode_protocol_and_catalog/003_research_ocx_internals.md
@@ -0,0 +1,75 @@
+# 003 — ocx 내부 경로 (서브에이전트 3레인 조사)
+
+## 인바운드 라우트
+
+| 경로 | 등록 |
+|---|---|
+| `POST /v1/responses` | `src/server/index.ts:1994` |
+| `POST /v1/messages` | `src/server/index.ts:2065` |
+| `POST /v1/messages/count_tokens` | `src/server/index.ts:2047` |
+| `POST /v1/chat/completions` | `src/server/index.ts:2097` |
+
+Anthropic과 Chat 인바운드는 둘 다 본문을 Responses 형태로 번역해 내부적으로 `handleResponses`로
+리플레이한다(`src/server/claude-messages.ts:2-7`, `src/server/chat-completions.ts:2-4`,
+`claude-messages.ts:900`의 `new Request("http://localhost/v1/responses", ...)`).
+Responses 인바운드만 번역이 0회다.
+
+ocx 자신도 ZCode를 Responses 클라이언트로 이미 인지하고 있다:
+
+> "Generic Responses-API clients (AI-SDK apps such as ZCode) omit `store`"
+> — `tests/responses/responses-inbound-store-default.test.ts:2`
+
+## 업스트림 와이어 결정
+
+인바운드가 아니라 라우트된 프로바이더의 `adapter`가 결정한다
+(`src/server/adapter-resolve.ts:13-15`, 하드핀 → 모델별 오버라이드 → 레지스트리 기본 → `provider.adapter`).
+`zai`는 `adapter: "openai-chat"`이므로 어떤 인바운드로 들어와도 업스트림은 Chat Completions다.
+
+## 클라이언트 export 프로토콜 지형
+
+| 클라이언트 | 프로토콜 | baseURL 규칙 |
+|---|---|---|
+| zcode | `kind:"openai-compatible"` → chat | base + `/v1` |
+| mcode | `api:"anthropic-messages"` | base에서 `/v1` 제거 |
+| dsh | `api:"openai-responses"` | base 그대로(`/v1` 포함) |
+| omp / raycast | chat completions | base 그대로 |
+
+즉 Responses로 붙는 클라이언트(dsh)와 Anthropic으로 붙는 클라이언트(mcode) 선례가 둘 다 있다.
+
+## ZCode 소유권 정책
+
+`src/integrations/ownership-policy.ts:66-84`가 refreshable로 인정하는 경로는
+`models.<id>.reasoning`, `models.<id>.limit.output`, (권위 컨텍스트 부재 시) `models.<id>.limit.context` 뿐이다.
+`kind`는 보호 필드다:
+
+> "Provider identity and connection fields (`name`, `kind`, `enabled`, `source`, and every `options` member), model membership, model names, modalities, and authoritative context limits remain protected. Changing any of them stays `conflict / foreign-edit`."
+> — `structure/clients/integrations.md:112-114`
+
+이건 사용자 편집에 대한 규칙이다. ocx가 생성 계약 자체를 바꾸면 desired contribution이 달라지므로
+기존 기록과 대조해 refresh 경로를 타야 한다. wp2에서 마이그레이션 동작을 반드시 확인한다.
+
+## 모달리티 전파 경로
+
+`registry.ts` → `configuredInputModalities`(`src/codex/catalog/provider-fetch.ts:674-677`)
+→ vision sidecar 보정(`provider-fetch.ts:787-798`) → 카탈로그 `input_modalities`
+→ `inputModalitiesForClient`(`src/clients/config-export/model-metadata.ts:61-72`) → 각 클라이언트 export.
+
+`zai` / `zhipu-bigmodel-coding` 행은 `modelInputModalities`를 아예 선언하지 않고
+`noVisionModels`(음수 선언)만 쓴다. 그래서 `glm-5.3-flash`는 sidecar 우회는 면하지만
+양수 선언이 없어 export 피커에서 `["text"]` 플로어로 떨어진다.
+
+`zhipu-bigmodel-responses` 행은 반대로 양수 선언을 갖는다
+(`modelInputModalities: { "glm-5.3": ["text"], "glm-5.3-flash": ["text", "image"], "glm-5-turbo": ["text"] }`).
+
+## 상류 권위 카탈로그 (라이브 확인, 2026-09-12)
+
+`GET https://api.z.ai/api/v1/models` → 200, Codex 형식 카탈로그:
+
+```json
+{"slug": "glm-5.3", "input_modalities": ["text"], "context_window": 1048576, "default_reasoning_level": "max"}
+{"slug": "glm-5.3-flash", "input_modalities": ["text", "image"], "context_window": 1048576, "default_reasoning_level": "max"}
+```
+
+전체 응답은 `evidence/zai-responses-models.json`. `POST https://api.z.ai/api/v1/responses`도 200을 반환했으므로
+"Coding Plan 구독 이력 키는 Chat만 가능"이라는 문서 문장은 이 키에 적용되지 않는다.
+
diff --git a/devlog/_plan/260912_zcode_protocol_and_catalog/010_wp2_zcode_export_responses.md b/devlog/_plan/260912_zcode_protocol_and_catalog/010_wp2_zcode_export_responses.md
new file mode 100644
index 0000000000..ba57892c69
--- /dev/null
+++ b/devlog/_plan/260912_zcode_protocol_and_catalog/010_wp2_zcode_export_responses.md
@@ -0,0 +1,82 @@
+# 010 — wp2 / ISSUE-1: ZCode export를 Responses kind로
+
+## 결함
+
+src/clients/config-export/zcode.ts 가 kind "openai-compatible" 을 내보낸다. ZCode 는 그 kind 에서
+{baseURL}/chat/completions 를 호출하고, ocx 의 Chat 인바운드는 본문을 Responses 로 번역해
+handleResponses 로 리플레이한 뒤 응답을 다시 Chat SSE 로 역번역한다. 왕복 2회 번역이고 그 과정에서
+tool-call delta 와 reasoning 블록이 형태를 바꾼다.
+
+ZCode 는 kind "openai" 로 {baseURL}/responses 를 직접 호출한다(002 문서의 fL / IHe 인용).
+ocx 는 POST /v1/responses 를 네이티브로 서빙한다(src/server/index.ts:1994). 번역 0회.
+
+## 변경
+
+### MODIFY src/clients/config-export/zcode.ts
+
+다섯 지점이다. 타입 리터럴(33행), 빌더 값(94행), 그리고 세 주석 블록(10-11행, 49-54행, 76-78행).
+
+    - kind: "openai-compatible";
+    + kind: "openai";
+
+    -        kind: "openai-compatible",
+    +        kind: "openai",
+
+주석은 3.11.2 번들에서 재추출한 사실로 갱신한다: getDefaultModelProviderEndpointPathForKind 가
+anthropic 을 /v1/messages, openai 를 /responses, openai-compatible 을 /chat/completions 로 보낸다는
+것과, Responses 가 프록시의 네이티브 인바운드라 이전 배선이 턴마다 번역 두 번을 냈다는 것.
+
+baseURL 은 그대로 ctx.baseUrl 에서 /v1 을 떼고 다시 "/v1" 을 붙인 값이다. ZCode 의
+normalizeModelProviderBaseUrlForKind 는 openai kind 에서 /responses 접미사만 떼므로 /v1 은 보존되고
+최종 URL 은 http://127.0.0.1:<port>/v1/responses 가 된다.
+
+reasoning 블록(enabled / variants / defaultVariant)은 kind 와 무관하게 같은 스키마다. openai kind 에서는
+선택된 variant 가 reasoning.effort 로 나가고, 그건 ocx /v1/responses 가 네이티브로 읽는 필드다.
+
+76-78행 주석이 "ZCode forwards the selected variant as reasoning_effort" 라고 말하는데 그건
+openai-compatible kind 의 wire 필드다. openai kind 는 reasoning.effort 로 보낸다(002 문서의
+withOpenAiResponsesThoughtLevel 인용). 동작은 스키마가 같아 그대로지만 주석은 틀리므로 함께 고친다.
+
+### MODIFY tests/providers/zcode-client.test.ts
+
+    -    expect(provider.kind).toBe("openai-compatible");
+    +    expect(provider.kind).toBe("openai");
+
+options 기대값(baseURL http://127.0.0.1:10100/v1)은 바뀌지 않는다. 같은 describe 에 회귀 테스트를
+하나 추가해, ZCode 가 openai kind 에서 조립하는 최종 URL 이 프록시가 실제로 서빙하는 경로와
+일치한다는 것을 고정한다.
+
+    test("the exported kind resolves to the proxy's native Responses route", () => {
+      const document = buildClientConfig("zcode", context()) as ZcodeGeneratedConfig;
+      const provider = document.provider[OPENCODE_PROVIDER_ID]!;
+      // ZCode 3.11.2 getDefaultModelProviderEndpointPathForKind: openai -> "/responses".
+      expect(provider.kind).toBe("openai");
+      expect(provider.options.baseURL + "/responses").toBe("http://127.0.0.1:10100/v1/responses");
+    });
+
+### MODIFY tests/config/client-config-export.test.ts
+
+123행 직렬화 바이트 고정값에서 "kind":"openai-compatible" 을 "kind":"openai" 로 바꾼다.
+나머지 필드 순서와 값은 동일하다.
+
+## 마이그레이션 — 기대 결과는 stale -> rewrite
+
+감사에서 확정됐다. kind 는 refreshable 경로가 아니지만(ownership-policy.ts:66-84), 사용자가 파일을
+손대지 않았다면 recordedBlockIsOwned 가 기존 지문으로 true 를 돌려주고(integrations/state.ts:213)
+desired 지문만 달라져 상태가 stale 이 된다(state.ts:411). JSON 클라이언트인 zcode 는 stale refresh 에서
+프래그먼트를 다시 쓴다. 즉 미수정 설치는 자동으로 따라온다.
+
+--overwrite-conflict 는 사용자가 kind 나 options 를 직접 고쳐 이미 foreign-edit 인 경우에만 필요하다.
+tests/clients/integrations-writer.test.ts:525 의 conflict 케이스는 사용자가 baseURL 을 편집한 상황이지
+ocx 가 kind 를 바꾸는 상황이 아니다.
+
+회귀 테스트는 구성 가능한 쪽으로 넣는다. 이전 빌드가 쓴 기록(옛 지문)을 이 하네스에서 만들 수 없어
+"옛 기록 + 새 계약 -> stale" 은 직접 재현할 수 없다. 그 경로는 코드로만 확인된다
+(state.ts:213 recordedBlockIsOwned, state.ts:405-411 stale 분류, writer.ts:390-391 재작성).
+대신 보완 관계인 보호 쪽을 고정한다: 사용자가 kind 를 손으로 되돌리면 여전히 conflict / foreign-edit 이고
+apply 가 거부된다. baseURL 편집에만 있던 보호를 kind 에도 명시적으로 건다.
+
+## 검증
+
+    bun test tests/providers/zcode-client.test.ts tests/config/client-config-export.test.ts tests/clients/integrations-writer.test.ts
+    bun run typecheck
diff --git a/devlog/_plan/260912_zcode_protocol_and_catalog/020_wp3_glm53_flash_modalities.md b/devlog/_plan/260912_zcode_protocol_and_catalog/020_wp3_glm53_flash_modalities.md
new file mode 100644
index 0000000000..619742aeaa
--- /dev/null
+++ b/devlog/_plan/260912_zcode_protocol_and_catalog/020_wp3_glm53_flash_modalities.md
@@ -0,0 +1,70 @@
+# 020 — wp3 / ISSUE-2: glm-5.3-flash 입력 모달리티 양수 선언
+
+## 결함
+
+glm-5.3 은 text-only 이고 glm-5.3-flash 는 네이티브 VLM 이다(001 문서, 그리고 상류
+GET https://api.z.ai/api/v1/models 의 input_modalities).
+
+zai 와 zhipu-bigmodel-coding 행은 이 사실을 noVisionModels 음수 선언으로만 표현한다.
+ZAI_GLM_5X_SIDECAR_VISION_MODELS 가 flash 를 제외하므로 vision sidecar 우회는 막히지만,
+modelInputModalities 가 없어 configuredInputModalities 가 undefined 를 돌려주고 카탈로그가
+["text"] 플로어로 떨어진다. 결과적으로 클라이언트 export(ZCode / Pi / OMP)의 모델 피커에
+네이티브 VLM 이 text-only 로 실리고 이미지 첨부가 막힌다.
+
+zhipu-bigmodel-responses 행은 이미 양수로 선언한다. 같은 모델인데 행마다 다르게 표현된 상태다.
+
+## 변경
+
+### MODIFY src/providers/registry.ts
+
+ZAI_GLM_5X_SIDECAR_VISION_MODELS 정의 바로 아래에 공유 상수를 추가한다.
+
+    const ZAI_GLM_5X_INPUT_MODALITIES: Record<string, string[]> = {
+      ...Object.fromEntries(ZAI_GLM_5X_SIDECAR_VISION_MODELS.map(id => [id, ["text"]])),
+      "glm-5.3-flash": ["text", "image"],
+    };
+
+주석으로 남길 근거: noVisionModels 는 음수 진술이라 sidecar 우회만 막고 카탈로그에 모델이 무엇을
+읽을 수 있는지 말해주지 않는다는 것, 그리고 권위 출처가 GET https://api.z.ai/api/v1/models 의
+input_modalities(["text"] vs ["text","image"], evidence/zai-responses-models.json 에 캡처)와
+docs.z.ai/devpack/latest-model 의 산문이라는 것.
+
+zai 행과 zhipu-bigmodel-coding 행 각각에 한 줄씩 추가한다.
+
+         noVisionModels: ZAI_GLM_5X_SIDECAR_VISION_MODELS,
+    +    modelInputModalities: ZAI_GLM_5X_INPUT_MODALITIES,
+         modelReasoningEfforts: ZAI_GLM_5X_REASONING_EFFORTS,
+
+glm-4.6 은 두 행의 models 에 있지만 5.x 가족이 아니라 이 맵에 없다. 선언이 없으면 기존 폴백 동작이
+유지되므로 의도적으로 건드리지 않는다.
+
+### MODIFY tests/providers/provider-registry-parity.test.ts
+
+기존 전역 assertion 은 "flash 선언이 있으면 image 를 포함해야 한다"는 조건부다. 이제 Chat 행에서도
+선언이 존재해야 하므로 고정 기대값을 추가한다.
+
+    test("the Chat-path Z.AI rows declare glm-5.3-flash as multimodal, not just out of the sidecar list", () => {
+      for (const id of ["zai", "zhipu-bigmodel-coding"] as const) {
+        const row = PROVIDER_REGISTRY.find(entry => entry.id === id);
+        expect(row?.modelInputModalities?.["glm-5.3-flash"]).toEqual(["text", "image"]);
+        expect(row?.modelInputModalities?.["glm-5.3"]).toEqual(["text"]);
+        expect(row?.noVisionModels ?? []).not.toContain("glm-5.3-flash");
+      }
+    });
+
+## 범위 밖
+
+src/generated/model-metadata.ts 와 scripts/model-metadata.source.json 의 zai 번들에는 glm-5.3-flash
+행 자체가 없다. 그 파일은 vendored 스냅샷 + 생성물이고 tests/codex-integration/model-metadata-sync.test.ts
+가 바이트 동기화를 강제한다. 스냅샷 갱신은 별도의 의도적 커밋이므로 이 PR 에 섞지 않는다.
+레지스트리 선언이 폴백보다 우선하므로 이 결함은 레지스트리 한 곳에서 닫힌다.
+
+상류가 말하는 Flash 의 입력은 Video / Image / Text / File 이지만 이 변경은 image 까지만 선언한다.
+ocx 의 내부 모달리티 어휘는 text / image / audio 이고 ZCode·Pi export 어휘는 text / image 뿐이라
+(src/clients/config-export/model-metadata.ts:56-58) video 와 file 은 표현할 자리가 없다.
+피커 결함은 image 선언만으로 닫힌다. video / file 은 명시적으로 범위 밖이다.
+
+## 검증
+
+    bun test tests/providers/provider-registry-parity.test.ts tests/codex-integration/catalog-vision-sidecar-modalities.test.ts
+    bun run typecheck
diff --git a/devlog/_plan/260912_zcode_protocol_and_catalog/030_wp4_zai_responses_default.md b/devlog/_plan/260912_zcode_protocol_and_catalog/030_wp4_zai_responses_default.md
new file mode 100644
index 0000000000..2b830e42e4
--- /dev/null
+++ b/devlog/_plan/260912_zcode_protocol_and_catalog/030_wp4_zai_responses_default.md
@@ -0,0 +1,210 @@
+# 030 — wp4 / ISSUE-3: Z.AI 를 Responses 기본으로 통합하고 Chat 을 opt-in 으로
+
+## 결함
+
+Z.AI 는 같은 키로 세 프로토콜을 서빙한다(001 문서 인용).
+
+    OpenAI Chat Completion   https://api.z.ai/api/coding/paas/v4
+    OpenAI Response          https://api.z.ai/api/v1
+    Anthropic Message        https://api.z.ai/api/anthropic
+
+ocx 의 zai 행은 Chat 한 갈래에 고정되어 있다(adapter openai-chat). Chat 경로는 실사용에서 불안정하고,
+Z.AI 자신의 devpack 안내도 Codex 계열 클라이언트에 Responses 엔드포인트를 지정한다("Codex:
+https://api.z.ai/api/v1"). 국내판 Responses 행(zhipu-bigmodel-responses)만 있고 국제판이 없다.
+
+## 라이브 확인 (2026-09-12, 사용자 키)
+
+    GET  https://api.z.ai/api/v1/models                    -> 200 (Codex 형식, slug/input_modalities)
+    POST https://api.z.ai/api/v1/responses  glm-5.3        -> 200
+    POST https://api.z.ai/api/v1/responses  glm-5.3-flash  -> 200
+    POST https://api.z.ai/api/v1/responses  glm-5.2        -> 200
+    POST https://api.z.ai/api/v1/responses  glm-5.1        -> 200
+    POST https://api.z.ai/api/v1/responses  glm-5          -> 200
+    POST https://api.z.ai/api/v1/responses  glm-4.6        -> 200
+    POST https://api.z.ai/api/v1/responses  glm-5-turbo    -> 200
+    POST https://api.z.ai/api/v1/chat/completions glm-5.3  -> 403 model_access_denied
+    POST https://api.z.ai/api/coding/paas/v4/chat/completions glm-5.3 -> 200
+
+두 가지가 확정된다. Responses 엔드포인트가 로스터 전체를 받으므로 전환은 모델 손실이 없다.
+그리고 두 와이어는 서로 다른 경로 접두를 쓰므로 한 baseUrl 로는 둘 다 맞출 수 없다.
+
+문서의 "Coding Plan 구독 이력 키는 Chat 으로만 접근 가능"이라는 문장은 이 키에 해당하지 않는다.
+
+## 설계
+
+한 행으로 통합한다. Responses 가 기본이고 Chat 은 opt-in 이며, Chat 이 받지 않는 모델은
+레지스트리가 Responses 로 고정한다. xAI 행과 방향이 같지는 않다 — 거기는 provider-wide Chat 에
+일부 모델만 modelWireDefaults 로 Responses 를 씌운다. 여기서는 반대로 provider-wide Responses 에
+Chat 을 opt-in 으로 둔다. 빌려오는 것은 modelWireDefaults 로 특정 모델의 와이어를 못박는 부분뿐이다.
+
+막히는 지점은 하나다. resolveWireProtocolOverride 는 adapter 만 바꾸고 baseUrl 은 그대로 둔다
+(src/server/adapter-resolve.ts:26-47). openai-chat 어댑터는 openaiChatCompletionsUrl(provider.baseUrl)
+로 URL 을 만들고(src/adapters/openai-chat.ts:99), openai-responses 어댑터만 provider.responsesPath
+라는 상대 경로 오버라이드를 갖는다(src/adapters/openai-responses.ts:2357-2362).
+즉 Responses 쪽에는 이미 경로 오버라이드가 있고 Chat 쪽에만 없다.
+
+그래서 responsesPath 의 대칭짝을 만든다.
+
+### NEW FIELD chatCompletionsPath
+
+MODIFY src/types/provider.ts — responsesPath 선언 바로 아래.
+
+    /**
+     * Relative send path for the openai-chat wire, mirroring responsesPath.
+     * Absent keeps openaiChatCompletionsUrl(baseUrl). Needed when one upstream serves
+     * Chat Completions and Responses under different path prefixes, so a per-model wire
+     * override cannot reach the right endpoint by swapping the adapter alone.
+     */
+    chatCompletionsPath?: string;
+
+MODIFY src/config.ts — responsesPath 검증과 같은 규칙을 재사용한다: 스킴 없는 상대 경로, "/" 로 시작,
+쿼리/프래그먼트 금지. providerResponsesPathConfigError 를 경로 이름만 받는 공용 함수로 일반화하고
+두 필드에 각각 적용한다.
+
+MODIFY src/adapters/openai-chat.ts — URL 조립을 responses 쪽과 같은 모양으로 바꾼다.
+
+    - return { url: openaiChatCompletionsUrl(provider.baseUrl), headers, hasCredential };
+    + const url = provider.chatCompletionsPath === undefined
+    +   ? openaiChatCompletionsUrl(provider.baseUrl)
+    +   : provider.baseUrl.replace(/\/$/, "") + provider.chatCompletionsPath;
+    + return { url, headers, hasCredential };
+
+responsesPath 가 실제로 흐르는 경로 전체를 대칭으로 따라가야 한다. 감사에서 확인된 지점이다.
+빠뜨리면 typecheck 가 즉시 깨지거나(auth-cors 의 satisfies Record<keyof OcxProviderConfig>)
+런타임에 필드가 사라져 Chat opt-in 이 https://api.z.ai/chat/completions 로 나간다.
+
+    src/providers/registry.ts:231    ProviderRegistryEntry 에 필드 선언
+    src/providers/registry.ts:363    ProviderConfigSeed Pick 목록
+    src/providers/derive.ts:18, :73  DerivedKeyLoginProvider / DerivedProviderPreset
+    src/providers/derive.ts:224, :259  providerConfigSeed (복사가 두 군데다)
+    src/providers/derive.ts:296      deriveKeyLoginMap
+    src/providers/derive.ts:480, :523  enrichProviderFromRegistry
+    src/providers/derive.ts:604      entryToPreset
+    src/router.ts:377-378            fill-if-absent 시딩
+    src/config.ts                    zod 스키마 + 경로 검증(responsesPath 규칙 재사용)
+    src/server/auth-cors.ts:801      필드 권한 맵에 "editor"
+    (대시보드 배선은 이 유닛에서 제외 — 아래 참고)
+    tests/server/config.test.ts:1476  허용/거절 검증 3건의 대칭
+
+openai-chat 쪽 URL 조립은 openAIChatTransport 한 곳(src/adapters/openai-chat.ts:99)이면 된다.
+116행과 1460행은 그 함수를 탄다.
+
+대시보드 payload/preset/모달은 이 변경에서 건드리지 않는다. router 의 fill-if-absent 가 라우팅 시점에
+필드를 채우므로 대시보드로 추가한 프로바이더도 올바른 경로로 나간다. 남는 차이는 손으로 만든 커스텀
+프로바이더의 디스크 설정에 필드가 남지 않는다는 것뿐이다. gui/ 아래 파일을 건드리면 PR 게이트가
+UI 스크린샷을 요구하는데 이 변경에는 보여 줄 시각적 변화가 없다. 에디터에 실제 입력 컨트롤을 붙이는
+후속 작업에서 스크린샷과 함께 가져간다.
+
+### NEW modelSuffixBracketStrip 을 Responses 어댑터에도 적용
+
+감사와 사전 조사가 일치한다. 이 플래그는 openai-chat.ts:119, :743, :1466 과 ollama-native.ts:214 에만
+있고 openai-responses.ts 에는 매치가 0건이다. zai 로스터는 glm-5.3[1m] 과 glm-5.2[1m] 를 포함하고,
+상류 실측에서 괄호 id 는 400 model_not_found 였다. 지금 상태로 Responses 를 기본으로 돌리면
+두 별칭이 기본 경로에서 죽는다.
+
+해결책은 둘이다. Responses buildRequest 에 스트립을 넣거나, 로스터에서 별칭을 뺀다.
+후자는 zai/glm-5.3[1m] 을 고른 기존 사용자 선택을 깨고 parity 테스트가 고정한 별칭 메타데이터
+(provider-registry-parity.test.ts:462, :490-504)까지 무너뜨린다. 결함 크기에 비해 파괴가 크다.
+전자를 택한다.
+
+삽입 지점은 감사가 정정했다. openai-responses 는 번역 어댑터가 없는 passthrough 라
+(adapters/registry.ts:90-94) body 를 parsed.modelId 로 다시 만들지 않고 parsed._rawBody 를 흘린다
+(openai-responses.ts:2373-2376). 라우터가 네이티브 id 를 _rawBody.model 에 써넣으므로
+(server/responses/core.ts:2492-2497) 괄호 별칭은 그 필드에 남는다. openai-chat 처럼 wire model 만
+건드리면 스트립이 조용히 무효가 된다.
+
+따라서 createResponsesPassthroughAdapter.buildRequest 안, JSON.stringify(finalBody)(:2544) 직전에
+provider.modelSuffixBracketStrip === true 이고 finalBody 가 plain object 이며 model 이 문자열일 때
+stripBracketedModelSuffix 를 적용한다. 이 한 지점이 HTTP 와 WebSocket outbound 를 모두 덮는다 —
+WS 는 어댑터가 URL/body 를 다시 만들지 않고 수송만 바꾼다(server/responses/fetch-helpers.ts:97-104).
+
+테스트는 기존 openai-chat-model-suffix.test.ts 헬퍼를 그대로 쓸 수 없다. 그 헬퍼(:7-14)는 _rawBody 가
+없어서 Responses 대칭 테스트에 넣으면 빈 body 가 된다. passthrough 테스트처럼 _rawBody 를 채운다.
+
+### MODIFY zai 행
+
+    id: "zai", label: "Z.AI — GLM Coding Plan",
+    baseUrl: "https://api.z.ai",
+    adapter: "openai-responses",
+    responsesPath: "/api/v1/responses",
+    chatCompletionsPath: "/api/coding/paas/v4/chat/completions",
+
+models 로스터는 유지한다. modelContextWindows 의 5.3 가족은 상류 카탈로그가 말하는 1_048_576 으로
+맞춘다(현재 1_000_000, 국내 Responses 행은 이미 1_048_576). modelInputModalities 는 020 에서 넣은
+ZAI_GLM_5X_INPUT_MODALITIES 를 그대로 쓴다. preserveResponsesReasoningContent 를 켜고,
+Chat 전용이던 preserveReasoningContentModels 는 유지한다(opt-in 한 사용자가 여전히 Chat 을 탄다).
+
+### Chat opt-in 과 Responses 고정
+
+opt-in 은 기존 수단을 그대로 쓴다: 사용자가 modelAdapters 에 "openai-chat" 을 적으면
+resolveWireProtocolOverride 가 어댑터를 바꾸고, 새 chatCompletionsPath 가 올바른 경로로 보낸다.
+
+Chat 이 받지 않는 모델은 레지스트리가 Responses 로 고정한다 — 다만 실측 결과 그런 모델이 없다.
+2026-09-12 에 coding/paas/v4 chat 경로로 로스터 전체를 던졌더니 glm-5.3 / glm-5.3-flash / glm-5.2 /
+glm-5.1 / glm-5 / glm-4.6 / glm-5-turbo 가 모두 200 이었다. 그래서 이번 변경에 modelWireDefaults 는
+넣지 않는다. 나중에 어느 모델이 Chat 에서 거절되면 그때 wire "openai-responses" 와
+inbound ["responses", "chat", "anthropic"] 로 선언하면 된다. grok-4.20-multi-agent 행 주석이 그 선례다.
+
+### 감사에서 정리된 사항
+
+- routedProviderConfig 는 매 요청 저장 설정을 레지스트리 값으로 덮는다(src/router.ts:375). 호스트가
+  api.z.ai 로 같으므로 키가 다른 호스트로 가지 않는다. quota 매핑도 https://api.z.ai 와 /api/v1 을
+  이미 허용한다(src/providers/quota.ts:348-356).
+- liveModels 는 켜지 않는다. 상류가 Codex 형식(models[] + slug)을 돌려주는데 ocx 라이브 발견은
+  OpenAI /models(data[] + id) 계약을 기대한다. 확인되지 않은 라이브 주장은 빈 피커를 만든다.
+- free-directory 의 glm id 는 별개다(src/providers/free-directory.ts:112). 계속
+  https://api.z.ai/api/coding/paas/v4 + openai-chat 에 남고 zai 전환을 따라가지 않는다.
+- Lab behavior fingerprint: behavior.ts 에 wire 키를 넣으려면 src/lab/subject/behavior-fingerprint.ts 의
+  CLOSED_KEYS(:5-6)에 같은 키를 등록해야 한다. 미분류 키는 normalizeBehaviorValues 가 런타임에 던지고
+  (:60) LabBehaviorValues 가 Record<string, ...> 라 typecheck 로는 안 잡힌다. wire.chatCompletionsPath 를
+  wire.responsesPath 와 나란히 등록한다.
+- #1100 destination 매칭: registryEntryForProviderDestination(registry.ts:3513-3524)은 adapter 와
+  정규화된 baseUrl 로 행을 찾는다. zai 를 openai-responses + https://api.z.ai 로 옮기면 구 Chat URL 을
+  가리키는 커스텀 프로바이더(예: 이름 "GLM")가 zai 메타데이터를 잃는다
+  (tests/codex-integration/codex-catalog.test.ts:6068-6075 가 그 계약을 고정한다).
+  구 Chat 엔드포인트를 destination alias 로 남겨서 기존 동작을 보존한다.
+- structure 문서 의무: 감사가 정정한 대로 structure/transports/responses.md:253 은 OpenCode Go URL 매처
+  문단이라 넣을 자리가 아니다. 갱신 대상은 같은 문서의 responsesPath 일반 계약 문단,
+  structure/data-planes/inbound-compat.md:8-10(현재 openaiChatCompletionsUrl 만 적혀 있다),
+  structure/config.md, structure/runtime.md:143-144. docs-site 는 guides/providers.md:457 의 zai baseUrl 과
+  reference/configuration/providers.md:144, reference/adapters.md:181 의 responsesPath 서술이 대상이다.
+- 이 변경은 020 이 넣는 ZAI_GLM_5X_INPUT_MODALITIES 상수를 쓴다. wp3 가 dev 에 들어간 뒤 올린다.
+
+## 테스트
+
+갱신이 필요한 기존 고정 테스트. 두 번째 감사가 좁혀 준 목록이다 — 초안은 과했다.
+
+    tests/providers/provider-registry-parity.test.ts:462   modelContextWindows 1_000_000 -> 1_048_576
+    tests/codex-integration/codex-catalog.test.ts:6068-6075  #1100 destination 계약
+    tests/server/config.test.ts:1476-1505                  responsesPath 검증의 대칭 3건 추가
+    tests/adapters/openai/openai-chat-model-suffix.test.ts:116-118  routed zai 스트립을 Responses 로
+    tests/gui/provider-payload.test.ts:195                 GUI 라운드트립 toEqual
+
+건드리지 않는다: parity :281 / :313 / :527 은 구 Chat URL 을 '낡은 저장 설정' 픽스처로 쓸 뿐 adapter/baseUrl 을
+단언하지 않는다. :512 는 131_072 라 무관하다. quota 테스트의 구 URL 은 매핑이 남아 있어 유효하다.
+zhipu-bigmodel-provider.test.ts:86/:91 은 glm 이 coding/paas/v4 에 남는다는 단언이라 그대로 둔다.
+
+MODIFY tests/providers/provider-registry-parity.test.ts
+
+    test("the Z.AI row defaults to Responses and keeps Chat reachable as an opt-in", () => {
+      const row = PROVIDER_REGISTRY.find(entry => entry.id === "zai");
+      expect(row?.adapter).toBe("openai-responses");
+      expect(row?.baseUrl).toBe("https://api.z.ai");
+      expect(row?.responsesPath).toBe("/api/v1/responses");
+      expect(row?.chatCompletionsPath).toBe("/api/coding/paas/v4/chat/completions");
+    });
+
+NEW tests/adapters/openai/openai-chat-path-override.test.ts — chatCompletionsPath 가 있을 때와
+없을 때의 최종 URL 을 고정하고, modelAdapters 로 openai-chat 을 opt-in 한 zai 라우트가
+coding/paas/v4 경로로 나가는지 end-to-end 로 확인한다.
+
+경로가 tests/adapters 루트가 아니라 tests/adapters/openai 인 이유는 layout 규칙이다:
+scripts/test-layout/layout.json 의 자식 규칙이 ^(?:openai)- 를 adapters/openai 로 보낸다.
+AGENTS.md 대로 새 파일은 layout.json 의 explicit 과 tests/fixtures/test-layout-expected.json 양쪽에
+"openai-chat-path-override.test.ts": "adapters/openai" 를 등록해야 한다.
+
+## 검증
+
+    bun test tests/providers/provider-registry-parity.test.ts tests/adapters
+    bun run typecheck
+    bun run test
diff --git a/devlog/_plan/260912_zcode_protocol_and_catalog/evidence/zai-responses-models.json b/devlog/_plan/260912_zcode_protocol_and_catalog/evidence/zai-responses-models.json
new file mode 100644
index 0000000000..9f5f462daf
--- /dev/null
+++ b/devlog/_plan/260912_zcode_protocol_and_catalog/evidence/zai-responses-models.json
@@ -0,0 +1,115 @@
+{
+  "models": [
+    {
+      "apply_patch_tool_type": "freeform",
+      "base_instructions": "",
+      "context_window": 1048576,
+      "default_reasoning_level": "max",
+      "default_reasoning_summary": "none",
+      "description": "Z.ai's latest flagship model",
+      "display_name": "glm-5.3",
+      "effective_context_window_percent": 95,
+      "experimental_supported_tools": [],
+      "input_modalities": [
+        "text"
+      ],
+      "max_context_window": 1048576,
+      "priority": 0,
+      "shell_type": "shell_command",
+      "slug": "glm-5.3",
+      "support_verbosity": false,
+      "supported_in_api": true,
+      "supported_reasoning_levels": [
+        {
+          "description": "Light reasoning",
+          "effort": "low"
+        },
+        {
+          "description": "Enhanced reasoning",
+          "effort": "high"
+        },
+        {
+          "description": "Deep reasoning",
+          "effort": "max"
+        }
+      ],
+      "supports_parallel_tool_calls": true,
+      "supports_reasoning_summaries": true,
+      "truncation_policy": {
+        "limit": 10000,
+        "mode": "bytes"
+      },
+      "visibility": "list"
+    },
+    {
+      "apply_patch_tool_type": "freeform",
+      "base_instructions": "",
+      "context_window": 1048576,
+      "default_reasoning_level": "max",
+      "default_reasoning_summary": "none",
+      "description": "Fast multimodal coding model",
+      "display_name": "glm-5.3-flash",
+      "effective_context_window_percent": 95,
+      "experimental_supported_tools": [],
+      "input_modalities": [
+        "text",
+        "image"
+      ],
+      "max_context_window": 1048576,
+      "priority": 1,
+      "shell_type": "shell_command",
+      "slug": "glm-5.3-flash",
+      "support_verbosity": false,
+      "supported_in_api": true,
+      "supported_reasoning_levels": [
+        {
+          "description": "Light reasoning",
+          "effort": "low"
+        },
+        {
+          "description": "Enhanced reasoning",
+          "effort": "high"
+        },
+        {
+          "description": "Deep reasoning",
+          "effort": "max"
+        }
+      ],
+      "supports_parallel_tool_calls": true,
+      "supports_reasoning_summaries": true,
+      "truncation_policy": {
+        "limit": 10000,
+        "mode": "bytes"
+      },
+      "visibility": "list"
+    },
+    {
+      "apply_patch_tool_type": "freeform",
+      "base_instructions": "",
+      "context_window": 204800,
+      "default_reasoning_level": "max",
+      "default_reasoning_summary": "none",
+      "description": "Agent-optimized model",
+      "display_name": "glm-5-turbo",
+      "effective_context_window_percent": 95,
+      "experimental_supported_tools": [],
+      "input_modalities": [
+        "text"
+      ],
+      "max_context_window": 204800,
+      "priority": 2,
+      "shell_type": "shell_command",
+      "slug": "glm-5-turbo",
+      "support_verbosity": false,
+      "supported_in_api": true,
+      "supported_reasoning_levels": [],
+      "supports_parallel_tool_calls": true,
+      "supports_reasoning_summaries": true,
+      "truncation_policy": {
+        "limit": 10000,
+        "mode": "bytes"
+      },
+      "visibility": "list"
+    }
+  ]
+}
\ No newline at end of file
diff --git a/docs-site/src/components/Landing.astro b/docs-site/src/components/Landing.astro
index 222057ce33..bbb71b13ae 100644
--- a/docs-site/src/components/Landing.astro
+++ b/docs-site/src/components/Landing.astro
@@ -86,7 +86,7 @@ const fr = {
 	'ocx claude launches Claude Code against the same port — every routed model in the /model picker, auto-context up to 1M, roster sub-agents, and your claude.ai login stays active.': 'ocx claude lance Claude Code sur le même port : tous les modèles routés figurent dans le sélecteur /model, le contexte automatique atteint 1 M, la liste de sous-agents est disponible et votre connexion claude.ai reste active.',
 	'Claude Code running a routed model through opencodex — gpt-5.6-luna-medium active in the status bar': 'Claude Code exécutant un modèle routé par opencodex, avec gpt-5.6-luna-medium actif dans la barre d’état',
 	'Search & vision sidecars': 'Services auxiliaires de recherche et de vision',
-	'Give non-OpenAI models real web search and image understanding through a gpt-5.4-mini sidecar.': 'Ajoutez aux modèles autres qu’OpenAI une véritable recherche web et la compréhension des images grâce à un service auxiliaire gpt-5.4-mini.',
+	'Give non-OpenAI models real web search and image understanding through a gpt-5.6-luna sidecar.': 'Ajoutez aux modèles autres qu’OpenAI une véritable recherche web et la compréhension des images grâce à un service auxiliaire gpt-5.6-luna.',
 	'ocx init writes a provider into your Codex config and shares one model catalog with Codex CLI, TUI, App, and SDK. ocx stop restores native Codex cleanly.': 'ocx init ajoute un fournisseur à votre configuration Codex et partage un catalogue de modèles unique entre Codex CLI, TUI, App et SDK. ocx stop restaure proprement Codex dans son état natif.',
 	'Documentation map': 'Plan de la documentation',
 	'Explore the docs': 'Explorer la documentation',
@@ -317,7 +317,7 @@ const docsMap = [
 			</article>
 			<article class="lp-cell">
 				<h3><svg class="lp-ico" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d={icons.search} /></svg>{t('Search & vision sidecars', '검색 & 비전 사이드카', '搜索与视觉边车', 'Сайдкары поиска и зрения', '検索 & ビジョンサイドカー', '搜尋與視覺邊車', 'Arama & görme sidecar’ları')}</h3>
-				<p>{t('Give non-OpenAI models real web search and image understanding through a gpt-5.4-mini sidecar.', 'gpt-5.4-mini 사이드카로 비 OpenAI 모델에 실제 웹 검색과 이미지 이해를 붙입니다.', '通过 gpt-5.4-mini 边车，让非 OpenAI 模型获得真实的网页搜索与图像理解能力。', 'Дайте моделям не от OpenAI настоящий веб-поиск и понимание изображений через сайдкар gpt-5.4-mini.', 'gpt-5.4-mini サイドカーで非 OpenAI モデルに本物のウェブ検索と画像理解を提供します。', '透過 gpt-5.4-mini 邊車，讓非 OpenAI 模型獲得真實的網頁搜尋與圖像理解能力。', 'gpt-5.4-mini sidecar’ı sayesinde OpenAI harici modellere gerçek web araması ve görsel anlama yeteneği kazandırın.')}</p>
+				<p>{t('Give non-OpenAI models real web search and image understanding through a gpt-5.6-luna sidecar.', 'gpt-5.6-luna 사이드카로 비 OpenAI 모델에 실제 웹 검색과 이미지 이해를 붙입니다.', '通过 gpt-5.6-luna 边车，让非 OpenAI 模型获得真实的网页搜索与图像理解能力。', 'Дайте моделям не от OpenAI настоящий веб-поиск и понимание изображений через сайдкар gpt-5.6-luna.', 'gpt-5.6-luna サイドカーで非 OpenAI モデルに本物のウェブ検索と画像理解を提供します。', '透過 gpt-5.6-luna 邊車，讓非 OpenAI 模型獲得真實的網頁搜尋與圖像理解能力。', 'gpt-5.6-luna sidecar’ı sayesinde OpenAI harici modellere gerçek web araması ve görsel anlama yeteneği kazandırın.')}</p>
 			</article>
 			<article class="lp-cell lp-cell-terminal">
 				<h3><svg class="lp-ico" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d={icons.code} /></svg>{t('Quickstart', '퀵스타트', '快速开始', 'Быстрый старт', 'クイックスタート', '快速入門', 'Hızlı Başlangıç')}</h3>
diff --git a/docs-site/src/content/docs/fr/getting-started/quickstart.md b/docs-site/src/content/docs/fr/getting-started/quickstart.md
index 79cce13afa..984294b476 100644
--- a/docs-site/src/content/docs/fr/getting-started/quickstart.md
+++ b/docs-site/src/content/docs/fr/getting-started/quickstart.md
@@ -74,7 +74,7 @@ codex -m "ollama-cloud/glm-5.2"      "Write a SQL migration"
 ## Choisissez des modèles de sous-agents (facultatif)
 
 Une nouvelle configuration propose cinq modèles natifs dans le sélecteur de sous-agents de Codex : `gpt-5.5`,
-`gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` et `gpt-5.4-mini`. Ouvrez `ocx gui` pour remplacer ou
+`gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` et `gpt-6-astra`. Ouvrez `ocx gui` pour remplacer ou
 réorganiser jusqu’à cinq modèles natifs ou routés. Le tableau de bord peut également définir un modèle de sous-agent
 préféré et un effort de raisonnement. Consultez [Interface des sous-agents](/fr/guides/sub-agent-surface/)
 pour choisir v1, base ou v2 et comprendre quand s’appliquent les instructions, les valeurs natives par défaut et les replis.
diff --git a/docs-site/src/content/docs/fr/guides/claude-code.md b/docs-site/src/content/docs/fr/guides/claude-code.md
index e11e6a06d8..65d1a39a45 100644
--- a/docs-site/src/content/docs/fr/guides/claude-code.md
+++ b/docs-site/src/content/docs/fr/guides/claude-code.md
@@ -623,3 +623,5 @@ par défaut par un contenu minimal (`blockedSkills: ["claude-api"]`).
 **Les sous-agents sont envoyés au mauvais modèle** — Les agents de la liste (`ocx-*`) utilisent les directives
 `<!-- ocx-route: ... -->`, et non l'argument `model` de l'outil Agent. Vérifiez que la directive désigne la route voulue.
 Utilisez `"haiku"` comme valeur de remplacement pour le modèle.
+
+Dans `config.json`, `claudeCode.stabilizePromptCache: true` déplace les notices Claude reconnues en fin des instructions système vers un dernier message utilisateur sur les routes traduites. La valeur par défaut est `false`. Activez cette option seulement si ce changement de rôle convient à vos clients. Les exemples dans des blocs de code et le texte non reconnu sont conservés ; le transfert Anthropic natif reste inchangé. Sans métadonnées, la clé de cache suit les instructions stabilisées. Cette option ne crée pas une identité de conversation et ne garantit aucun succès du cache amont.
diff --git a/docs-site/src/content/docs/fr/guides/codex-app-models.md b/docs-site/src/content/docs/fr/guides/codex-app-models.md
index fb81b9597e..10dce00320 100644
--- a/docs-site/src/content/docs/fr/guides/codex-app-models.md
+++ b/docs-site/src/content/docs/fr/guides/codex-app-models.md
@@ -130,8 +130,8 @@ service OpenAI.
 
 ## Couverture stable actuelle des modèles
 
-L'ensemble natif de secours comprend `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.3-codex-spark` et GPT-5.6
-Sol/Terra/Luna. Pour la famille GPT-5.5/5.4, opencodex conserve les entrées dynamiques plus riches du
+L'ensemble natif de secours comprend `gpt-5.5`, `gpt-5.3-codex-spark` et GPT-5.6
+Sol/Terra/Luna. Pour la famille GPT-5.5, opencodex conserve les entrées dynamiques plus riches du
 catalogue Codex installé et ne synthétise qu'une entrée manquante. L'instantané amont fourni n'est employé
 que pour GPT-5.6, auquel il apporte l'identité et les métadonnées réelles de chaque modèle plutôt qu'une
 approximation fondée sur un ancien modèle d'entrée.
diff --git a/docs-site/src/content/docs/fr/guides/codex-integration.md b/docs-site/src/content/docs/fr/guides/codex-integration.md
index e8a4deae4f..57b5b63fde 100644
--- a/docs-site/src/content/docs/fr/guides/codex-integration.md
+++ b/docs-site/src/content/docs/fr/guides/codex-integration.md
@@ -375,7 +375,7 @@ délégation v1/base/v2 et de ses mécanismes de repli.
 
 ## Préchauffage des comptes Codex
 
-L’ajout ou la réauthentification vérifie normalement le compte avant son enregistrement par une petite requête attendant `response.completed`. Le modèle par défaut est `gpt-5.4-mini`, avec un essai sur `gpt-5.5` et `gpt-5.6-luna` en cas de HTTP 400 ou HTTP 404. Les erreurs publiques contiennent des catégories fixes, sans corps de réponse brut.
+L’ajout ou la réauthentification vérifie normalement le compte avant son enregistrement par une petite requête attendant `response.completed`. Le modèle par défaut est `gpt-5.6-luna`, avec un essai sur `gpt-5.5` en cas de HTTP 400 ou HTTP 404. Les erreurs publiques contiennent des catégories fixes, sans corps de réponse brut.
 
 Si la lecture authentifiée des quotas avec le nouveau jeton OAuth confirme un quota de 5 heures, hebdomadaire ou mensuel épuisé, le compte est enregistré sans appel au modèle et affiche **Validation en attente**. Il reste exclu du routage après un redémarrage ou un renouvellement du jeton. Après récupération du quota, actualisez les quotas : une lecture récente et complète avec de la capacité disponible permet une petite requête de validation. Seule sa réussite active le compte. Tout échec conserve la restriction. Les lectures passives ne déclenchent pas cette requête. Un quota inconnu à l’inscription conserve la vérification habituelle.
 
@@ -397,7 +397,7 @@ Un renouvellement du compte principal qui n'aboutit pas répond toujours `503` a
 ocx config set codexPool '{"excludedPlans":["free"]}'
 ```
 
-C'est une politique de sélection, pas un blocage. Un compte écarté conserve ses identifiants, son historique de quota et son affinité de thread, reste visible dans la liste des comptes et demeure joignable par sélection explicite comme `work/gpt-5.4`. Seule la rotation automatique cesse de le choisir, y compris lorsqu'il est déjà le compte actif ou déjà lié à un thread — l'état exact que laisse un abonnement expiré.
+C'est une politique de sélection, pas un blocage. Un compte écarté conserve ses identifiants, son historique de quota et son affinité de thread, reste visible dans la liste des comptes et demeure joignable par sélection explicite comme `work/gpt-5.5`. Seule la rotation automatique cesse de le choisir, y compris lorsqu'il est déjà le compte actif ou déjà lié à un thread — l'état exact que laisse un abonnement expiré.
 
 Deux limites volontaires. Le compte Codex principal n'est jamais écarté par forfait, car le routage en mode sélection seule ne lit pas son forfait dans les identifiants natifs protégés ; une règle le couvrant se contredirait. Et lorsqu'il ne reste aucun compte non écarté, le compte écarté répond quand même au lieu d'échouer : mettre tous les comptes en pause reste le moyen d'arrêter complètement le service. Il n'existe pas de `minimumPlan`, car classer les forfaits ChatGPT entre eux exige un ordre total qui n'existe pas ici.
 
@@ -416,3 +416,9 @@ ocx restore back # point plain Codex at the running proxy again
 Lorsque opencodex s'exécute comme [service d'arrière-plan géré](/fr/reference/cli/lifecycle/#ocx-service-installrepairstartstopstatusuninstallremove), il définit
 `OCX_SERVICE=1` afin qu'un redémarrage déclenché par le service ne modifie **pas** sans cesse la configuration
 Codex. Seule l'exécution explicite de `ocx stop` ou `ocx service stop` restaure Codex natif.
+
+## Refus de sécurité pour l’historique paginé
+
+Une transition de fournisseur peut renvoyer `history_paginated_requires_native_writer` si le stockage concerné prend en charge la pagination, même pour ses lignes legacy. OpenCodex conserve configuration, profil, catalogue, historique et preuves de restauration au lieu d’attribuer des numéros hors de Codex. Les sorties sans transition, comme la préservation d’un fournisseur externe, restent disponibles.
+
+Ne supprimez pas un fournisseur encore référencé, ne répétez pas `ocx sync` ou une restauration legacy et ne réécrivez pas un historique actif. Conservez les fichiers, fermez la conversation avant toute récupération et signalez l’erreur exacte et les versions sans publier de données privées. Utilisez un correctif vérifié coordonné avec le processus natif d’écriture. Une sauvegarde ou le succès d’un script ne prouve pas le rétablissement de l’affichage : vérifiez la conversation après réouverture de Codex.
diff --git a/docs-site/src/content/docs/fr/guides/combos.md b/docs-site/src/content/docs/fr/guides/combos.md
index 9785135d53..9073372327 100644
--- a/docs-site/src/content/docs/fr/guides/combos.md
+++ b/docs-site/src/content/docs/fr/guides/combos.md
@@ -190,6 +190,8 @@ indique la réinitialisation de fenêtre à venir la plus proche (cinq heures, h
 Le fournisseur dont le quota se renouvelle en premier est ainsi sollicité. Les cibles dépourvues de données de quota
 récentes et les égalités conservent l’ordre de configuration. `weight` et `stickyLimit` n’affectent pas cette stratégie.
 
+Ce classement et l’exclusion des fournisseurs avant l’envoi exigent des limites récentes d’inférence de modèles applicables dans leur ensemble à l’unique clé API actuelle. Les résumés OAuth ou du compte courant, les routes transmettant les identifiants de l’appelant, les configurations à plusieurs clés et les instantanés dont les identifiants ou la destination ont changé servent uniquement à l’affichage pour cette décision préalable. Il en va de même lorsque les en-têtes `Authorization`, `x-api-key` ou `x-goog-api-key` remplacent les identifiants ; les fenêtres réservées à la recherche ou à MCP sont exclues. Si aucune cible admissible n’a de réinitialisation applicable, l’ordre de configuration prévaut. La sélection des comptes et les nouvelles tentatives appliquent toujours leurs limites habituelles.
+
 ## Que se passe-t-il lorsqu'une cible échoue
 
 Les échecs d’un combo se répartissent entre ceux qui entraînent un **basculement** et les échecs **terminaux**.
@@ -279,9 +281,7 @@ Ouvrez le tableau de bord local et choisissez **Modèles → Combos**. L'espace
 combos, et son sélecteur de cible exclut les modèles désactivés et les combos imbriqués.
 
 Chaque cible affiche aussi un badge de quota en direct : **Disponible**, **Quota épuisé** ou **Quota inconnu**.
-Enregistrer et Créer ne sont désactivés que lorsque chaque cible activée dispose de preuves fraîches et complètes
-que son quota est épuisé. Les données manquantes, obsolètes, mal formées ou agrégées de façon incomplète restent
-inconnues et ne verrouillent jamais un contrôle. La récupération du quota réactive automatiquement l’action.
+L’éditeur bloque Enregistrer et Créer pour une raison de quota uniquement lorsque chaque cible utilisable dispose d’une confirmation serveur encore valide indiquant que la limite d’inférence liée à ses identifiants configurés est épuisée. Les quotas de compte, de modèle, de recherche et de MCP fournis uniquement à titre d’affichage, ainsi que les informations de routage absentes ou expirées, ne déclenchent pas ce blocage. Le blocage expire à la réinitialisation applicable ou à l’expiration de la validité des données et fait l’objet d’une nouvelle vérification lorsque la page devient active ou visible ; Actualiser recharge à la fois les données des combos et les quotas.
 
 ### CLI
 
diff --git a/docs-site/src/content/docs/fr/guides/integrations.md b/docs-site/src/content/docs/fr/guides/integrations.md
index 9dd4e5bc2e..831a7dbaef 100644
--- a/docs-site/src/content/docs/fr/guides/integrations.md
+++ b/docs-site/src/content/docs/fr/guides/integrations.md
@@ -1,10 +1,10 @@
 ---
 title: Intégrations
-description: Connectez opencodex à OpenCode, Pi, OMP, Hermes, OpenClaw, Kimi Code, Gajae Code, DeepSeek Harness, MiniMax Code, ZCode, Prime Agent, Aside et Raycast depuis le tableau de bord — un commutateur par client, avec une sauvegarde avant chaque écriture.
+description: Connectez opencodex à OpenCode, Pi, OMP, Hermes, OpenClaw, Kimi Code, gjc, DeepSeek Harness, MiniMax Code, ZCode, Prime Agent, Aside, Raycast et omo depuis le tableau de bord — un commutateur par client, avec une sauvegarde avant chaque écriture.
 ---
 
 L'onglet **Intégrations** écrit le bloc fournisseur d'opencodex dans le fichier de configuration du client,
-puis peut le retirer. Treize clients fonctionnent ainsi, chacun avec son propre commutateur :
+puis peut le retirer. Quinze clients fonctionnent ainsi, chacun avec son propre commutateur :
 
 | Client | Fichier de configuration | Format | Prise d'effet de la modification | Identifiant |
 |---|---|---|---|---|
@@ -14,13 +14,15 @@ puis peut le retirer. Treize clients fonctionnent ainsi, chacun avec son propre
 | Hermes | `~/.hermes/config.yaml` | YAML | dans les nouvelles sessions | `OPENCODEX_HERMES_API_KEY` |
 | OpenClaw | `~/.openclaw/openclaw.json` | JSON5 | immédiatement, sur une passerelle en cours d'exécution | `OPENCODEX_OPENCLAW_API_KEY` |
 | Kimi Code | `~/.kimi-code/config.toml` | TOML | au redémarrage ou avec `/reload` | valeur fictive de bouclage |
-| Gajae Code | `~/.gjc/agent/models.yml` | YAML | dans les nouvelles sessions ou à l'ouverture de `/model` |`OPENCODEX_GAJAE_API_KEY` |
+| gjc | `~/.gjc/agent/models.yml` | YAML | dans les nouvelles sessions ou à l'ouverture de `/model` |`OPENCODEX_GAJAE_API_KEY` |
 | DeepSeek Harness (DSH) | `$DSH_HOME/settings.yaml` (`~/.dsh/settings.yaml` par défaut) | YAML | rechargement à chaud | jeton porteur fictif et non secret pour le bouclage |
 | MiniMax Code | `~/.minimax/config.yaml` | YAML | dans les nouvelles sessions ou après l’ouverture du sélecteur de modèles | valeur fictive de bouclage |
 | Prime Agent | `~/.prime/agent/models.json` | JSON | dans les nouvelles sessions | valeur fictive de bouclage |
 | ZCode | `~/.zcode/v2/config.json` | JSON | au redémarrage | valeur fictive de bouclage |
 | Aside | `~/.aside/u/<account>/models.json` | JSON | après avoir quitté complètement puis rouvert Aside | valeur fictive de bouclage |
 | Raycast | `~/.config/raycast/ai/providers.yaml` | YAML | immédiatement à l'enregistrement — Raycast surveille le fichier | aucun — bouclage uniquement |
+| omo | `~/.omo/agent/models.json` | JSON | nouvelles sessions | espace réservé de bouclage |
+| Cline CLI | `~/.cline/data/settings/providers.json` + `models.json` | JSON | après arrêt et redémarrage | bouclage uniquement |
 
 La prise en charge gérée de DSH exige au minimum **DSH 0.1.0-rc.6**. OpenCodex ne possède que le fragment
 `llm-pi-ai.providers.opencodex` : **Appliquer** et **Actualiser** remplacent ce fragment, **Désactiver** ne
@@ -128,7 +130,7 @@ niveaux. Dans ces cas, le commutateur est verrouillé afin que rien ne soit modi
 **OMP, DSH et Hermes** ne sont pas affectés non plus par les modifications voisines, mais pour une autre raison : leurs outils
 d'écriture ne modifient, octet par octet, que leur propre plage `providers.opencodex` ; le reste du fichier
 n'est jamais réécrit. Pour les autres formats susceptibles de contenir des commentaires (OpenClaw,
-Kimi Code, Gajae Code, MiniMax Code et Raycast — documents YAML, JSON5 et TOML réécrits en entier), ou lorsque les propres entrées
+Kimi Code, gjc, MiniMax Code et Raycast — documents YAML, JSON5 et TOML réécrits en entier), ou lorsque les propres entrées
 d'opencodex ont été modifiées, le commutateur se verrouille et la désactivation est refusée plutôt que de
 deviner quelles modifications vous appartiennent.
 
@@ -154,7 +156,7 @@ les convertirait en chaînes entre guillemets, y compris dans les tableaux et le
 tables en ligne. Les dates déjà écrites entre guillemets restent prises en charge.
 Pour conserver une date typée sans guillemets, modifiez manuellement la configuration.
 
-**Pi, Kimi Code, Gajae Code, MiniMax Code et l'intégration DSH gérée fonctionnent uniquement avec une adresse de
+**Pi, Kimi Code, gjc, MiniMax Code et l'intégration DSH gérée fonctionnent uniquement avec une adresse de
 bouclage.** Les quatre premiers n'ont aucun champ de configuration pour l'en-tête `x-opencodex-api-key`
 qu'exige une liaison hors bouclage. DSH possède une table d'en-têtes générique, mais rc.6 ne documente pas
 cet en-tête d'admission dédié comme contrat d'intégration pris en charge ; l'outil d'écriture géré échoue
@@ -205,8 +207,8 @@ ocx mcode
 ```
 
 Une fois l’intégration connectée, `ocx sync` et `POST /api/sync` actualisent les catalogues MCode,
-Pi, Aside et Raycast gérés. Le démarrage du proxy actualise aussi le catalogue Raycast géré.
-Les changements de visibilité, de fournisseur ou de préréglage actualisent Pi, Aside et Raycast.
+Pi, Aside, Raycast et omo gérés. Le démarrage du proxy actualise aussi le catalogue Raycast géré.
+Les changements de visibilité, de fournisseur ou de préréglage actualisent Pi, Aside, Raycast et omo.
 Les blocs absents, modifiés par un tiers, non sûrs ou supprimés manuellement restent intacts ;
 réactivez explicitement l’intégration lorsque vous souhaitez la reconnecter.
 
@@ -233,3 +235,15 @@ commande refuse et vous l'indique : remplacer vos modifications plus récentes r
 Les détails des clients ont été vérifiés par rapport au format de configuration propre à chaque projet ;
 consultez les notes de recherche dans
 `devlog/_fin/260802_client_toggle_api/002_client_toggle_matrix.md` pour savoir ce qui a été contrôlé et quand.
+
+## Cline CLI
+
+Cline CLI utilise providers.json et models.json. Quittez Cline avant toute modification ou synchronisation, puis redémarrez-le. Annuler restaure les deux originaux. Le fournisseur par défaut reste inchangé. Cette intégration ne migre pas le stockage des anciennes extensions VS Code.
+
+```bash
+ocx integration client enable --client cline
+ocx integration client history --client cline
+ocx integration client restore --op <operation-id>
+```
+
+[CLI / rollback / CLINE_PROVIDER_SETTINGS_PATH](/guides/integrations/#cline-cli).
diff --git a/docs-site/src/content/docs/fr/guides/model-ordering.md b/docs-site/src/content/docs/fr/guides/model-ordering.md
index b22bf9b827..fab755afdf 100644
--- a/docs-site/src/content/docs/fr/guides/model-ordering.md
+++ b/docs-site/src/content/docs/fr/guides/model-ordering.md
@@ -124,7 +124,7 @@ au-delà de ce bloc mis en avant :
 ```json
 {
   "modelPickerOrder": [
-    "tyler/deepseek-v4-pro",
+    "tyler/deepseek-v4-flash",
     "jd-chat/kimi-k3",
     "jd-chat/glm-5.2"
   ]
diff --git a/docs-site/src/content/docs/fr/guides/providers.md b/docs-site/src/content/docs/fr/guides/providers.md
index 0b36b95a92..20cd9a79f5 100644
--- a/docs-site/src/content/docs/fr/guides/providers.md
+++ b/docs-site/src/content/docs/fr/guides/providers.md
@@ -96,8 +96,11 @@ Le catalogue du transfert ChatGPT ajoute également les identifiants non qualifi
 
 Huit préréglages de fournisseurs utilisent une connexion OAuth. GitHub Copilot s'y ajoute au moyen d'un pont
 expérimental et non officiel reposant sur un flux d'autorisation d'appareil. opencodex enregistre leurs identifiants dans
-`~/.opencodex/auth.json` et les actualise automatiquement. La CLI de connexion accepte également `chatgpt` ;
-elle obtient un identifiant ChatGPT tout en créant une entrée de fournisseur en mode `forward`.
+`~/.opencodex/auth.json` et les actualise automatiquement. La CLI de connexion accepte également
+`ocx login codex`, qui n'est pas l'un des fournisseurs ci-dessus : la commande est routée vers la
+connexion au pool de comptes Codex (le même flux que `ocx account login codex`). Ce pool tient son
+propre registre de comptes, donc cette route nécessite un proxy en cours d'exécution. `chatgpt` et
+`openai` sont des alias de la même route.
 
 ```bash
 ocx login xai          # xAI Grok
@@ -108,8 +111,9 @@ ocx login kiro         # import kiro-cli credentials (or token fallback)
 ocx login google-antigravity
 ocx login cursor       # standalone Cursor PKCE login
 ocx login command-code # Command Code browser OAuth (or import ~/.commandcode/auth.json)
+ocx login devin       # Connexion navigateur Auth0 Cognition/Devin
 ocx login github-copilot  # GitHub device flow → Copilot token (Copilot Pro/Business)
-ocx login chatgpt      # standalone ChatGPT OAuth login
+ocx login codex        # pool de comptes Codex (alias : chatgpt, openai ; nécessite un proxy en cours d'exécution)
 ocx logout <provider>
 ```
 
@@ -122,6 +126,8 @@ ocx logout <provider>
 | `kiro` | `kiro` | `https://runtime.us-east-1.kiro.dev` | La connexion initiale importe la session de l'installation locale de `kiro-cli`, déjà authentifiée (sous Unix, installez avec `curl -fsSL https://cli.kiro.dev/install` &#124; `bash`; sous Windows PowerShell, utilisez `irm 'https://cli.kiro.dev/install.ps1'` &#124; `iex`; puis exécutez `kiro-cli login`). **Ajouter un compte** déconnecte `kiro-cli`, lance une nouvelle connexion dans le navigateur qui change le compte utilisé par `kiro-cli`, puis enregistre les métadonnées propres au profil. Les comptes OpenCodex existants sont préservés ; une annulation ou un échec restaure la session `kiro-cli` précédente. |
 | `google-antigravity` | `google` | `https://daily-cloudcode-pa.googleapis.com` | Google OAuth avec le protocole Cloud Code Assist. La découverte en direct utilise le point de terminaison CCA authentifié `v1internal:fetchAvailableModels` et publie les modèles d'agent accessibles au compte connecté ; le catalogue maintenu reste la solution de repli. |
 | `cursor` | `cursor` | `https://api2.cursor.sh` | Connexion PKCE expérimentale, transport HTTP/2 en direct et découverte de modèles filtrés par compte. |
+| `devin` | `devin` | `https://server.codeium.com` | Passerelle Cognition/Devin non officielle et expérimentale. La connexion ouvre l'authentification Auth0 dans le navigateur, puis échange le jeton via `RegisterUser` contre une clé d'API durable. Les modèles sont découverts par compte avec `GetCascadeModelConfigs` ; le streaming passe uniquement par `runTurn` sur Connect-RPC. Absente du préréglage du tableau de bord par défaut. |
+| `devin-cli` | `devin` | `https://server.codeium.com` | Importe l'identifiant que votre Devin CLI installé détient déjà (`devin auth login` l'écrit dans son propre `credentials.toml`), puis diffuse via l'api-server Connect-RPC de Cognition comme le fournisseur `devin` — sans connexion navigateur ni clé à coller. La liste des modèles et les fenêtres de contexte proviennent du catalogue de votre compte. Pour la boucle d'agent locale du CLI (ACP stdio), utilisez une entrée nommée différemment avec `"adapter": "devin-cli"`. |
 | `github-copilot` | `openai-chat` | `https://api.githubcopilot.com` | Expérimental. Flux d'appareil GitHub et échange `copilot_internal` (client OAuth de VS Code). Nécessite un abonnement Copilot actif ; il ne s'agit pas d'une API tierce officielle. |
 
 Les vérifications de quota Google Antigravity utilisent des points de terminaison Google fixes, y compris le repli vers la liste des modèles. Elles prennent en charge le DNS Fake-IP transparent pour ces destinations en conservant la vérification TLS, le refus des redirections et les contrôles des adresses privées. Une URL de base personnalisée ne modifie que les requêtes de modèles ; `NO_PROXY` conserve la politique de connexion directe.
@@ -213,7 +219,8 @@ identifiants de compte expurgés, aucun jeton. `ocx doctor` ajoute une section s
 contrôles du magasin accessible en écriture et de l'appel unique, ainsi que des lignes WARN qui indiquent une
 action de récupération. Lorsqu'un compte de fournisseur OAuth doit être réauthentifié, exécutez
 `ocx login <provider>` ou utilisez **Réauthentifier** dans le tableau de bord. Les comptes du pool Codex ne
-constituent pas un fournisseur `ocx login` : réauthentifiez-les dans le groupe de comptes Codex du tableau de bord. Consultez
+font pas partie de ces fournisseurs, mais `ocx login codex --reauth` est routé vers leur réauthentification
+dans le pool de comptes, ce que fait aussi le pool de comptes Codex du tableau de bord. Consultez
 [`ocx status` / `ocx doctor`](/fr/reference/cli/) dans la référence CLI.
 
 ### Importation des identifiants Kiro
@@ -366,7 +373,7 @@ modèle ; les flux mal formés ou partiels sont fermés comme incomplets, et non
 > des ressources d'embedding, d'image, de vidéo et de 3D, la passerelle Coding renvoie le même catalogue étendu,
 > et la passerelle Agent Plan ne possède aucune ressource `/models`. Le modèle par défaut de la route facturée à
 > l'usage est `doubao-seed-2-1-pro-260628` ; son catalogue sélectionné comprend également les modèles de texte
-> DeepSeek et GLM actuels. Coding Plan utilise `ark-code-latest` par défaut, et Agent Plan `deepseek-v4-pro`.
+> DeepSeek et GLM actuels. Coding Plan utilise `ark-code-latest` par défaut, et Agent Plan `deepseek-v4-flash`.
 
 > **Restriction d'utilisation des forfaits Volcengine :** selon la documentation de Volcengine, les quotas
 > Coding Plan et Agent Plan ne sont valables que dans les outils de programmation par IA pris en charge. Elle
@@ -600,7 +607,7 @@ native d'Ollama (`POST /api/chat`) plutôt que via la surface compatible OpenAI,
 liste des modèles auprès du fournisseur : les nouveaux modèles Ollama Cloud apparaissent sans
 modifier la configuration. opencodex classe les modèles cloud selon leurs
 capacités visuelles, afin que le [service auxiliaire de vision](/fr/guides/sidecars/) n'intervienne que pour les modèles
-exclusivement textuels. Ces derniers, par exemple `glm-5.2`, `deepseek-v4-pro`, `gpt-oss`, `qwen3-coder`,
+exclusivement textuels. Ces derniers, par exemple `glm-5.2`, `deepseek-v4-flash`, `gpt-oss`, `qwen3-coder`,
 `minimax-m2.x` et `nemotron-3-*`, figurent dans `noVisionModels` ; les modèles à vision native, comme
 `kimi-k2.6`, `minimax-m3`, `gemma4`, `qwen3.5` et `gemini-3-flash-preview`, n'y figurent pas. La correspondance
 tolère les balises `:size` d'Ollama : `gpt-oss` couvre donc `gpt-oss:120b` et `gpt-oss:20b`.
diff --git a/docs-site/src/content/docs/fr/guides/sidecars.md b/docs-site/src/content/docs/fr/guides/sidecars.md
index b778c4c99e..367b98d9c3 100644
--- a/docs-site/src/content/docs/fr/guides/sidecars.md
+++ b/docs-site/src/content/docs/fr/guides/sidecars.md
@@ -93,7 +93,7 @@ modèle couvert par le sidecar. Les combos annoncent l'entrée image seulement l
 nativement ou via un sidecar, et que le paramètre `imageInput` du combo n'est pas désactivé, afin que des clients comme
 l'application Codex autorisent les pièces jointes au lieu de les bloquer avant l'exécution du sidecar. Lorsque
 `visionSidecar.model` est absent ou vide, le chemin d'exécution OpenAI, le tableau de bord et l'API de gestion
-utilisent le modèle de repli `gpt-5.4-mini`. Au démarrage, une ancienne valeur `gpt-5.4-mini` explicitement enregistrée
+utilisent le modèle de repli `gpt-5.6-luna`. Au démarrage, une ancienne valeur `gpt-5.6-luna` explicitement enregistrée
 est toujours migrée vers `gpt-5.6-luna` ; cette migration s'applique à une valeur stockée, et non à l'absence du
 champ du modèle.
 
@@ -146,7 +146,7 @@ Un modèle est marqué en texte uniquement par fournisseur :
   "providers": {
     "ollama-cloud": {
       "baseUrl": "https://ollama.com/v1",
-      "noVisionModels": ["glm-5.2", "gpt-oss", "qwen3-coder", "deepseek-v4-pro"]
+      "noVisionModels": ["glm-5.2", "gpt-oss", "qwen3-coder", "deepseek-v4-flash"]
     }
   }
 }
diff --git a/docs-site/src/content/docs/fr/guides/sub-agent-surface.md b/docs-site/src/content/docs/fr/guides/sub-agent-surface.md
index 14bf8bb0d3..a5b172a4e4 100644
--- a/docs-site/src/content/docs/fr/guides/sub-agent-surface.md
+++ b/docs-site/src/content/docs/fr/guides/sub-agent-surface.md
@@ -191,7 +191,7 @@ Utilisez `ocx agent` pour les paramètres de délégation, de liste, de plafond
 ocx agent status
 ocx agent injection set --model anthropic/claude-sonnet-5 --effort xhigh
 ocx agent subagents set gpt-5.6-sol,anthropic/claude-sonnet-5
-ocx agent fallback set gpt-5.4-mini,xai/grok-4.5 --poll-ms 60000
+ocx agent fallback set gpt-5.6-luna,xai/grok-4.5 --poll-ms 60000
 ocx agent effort set --subagent max
 ```
 
diff --git a/docs-site/src/content/docs/fr/reference/adapters.md b/docs-site/src/content/docs/fr/reference/adapters.md
index 2b33a26e2e..9adb60f68b 100644
--- a/docs-site/src/content/docs/fr/reference/adapters.md
+++ b/docs-site/src/content/docs/fr/reference/adapters.md
@@ -144,6 +144,16 @@ Si Kiro s’arrête sans appeler l’outil d’achèvement, l’adaptateur effec
 - Envoie les niveaux ordinaires de `cursor/grok-4.5` avec les identifiants de protocole exacts issus de la découverte en direct de Cursor (`cursor-grok-4.5-low`, `-medium` ou `-high`). `cursor/grok-4.5-fast` reste sélectionnable, mais le modèle canonique `grok-4.5` est envoyé avec des paramètres distincts `effort` et `fast=true`.
 - L’exécution locale native de commandes sur le système de fichiers, le shell ou le réseau par Cursor est refusée par défaut. Les intégrations explicites `mcpServers` et `desktopExecutor` disposent d’activations distinctes ; `nativeLocalExec: "on"` active l’exécuteur intégré plus large et contourne la sémantique d’approbation et de bac à sable de Codex. L’ancien réglage `unsafeAllowNativeLocalExec: true` reste équivalent uniquement lorsque `nativeLocalExec` n’est pas défini.
 
+## `devin`
+
+**Cible :** `exa.api_server_pb.ApiServerService/GetChatMessage` de Cognition, en streaming Connect sur `server.codeium.com`.
+**Authentification :** clé d'API Devin/Cognition issue de `provider.apiKey` ou de l'en-tête authorization transmis. La connexion ouvre l'authentification Auth0 dans le navigateur, puis échange le jeton via `SeatManagementService.RegisterUser` contre une clé durable.
+
+- Utilise `runTurn` plutôt que le chemin fetch/parse ordinaire. Les requêtes et les événements serveur passent par le cadrage protobuf manuel de `devin/cloud-direct/wire.ts`.
+- Les modèles sont découverts par compte avec `GetCascadeModelConfigs` ; ceux qui ne figurent pas dans l'offre disparaissent de la liste au lieu d'échouer au moment de la requête.
+- Cognition impose une limite de longueur sur les descriptions d'outils et une liste de phrases interdites. L'adaptateur réécrit les formulations connues et tronque les descriptions trop longues.
+- Les clés ne se renouvellent pas. Relancez `ocx login devin` lorsqu'une clé expire ou est révoquée.
+
 ## `azure-openai` (alias : `azure`)
 
 **Cibles :** **Azure OpenAI**. Encapsule `openai-responses` (et utilise donc également `passthrough: true`).
diff --git a/docs-site/src/content/docs/fr/reference/cli/agents.md b/docs-site/src/content/docs/fr/reference/cli/agents.md
index 749119f70a..0d781042d9 100644
--- a/docs-site/src/content/docs/fr/reference/cli/agents.md
+++ b/docs-site/src/content/docs/fr/reference/cli/agents.md
@@ -164,7 +164,7 @@ Gérez et appliquez la clôture du modèle Grok Build.
 
 ## Exportation de la configuration client
 
-### `ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|prime|aside|raycast>`
+### `ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|prime|aside|raycast|omo>`
 
 Imprimez une configuration client connectée au proxy en cours d'exécution. La commande sérialise le
 bloc fournisseur `opencodex` — URL de base, liste de modèles et référence d’identifiant du client
@@ -175,7 +175,7 @@ les modèles Codex peuvent actuellement voir.
 
 | Option | Actions |
 | --- | --- |
-| `--client <opencode\|pi\|omp\|hermes\|openclaw\|kimi\|gajae\|dsh\|mcode\|zcode\|prime\|aside\|raycast>` | Requis. Sélectionne le dialecte de configuration client. |
+| `--client <opencode\|pi\|omp\|hermes\|openclaw\|kimi\|gajae\|dsh\|mcode\|zcode\|prime\|aside\|raycast\|omo>` | Requis. Sélectionne le dialecte de configuration client. |
 | `--json` | Imprimez le document généré en tant que JSON sur la sortie standard pour les scripts. Il s'agit de JSON même lorsque le format natif du client sélectionné est YAML, TOML ou JSON5. |
 | `--out <path>` | Écrivez le format de configuration natif du client dans `<path>`. Refuse de remplacer un fichier existant. |
 | `--force` | Autoriser `--out` à remplacer un fichier existant. |
@@ -205,7 +205,9 @@ propres valeurs par défaut à ces lignes.
 | `mcode` | `~/.minimax/config.yaml` (`MINIMAX_DATA_DIR`, puis l'ancien `MAVIS_DATA_DIR`, l'emportent une fois définis ; une valeur relative est refusée) | `mcode-config.yaml` | aucun — espace réservé de bouclage |
 | `zcode` | `~/.zcode/v2/config.json` (`ZCODE_DATA_DIR` l'emporte une fois défini ; une valeur relative est refusée) | `config.json` | aucun — espace réservé de bouclage |
 | `prime` | `~/.prime/agent/models.json` (`PRIME_AGENT_CODING_AGENT_DIR` l'emporte une fois défini ; une valeur relative est refusée) | `prime-models.json` | aucun — espace réservé de bouclage |
+| `aside` | `~/.aside/u/<account>/models.json` pour le compte que le fichier `accounts.json` d'Aside désigne comme courant ; un manifeste illisible est refusé plutôt que de retomber sur un compte | `aside-models.json` | aucun — espace réservé de bouclage |
 | `raycast` | `~/.config/raycast/ai/providers.yaml`, sur macOS comme sur Windows (Raycast n'honore pas `XDG_CONFIG_HOME`) | `raycast-providers.yaml` | aucun — bouclage uniquement, aucune entrée `api_keys` n'est écrite |
+| `omo` | `~/.omo/agent/models.json` (`OMO_CODING_AGENT_DIR`, puis `SENPI_CODING_AGENT_DIR`, puis `PI_CODING_AGENT_DIR` l'emportent dans cet ordre une fois définis ; une valeur relative est refusée) | `omo-models.json` | aucun — espace réservé de bouclage |
 
 L'exportation Raycast est un document `providers.yaml` autonome contenant un seul élément `id: opencodex`
 dans la séquence `providers` : `name: OpenCodex`, l'URL de base `/v1` du proxy et chaque modèle routé avec
@@ -241,8 +243,8 @@ le proxy se lie au-delà du bouclage ; voir
 [Accès à distance](/fr/reference/configuration/server/#accès-à-distance) pour savoir comment les clés d'admission sont délivrées. Clés pour
 les fournisseurs en amont eux-mêmes sont une chose entièrement distincte, configurée par
 [Fournisseurs](/fr/guides/providers/).
-Gajae est l'exception : `OPENCODEX_GAJAE_API_KEY` remplit ses informations d'identification de fournisseur à partir du
-environnement, mais son schéma ne peut pas envoyer l'en-tête d'admission à distance, donc le Gajae généré
+gjc est l'exception : `OPENCODEX_GAJAE_API_KEY` remplit ses informations d'identification de fournisseur à partir du
+environnement, mais son schéma ne peut pas envoyer l'en-tête d'admission à distance, donc l'intégration gjc générée
 l'intégration reste uniquement en boucle.
 
 La même charge utile est servie par `GET /api/client-config` et rendue sur l'onglet API du tableau de bord, donc
diff --git a/docs-site/src/content/docs/fr/reference/cli/providers-accounts.md b/docs-site/src/content/docs/fr/reference/cli/providers-accounts.md
index ac4e42bbc2..b28642e0ca 100644
--- a/docs-site/src/content/docs/fr/reference/cli/providers-accounts.md
+++ b/docs-site/src/content/docs/fr/reference/cli/providers-accounts.md
@@ -70,9 +70,11 @@ de fournisseurs OAuth et à clé API actuellement acceptés.
 
 Utilisez la même commande pour **réauthentifier** après `ocx status` / `ocx doctor` rapports
 réauthentification requise ou échec de l'actualisation du terminal (ou utilisez Réauthentifier dans le tableau de bord).
-Les comptes du groupe Codex ne constituent pas un fournisseur public pour `ocx login` : réauthentifiez-vous
-plutôt depuis le groupe de comptes Codex du tableau de bord (**Réauthentifier**) ou avec le flux non
-interactif `ocx account reauth`.
+Les comptes du pool Codex ne font pas partie des fournisseurs OAuth ou API-key ci-dessus, mais
+`ocx login codex` les atteint : la commande est routée vers la connexion au pool de comptes, si bien que
+`ocx login codex --reauth` équivaut à `ocx account reauth codex`. Le pool de comptes Codex du tableau de
+bord (**Réauthentifier**) fait de même. Cette route s'exécute dans le proxy, elle en exige donc un en
+cours d'exécution.
 
 ```bash
 ocx login xai
@@ -103,7 +105,7 @@ Répertoriez et changez de compte de fournisseur et de pools de clés API via le
 la surface est :
 
 ```text
-Usage: ocx account <list|current|use|refresh|auto-switch|priority|login|reauth|code|cancel|remove|add-key|reset-credits> ...
+Usage: ocx account <list|current|use|refresh|auto-switch|priority|login|reauth|code|cancel|remove|add-key|reset-credits|grok-reset-coupons> ...
 
 list [provider]     Codex account pool, OAuth accounts and API keys (identifiers shown masked as the API returns them).
 current <provider>  Show the active account or key.
@@ -115,6 +117,7 @@ remove <provider> <id> --yes  Remove a stored account or key after an existence
 add-key <provider> [--label <label>]  Add a key read only from piped stdin.
 login/reauth/code/cancel  Run browser or manual-code auth from a headless shell.
 reset-credits <id|main> [--consume --yes]  Inspect or consume Codex reset credits.
+grok-reset-coupons [<id>] [--consume --yes] [--token-id <token-id>] [--operation-id <uuid>]  Inspect or redeem Grok reset coupons.
 Switching the active account takes effect immediately; running threads move on their next request, and in-flight requests keep the account they captured.
 A selection-order change applies from the next unbound request and never moves a bound thread.
 ```
@@ -206,11 +209,11 @@ renvoient 1 ; une sonde de quota en amont qui échoue ou expire produit plutôt
 
 ### `ocx account auto-switch <provider> <on|off|status|threshold <0-100>> [--json]`
 
-Contrôle le seuil du pool Codex `openai`, ou enregistre celui d’un pool OAuth générique. `on` enregistre 80 %, `off` 0 % et `threshold <n>` accepte 0–100. Les seuils génériques sont actuellement inactifs : leur sauvegarde ne change ni le basculement par seuil, ni l’activation du fournisseur, ni la rotation réactive après une erreur 429. Pour les pools génériques, les sorties utilisent la réponse confirmée du serveur. Pour un pool générique, `poolEnabled` est le réglage enregistré (`null` signifie non spécifié), pas l’état effectif hérité. `inert: true` indique que le seuil ne s’applique pas ; une capacité inconnue ne produit jamais `enabled: true`. Les fournisseurs à clé API, Anthropic et les valeurs invalides sont refusés.
+Contrôle le seuil du pool Codex `openai`, ou enregistre celui d’un pool OAuth générique. `on` enregistre 80 %, `off` 0 % et `threshold <n>` accepte 0–100. Un seuil générique n’oriente la sélection que si `pool.kernel` est activé avec `strategy: "fill-first"` ; le drapeau désactivé, sa sauvegarde n’active pas le basculement par seuil. Dans les deux cas, elle ne change ni l’activation du fournisseur, ni la rotation réactive après une erreur 429. Pour les pools génériques, les sorties utilisent la réponse confirmée du serveur. Pour un pool générique, `poolEnabled` est le réglage enregistré (`null` signifie non spécifié), pas l’état effectif hérité. `inert: true` indique un seuil enregistré mais non appliqué, `inert: false` un seuil que le pool applique réellement. L’absence d’`inert` signale une capacité inconnue, qui ne produit jamais `enabled: true`. Les fournisseurs à clé API, Anthropic et les valeurs invalides sont refusés.
 
 ```text
 openai: { provider, autoSwitchThreshold: number, enabled: boolean }
-generic OAuth: { provider, autoSwitchThreshold: number | null, enabled: boolean, poolEnabled: boolean | null, inert: true | null }
+generic OAuth: { provider, autoSwitchThreshold: number | null, enabled: boolean, poolEnabled: boolean | null, inert: boolean | null }
 ```
 
 ### `ocx account priority <provider> <account-id|main> [<-100..100|first|earlier|normal|later|last|reset>] [--json]`
@@ -283,6 +286,26 @@ security find-generic-password -w openrouter | ocx account add-key openrouter --
 Inspectez Codex réinitialiser les crédits d'un compte. Consommer un crédit est destructeur et nécessite à la fois
 `--consume` et `--yes`.
 
+### `ocx account grok-reset-coupons [<account-id>] [--consume --yes [--token-id <id>] [--operation-id <uuid>]] [--json]`
+
+Inspecte les coupons de réinitialisation restants ou en échange un pour un compte xAI / Grok.
+
+Sans `--consume`, la commande renvoie les jetons de coupon disponibles et leurs fenêtres de validité :
+
+```bash
+ocx account grok-reset-coupons
+ocx account grok-reset-coupons acc_xai_01 --json
+```
+
+Échanger un coupon de réinitialisation modifie l'état de facturation et épuise définitivement un jeton de coupon. `--consume` exige strictement `--yes` :
+
+```bash
+ocx account grok-reset-coupons --consume --yes
+ocx account grok-reset-coupons --consume --yes --token-id <token-id>
+```
+
+Passez `--operation-id <uuid>` (doit être un UUIDv4 valide) pour garantir une règlement idempotent. En cas de coupure réseau ou de nouvelle tentative, des identifiants d'opération identiques rejouent le résultat enregistré de manière durable au lieu de consommer un second coupon.
+
 ### `ocx account main <subcommand>`
 
 Gérez les profils de connexion principale natifs nommés Codex sans modifier le routage du groupe de comptes OpenCodex :
diff --git a/docs-site/src/content/docs/fr/reference/configuration/agents.md b/docs-site/src/content/docs/fr/reference/configuration/agents.md
index 4f04a20d44..03e289e3e9 100644
--- a/docs-site/src/content/docs/fr/reference/configuration/agents.md
+++ b/docs-site/src/content/docs/fr/reference/configuration/agents.md
@@ -67,9 +67,9 @@ opencodex ignore les candidats désactivés, non routables, en mauvais état, en
   "injectionModel": "gpt-5.5",
   "injectionEffort": "high",
   "syncCodexSubagentDefaults": true,
-  "subagentModelFallback": ["gpt-5.4-mini"],
+  "subagentModelFallback": ["gpt-5.6-luna"],
   "subagentModelFallbackByModel": {
-    "gpt-5.5": ["gpt-5.4-mini"]
+    "gpt-5.5": ["gpt-5.6-luna"]
   },
   "subagentModelFallbackPollMs": 60000,
   "subagentEffortCap": "high"
diff --git a/docs-site/src/content/docs/fr/reference/configuration/providers.md b/docs-site/src/content/docs/fr/reference/configuration/providers.md
index c7879dfa9c..576b13c1bb 100644
--- a/docs-site/src/content/docs/fr/reference/configuration/providers.md
+++ b/docs-site/src/content/docs/fr/reference/configuration/providers.md
@@ -38,8 +38,9 @@ Après une inscription ou une connexion OAuth dans l’interface, une boîte de
 | `activeCodexAccountId?` | `string` | — | Compte de pool sélectionné manuellement pour la prochaine demande. La sélection efface l'affinité des threads ; les demandes en cours conservent les informations d’identification capturées. |
 | `codexAccountPriorities?` | `Record<string, number>` | — | Ordre de sélection par compte pour le pool Codex : identifiant de compte → entier de `-100` à `100`, **les valeurs élevées sont prioritaires**, une valeur absente équivaut à `0`. Cette limite porte sur le classement, et non sur l'admissibilité : la sélection retient, parmi les comptes déjà admissibles, le niveau prioritaire le plus élevé qui dispose encore d'une marge de quota, puis `accountPoolStrategy` choisit un compte dans ce niveau. Un niveau est ignoré uniquement lorsque chacun de ses membres dépasse `autoSwitchThreshold`, est en temporisation, est temporairement évité, est suspendu ou doit être réauthentifié ; un quota inconnu ne suffit jamais à considérer un niveau comme épuisé. L'ordre ne rend jamais admissible un compte qui ne l'est pas et ne réaffecte jamais une tâche déjà liée à un compte. Le compte principal `__main__` participe selon les mêmes règles ; la connexion Codex Desktop peut ainsi être configurée pour être utilisée en dernier. Sans entrée, le pool se comporte exactement comme auparavant. Un mappage mal formé est ignoré avec un avertissement dans la console : l'ordre est désactivé et la configuration n'est pas réparée. Ce champ est géré par `ocx account priority` et la page Codex Auth. |
 | `activeCodexAccountPinned?` | `string` | — | Identifiant du compte du dernier opérateur sélectionné manuellement. Lorsqu'il est défini, un niveau `codexAccountPriorities` supérieur ne peut pas le préempter jusqu'à ce que la broche soit libérée par drainage, exclusion, suppression ou un failover/promotion explicite. Un mouvement circulaire ordinaire à l’intérieur du niveau plafonné ne le libère pas. L'écriture d'une entrée `codexAccountPriorities` libère également le pin, donc un pin créé avant qu'un ordre n'existe ne peut pas surpasser un ensemble par la suite. `GET /api/codex-auth/active` indique à la fois si le compte effectif est épinglé (`pinned`) et le compte portant le plafond (`pinnedAccountId`). |
-| `autoSwitchThreshold?` | `number` | `80` | Seuil d'utilisation pour la commutation proactive. `quota` peut réévaluer les tâches liées et non liées lors de leur prochaine requête ; `fill-first` ne l'utilise que comme seuil d'évacuation pour l'affectation des requêtes non liées ; la sélection `round-robin` normale ne l'utilise pas. Le score retient la plus élevée des fenêtres de quota connues sur 5 heures, une semaine ou 30 jours. `0` désactive uniquement la commutation proactive fondée sur l'utilisation, pas l'affectation des requêtes non liées ni la récupération après incident. |
-| `accountPoolStrategy?` | `"quota" \| "round-robin" \| "fill-first"` | `"quota"` | Stratégie d'affectation des requêtes Codex nouvelles ou non liées. Une requête est non liée lorsqu'elle ne possède aucune affinité active, définie par l'identifiant de la tâche parente et la portée du quota ; une tâche existante visible peut perdre son lien après le redémarrage du proxy ou la réinitialisation de l'affinité. `quota` sélectionne le compte admissible le moins utilisé lorsqu'aucun compte actif n'existe, conserve un compte actif admissible sous `autoSwitchThreshold` et, une fois le seuil franchi, peut déplacer une requête non liée ou relier de manière proactive une tâche liée à un compte admissible moins utilisé. `round-robin` répartit équitablement les requêtes non liées ; `fill-first` continue de les attribuer au compte actif jusqu'à sa temporisation, son indisponibilité ou le seuil d'évacuation configuré. |
+| `autoSwitchThreshold?` | `number` | `80` | Seuil d'utilisation pour la commutation proactive. `quota` peut réévaluer les requêtes non liées lors de leur prochaine requête et, par défaut, réévalue aussi les tâches liées une fois ce seuil franchi. Avec `pool.cacheAffinity` activé, une tâche liée conserve son compte au-delà du seuil jusqu'à ce que ce compte soit épuisé ou ne puisse plus servir. `fill-first` ne l'utilise que comme seuil d'évacuation pour l'affectation des requêtes non liées ; la sélection `round-robin` normale ne l'utilise pas. Le score retient la plus élevée des fenêtres de quota connues sur 5 heures, une semaine ou 30 jours. `0` désactive uniquement la commutation proactive fondée sur l'utilisation, pas l'affectation des requêtes non liées ni la récupération après incident. |
+| `accountPoolStrategy?` | `"quota" \| "round-robin" \| "fill-first"` | `"quota"` | Stratégie d'affectation des requêtes Codex nouvelles ou non liées. Une requête est non liée lorsqu'elle ne possède aucune affinité active, définie par l'identifiant de la tâche parente et la portée du quota ; une tâche existante visible peut perdre son lien après le redémarrage du proxy ou la réinitialisation de l'affinité. `quota` sélectionne le compte admissible le moins utilisé lorsqu'aucun compte actif n'existe, conserve un compte actif admissible sous `autoSwitchThreshold` et, une fois le seuil franchi, peut déplacer une requête non liée. Sauf si `pool.cacheAffinity` est activé, il peut aussi relier de manière proactive une tâche liée à un compte admissible moins utilisé. Avec ce drapeau, la tâche liée reste jusqu'à ce que son compte soit épuisé (utilisation connue à 100 %) ou ne puisse plus servir. `round-robin` répartit équitablement les requêtes non liées ; `fill-first` continue de les attribuer au compte actif jusqu'à sa temporisation, son indisponibilité ou le seuil d'évacuation configuré. |
+| `pool.cacheAffinity?` | `boolean` | `false` | Ordre d'affinité de cache optionnel pour les threads Codex liés, indépendant de `pool.kernel`. Désactivé par défaut ; une valeur mal formée est lue comme désactivée. Une fois activé, une liaison active prime sur la marge de quota : `quota` ne déplace pas le thread simplement parce que l'utilisation a franchi `autoSwitchThreshold`. Le thread quitte encore le compte s'il ne peut plus servir — suspendu, inutilisable, ou réellement épuisé (utilisation connue à 100 %) — l'affinité est donc un réordonnancement, pas un verrouillage. |
 | `accountPoolStickyLimit?` | `number` | `1` | Nombre d'affectations de tâches nouvelles ou non liées conservées sur une même sélection tournante avant de passer à la suivante ; le compteur avance lorsqu'une tâche est liée, et non après une réponse réussie en amont. Plage : 1–100. |
 | `upstreamFailoverThreshold?` | `number` | `3` | Nombre d'échecs transitoires consécutifs avant le basculement des futures nouvelles sessions. Réglez `0` pour désactiver ce mécanisme. Pour les requêtes Responses ordinaires et les envois compacts natifs, les échecs avérés d'accessibilité DNS/TCP avant connexion sont suivis au niveau du couple fournisseur-hôte : ils n'affectent jamais l'état ni la temporisation du compte, l'affinité de tâche ou de session, la sélection du compte actif ou le routage du pool, et ne sont jamais comptabilisés dans ce seuil. |
 | `upstreamHostCircuitThreshold?` | `number` | `0` | Seuil facultatif du coupe-circuit pour les échecs DNS/TCP avérés avant connexion sur les requêtes Responses OpenAI natives en mode transfert et les envois compacts. `0` le désactive ; `1`–`20` ouvre, après ce nombre de requêtes logiques arrivées à leur terme, une temporisation de 30 secondes propre à l'origine du fournisseur. Tant que le circuit est ouvert, les requêtes reçoivent `503` avec `Retry-After` avant la sélection du compte ou l'envoi en amont ; après la temporisation, une requête est admise en état semi-ouvert. Les délais d'attente et les réponses HTTP ne sont jamais comptabilisés, et toute réponse HTTP ferme le circuit. Ce mécanisme s'applique uniquement au routage du pool Codex sans compte épinglé ; il reste inactif pour `codexAccountMode: "direct"` et les sélecteurs qualifiés par compte. |
@@ -129,6 +130,7 @@ sauvegarde dont le contenu diffère, puis réécrit en identifiants sans préfix
 | `noTopPModels?` | `string[]` | Modèles qui rejettent `top_p` spécifié par l’appelant. |
 | `noPenaltyModels?` | `string[]` | Modèles qui rejettent les pénalités presence/frequency. |
 | `noStructuredOutputModels?` | `string[]` | ID de modèle exact dont le point final `openai-chat` rejette `response_format`. Seule une correspondance exacte du modèle demandé omet le champ ; la traduction à sortie structurée reste activée pour tous les autres modèles `openai-chat`. |
+| `noJsonSchemaModels?` | `string[]` | ID de modèle exact dont le point final `openai-chat` rejette un `response_format` `json_schema` mais accepte encore `json_object`. Une telle requête est rétrogradée vers `json_object` au lieu d’être supprimée, donc un appelant qui demande du JSON en reçoit toujours. `noStructuredOutputModels` l’emporte quand un modèle figure dans les deux listes. Les préréglages `opencode go`, `opencode zen` et `opencode free` l’embarquent pour leurs routes DeepSeek. |
 | `parallelToolCalls?` | `boolean` | Contrôler les appels d’outils parallèles. Pour `openai-chat`, ils sont activés par défaut ; `false` envoie explicitement `parallel_tool_calls: false`. Les autres adaptateurs ne les annoncent que lorsque la valeur vaut explicitement `true`. |
 | `terminalContinuationGuard?` | `boolean` | Active, pour un fournisseur `openai-chat`, une relance interne bornée lorsqu’un tour exploitable annonce une action puis s’arrête proprement sans appel d’outil. La valeur par défaut est `false`, et une valeur explicite `false` équivaut à l’absence du champ. Les tentatives de combinaison et les tours de compactage routés sont exclus ; les autres adaptateurs ignorent cette option. |
 | `responsesItemIdRepair?` | `{ message?: string[]; reasoning?: string[]; repairMissingTerminalIds?: boolean; repairInvalidIds?: boolean }` | Réparation SSE en aval désactivée par défaut pour les identifiants d'espace réservé exacts, les identifiants de terminal manquants et (avec `repairInvalidIds`) les identifiants message/reasoning manquant du préfixe canonique `msg_`/`rs_`. Les identifiants d’appel de fonction ne sont jamais réécrits. Le DeepSeek intégré active les deux derniers par défaut. |
@@ -181,8 +183,8 @@ Deux accommodements fake-IP DNS existent pour les utilisateurs de Clash / Surge
 Utilisez **Codex Auth** dans le tableau de bord pour ajouter des comptes au groupe et actualiser les quotas. `config.json` stocke les
 métadonnées non secrètes ; les jetons d'accès et d'actualisation utilisent le magasin d'identifiants renforcé. Le routage du pool
 distingue l'affectation des requêtes nouvelles ou non liées, la commutation proactive fondée sur l'utilisation et la récupération après incident. Une tâche liée
-conserve normalement son affinité, mais `quota` peut la relier lors de sa requête suivante une fois le seuil d'utilisation
-franchi ; la suspension, la temporisation, la réauthentification et la gestion des échecs peuvent, indépendamment, effacer ou déplacer son routage.
+conserve normalement son affinité. Par défaut, `quota` peut la relier lors de sa requête suivante une fois le seuil d'utilisation
+franchi ; avec `pool.cacheAffinity` activé, cette réaffectation attend que le compte lié soit épuisé ou ne puisse plus servir. La suspension, la temporisation, la réauthentification et la gestion des échecs peuvent, indépendamment, effacer ou déplacer son routage.
 Une requête non liée ne possède aucune liaison active à un compte ; il peut s'agir d'une tâche existante visible après le redémarrage
 du proxy ou la réinitialisation de l'affinité. Un 429 ou un 402 reçu avant le début de la diffusion déclenche une nouvelle tentative unique sur un
 autre compte admissible au sein de la même requête, même lorsque la commutation proactive fondée sur l'utilisation est désactivée. Les changements de
@@ -202,7 +204,7 @@ et suspend uniquement ceux dont l'utilisation vient d'être confirmée à 100 %
 
 | Stratégie | Comportement |
 | --- | --- |
-| `quota` (par défaut) | S'il n'existe aucun compte actif, choisir le compte admissible le moins utilisé selon les fenêtres de 5 heures, d'une semaine et de 30 jours. Sinon, conserver un compte actif admissible sous `autoSwitchThreshold` ; une fois le seuil franchi, une requête non liée ou la requête suivante d'une tâche liée peut être déplacée vers un compte admissible moins utilisé. `0` désactive cette réévaluation fondée sur l'utilisation, mais pas la récupération après incident. |
+| `quota` (par défaut) | S'il n'existe aucun compte actif, choisir le compte admissible le moins utilisé selon les fenêtres de 5 heures, d'une semaine et de 30 jours. Sinon, conserver un compte actif admissible sous `autoSwitchThreshold` ; une fois le seuil franchi, une requête non liée peut être déplacée vers un compte admissible moins utilisé, et la requête suivante d'une tâche liée aussi sauf si `pool.cacheAffinity` est activé. Avec ce drapeau, l'affinité de cache prime sur la marge de quota et la tâche liée reste jusqu'à ce que le compte soit épuisé (utilisation connue à 100 %) ou ne puisse plus servir (suspendu, inutilisable). `0` désactive cette réévaluation fondée sur l'utilisation, mais pas la récupération après incident. |
 | `round-robin` | Répartit uniformément les requêtes non liées entre les comptes admissibles. `autoSwitchThreshold` ne modifie pas la sélection circulaire normale. `accountPoolStickyLimit` (1–100) compte les affectations effectuées avec une même sélection, et non les réponses réussies en amont. |
 | `fill-first` | Attribue les requêtes non liées au compte actif jusqu'à sa temporisation, sa réauthentification ou le seuil d'évacuation configuré ; une utilisation inconnue n'impose pas de changement. Les tâches liées et saines conservent leur affinité. |
 
@@ -251,7 +253,7 @@ Les entrées `codexAccounts[]` exigent `id`, `email` et `isMain` ; `plan`,
 | `failureBackoffMaxSeconds?` | `number` | `3600` | Plafond du délai d'attente et délai après un échec permanent. |
 | `codexWarmupEnabled?` | `boolean` | `false` | Active la validation synthétique des comptes du pool Codex. |
 | `codexWarmupMaxAgeSeconds?` | `number` | `691200` | Revalidez un compte après 8 jours. |
-| `codexWarmupModel?` | `string` | `gpt-5.4-mini` | Modèle natif utilisé pour l'échauffement facultatif. |
+| `codexWarmupModel?` | `string` | `gpt-5.6-luna` | Modèle natif utilisé pour l'échauffement facultatif. |
 
 ## Points de terminaison du fournisseur fixes
 
@@ -513,7 +515,7 @@ le nom actuel avant d'effectuer une autre modification.
       "baseUrl": "https://ollama.com/v1",
       "apiKey": "${OLLAMA_API_KEY}",
       "defaultModel": "glm-5.2",
-      "noVisionModels": ["glm-5.2", "glm-5.3", "gpt-oss", "qwen3-coder", "deepseek-v4-pro"]
+      "noVisionModels": ["glm-5.2", "glm-5.3", "gpt-oss", "qwen3-coder", "deepseek-v4-flash"]
     }
   },
   "subagentModels": ["anthropic/claude-opus-5", "ollama-cloud/glm-5.2"],
diff --git a/docs-site/src/content/docs/fr/reference/configuration/server.md b/docs-site/src/content/docs/fr/reference/configuration/server.md
index 27fd80b36a..d957d9b50f 100644
--- a/docs-site/src/content/docs/fr/reference/configuration/server.md
+++ b/docs-site/src/content/docs/fr/reference/configuration/server.md
@@ -240,7 +240,7 @@ une garde d'inactivité, pas un délai de génération total.
 | --- | --- | --- | --- |
 | `enabled?` | `boolean` | activé lorsqu'il est utilisable | Commutateur principal de description d'images. |
 | `backend?` | `"openai" \| "anthropic"` | automatique | La valeur explicite prévaut ; si elle est omise, un identifiant OAuth Anthropic stocké et utilisable est privilégié, sinon `openai`. |
-| `model?` | `string` | dépendant du backend | `gpt-5.4-mini` pour OpenAI ou `claude-sonnet-5` pour Anthropic. |
+| `model?` | `string` | dépendant du backend | `gpt-5.6-luna` pour OpenAI ou `claude-sonnet-5` pour Anthropic. |
 | `maxDescriptionsPerTurn?` | `number` | `8` | Nouvelles descriptions des ratés du cache admises par tour principal. `0` désactive les appels ; les valeurs non valides utilisent la valeur par défaut. |
 | `timeoutMs?` | `number` | `45000` | Délai d'expiration de la récupération par le service auxiliaire. Entier 1–2147483647. |
 
diff --git a/docs-site/src/content/docs/fr/reference/management-api.md b/docs-site/src/content/docs/fr/reference/management-api.md
index 0732df6dca..d50b11a50c 100644
--- a/docs-site/src/content/docs/fr/reference/management-api.md
+++ b/docs-site/src/content/docs/fr/reference/management-api.md
@@ -78,11 +78,21 @@ résultats propres à chaque route, sans répéter ce tableau.
 | `GET /api/grok` | Lire l'état de la configuration Grok gérée et les modèles candidats | 400 échec de lecture de l'état |
 | `PUT /api/grok/selection` | Persister les modèles Grok exclus | 400 sélection invalide ou surdimensionnée |
 | `POST /api/grok/apply` | Appliquer la configuration Grok persistante par la synchronisation gérée | 409 `grok_apply_busy` ; 400/500 échec de l'application |
+| `GET /api/grok/reset-coupons?accountId=...` | Lire les jetons de réinitialisation de facturation Grok restants et leurs fenêtres de validité pour le compte xAI actif ou spécifié | 400 compte manquant ; 401 non authentifié ; 502 erreur gRPC-Web en amont |
+| `POST /api/grok/reset-coupons/consume` | Échanger un coupon de réinitialisation éligible. Corps `{ accountId?, tokenId?, operationId? }`. L'`operationId` facultatif (UUIDv4) rend l'échange idempotent : répéter le même identifiant rejoue le résultat durable sans double échange. | 400 JSON/UUID invalide ; 401 non authentifié ; 409 `identity_mismatch` ; 502 erreur en amont ; 503 capacité du registre |
 | `GET, PUT /api/claude-desktop` | Lire ou enregistrer le profil Claude Desktop routé ou natif | 400 affectation invalide ou indisponible |
 | `POST /api/claude-desktop/apply` | Écrire le profil enregistré dans la configuration gérée de Claude Desktop | 400/500 échec d'écriture |
 | `GET /api/claude-desktop/status` | Inspecter le profil enregistré par rapport à celui appliqué et l'état du bureau | 400 échec de lecture de l'état |
 | `GET, PUT /api/claude-code` | Lire ou mettre à jour les paramètres de passerelle, de mode d'authentification, de correspondance des modèles, de contexte, d'agent et de service auxiliaire | 400 champ ou structure invalide |
 
+Le tableau de bord pilote les deux chemins de coupon depuis **Providers > xAI Grok > Accounts** : chaque
+ligne de compte connecté porte un badge de ticket indiquant le nombre de coupons restants, et le
+badge ouvre une boîte de dialogue qui liste les fenêtres de validité et échange le coupon le plus
+proche de l'expiration. La boîte de dialogue envoie un `operationId` émis par le client, et cesse
+d'envoyer après un délai d'attente au lieu de réessayer, car un échange dont l'enregistrement du
+journal est encore ouvert s'exécuterait de nouveau. `ocx account grok-reset-coupons` reste l'équivalent
+en terminal.
+
 Pour comprendre la liste de modèles et le comportement chiffré des tâches confiées aux agents d'exécution, voir
 [Surface des sous-agents](/fr/guides/sub-agent-surface/).
 
diff --git a/docs-site/src/content/docs/fr/reference/proxy-formats.md b/docs-site/src/content/docs/fr/reference/proxy-formats.md
index 7cc7d977e4..04637428e1 100644
--- a/docs-site/src/content/docs/fr/reference/proxy-formats.md
+++ b/docs-site/src/content/docs/fr/reference/proxy-formats.md
@@ -332,6 +332,8 @@ Les requêtes Responses et Chat acceptent une clé du proxy dans l’en-tête d
 
 Une route Cursor sans clé et sans OAuth peut utiliser ce bearer distinct de l’appelant, mais jamais un secret du proxy ni l’authentification ChatGPT main ajoutée automatiquement. La sélection Combo/policy et les réécritures effectives shadow/thread-spawn ne transmettent pas les identifiants bruts de l’appelant aux nouvelles cibles. Le routage OpenAI canonique peut restaurer l’unique bearer de l’appelant qui n’est pas une clé du proxy après un changement de route interne uniquement si son JWT contient un claim de compte ChatGPT et si tout en-tête de compte explicite correspond à ce claim. La transmission de l’authentification de l’appelant aux sidecars OpenAI facultatifs exige un unique JWT et un `chatgpt-account-id` explicite et correspondant. Les bearers opaques ne sont pas restaurés lors des changements de route, même avec un en-tête de compte explicite. Dans les autres cas, la cible finale doit disposer de son propre identifiant configuré, OAuth ou stocké ; sinon, la requête échoue localement. Un simple marqueur thread-spawn sans changement de route ne supprime pas les identifiants.
 
+Pour une requête Chat vers Cursor sans clé configurée, l’enrichissement facultatif par l’authentification main stockée est différé jusqu’à ce qu’un auxiliaire OpenAI soit réellement prévu et qu’un candidat Direct canonique soit disponible. Une requête Cursor indépendante ne réserve donc pas native main par cette voie et ne retarde pas le changement de profil. Les identifiants auxiliaires respectent les protections de démarrage et de changement de profil et restent séparés du bearer Cursor. Les auxiliaires Pool ou associés à un compte précis conservent leur sélection de compte.
+
 Le replay Claude ne conserve l’authentification main que dans un snapshot en mémoire dont le turn a acquis la propriété, et ne la reconstruit que pour une route ChatGPT canonique finale.
 
 :::caution
diff --git a/docs-site/src/content/docs/getting-started/quickstart.md b/docs-site/src/content/docs/getting-started/quickstart.md
index 867a06cec1..137b532118 100644
--- a/docs-site/src/content/docs/getting-started/quickstart.md
+++ b/docs-site/src/content/docs/getting-started/quickstart.md
@@ -114,7 +114,7 @@ codex -m "ollama-cloud/glm-5.2"      "Write a SQL migration"
 ## Choose sub-agent models (optional)
 
 A fresh config features five native models in Codex's sub-agent picker: `gpt-5.5`,
-`gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, and `gpt-5.4-mini`. Open `ocx gui` to replace or
+`gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, and `gpt-6-astra`. Open `ocx gui` to replace or
 reorder up to five native or routed models. The dashboard can also set one preferred sub-agent model
 and reasoning effort. See [Sub-agent Surface](/guides/sub-agent-surface/) to choose v1/base/v2 and
 understand when guidance, native defaults, and fallback apply.
diff --git a/docs-site/src/content/docs/guides/claude-code.md b/docs-site/src/content/docs/guides/claude-code.md
index 59bac66535..9be9d644df 100644
--- a/docs-site/src/content/docs/guides/claude-code.md
+++ b/docs-site/src/content/docs/guides/claude-code.md
@@ -679,3 +679,5 @@ it by default (`blockedSkills: ["claude-api"]`).
 **Subagent dispatches to wrong model** — Roster agents (`ocx-*`) use `<!-- ocx-route: ... -->`
 directives, not the Agent tool's `model` argument. Make sure the directive matches the intended
 route. Pass `"haiku"` as the model placeholder.
+
+Set `claudeCode.stabilizePromptCache` to `true` in `config.json` to relocate supported trailing Claude harness notices from system instructions to a trailing user message on translated routes. The default is `false`. Enable it only when this role change is appropriate for your clients. It preserves fenced examples and unmatched text; native Anthropic passthrough is unchanged. The metadata-less prompt-cache key then follows stabilized instructions. This does not create conversation identity or guarantee upstream cache hits.
diff --git a/docs-site/src/content/docs/guides/codex-app-models.md b/docs-site/src/content/docs/guides/codex-app-models.md
index b30240bf0e..f99fbc5fd8 100644
--- a/docs-site/src/content/docs/guides/codex-app-models.md
+++ b/docs-site/src/content/docs/guides/codex-app-models.md
@@ -188,8 +188,8 @@ including OpenAI service-tier metadata.
 
 ## Current stable model coverage
 
-The native fallback set includes `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`,
-`gpt-5.3-codex-spark`, and GPT-5.6 Sol/Terra/Luna. For the GPT-5.5/5.4 family, opencodex preserves
+The native fallback set includes `gpt-5.5`, `gpt-5.3-codex-spark`, and GPT-5.6 Sol/Terra/Luna.
+For the GPT-5.5 family, opencodex preserves
 the installed Codex catalog's richer live entries and only synthesizes a missing entry. The bundled
 upstream snapshot is used only for GPT-5.6, where it supplies the real per-model identity and
 metadata instead of an older-template approximation.
diff --git a/docs-site/src/content/docs/guides/codex-integration.md b/docs-site/src/content/docs/guides/codex-integration.md
index a99b880fc1..e56f2bd55b 100644
--- a/docs-site/src/content/docs/guides/codex-integration.md
+++ b/docs-site/src/content/docs/guides/codex-integration.md
@@ -123,6 +123,87 @@ The proxy listens on port `10100` by default and serves `POST /v1/responses`,
 `POST /v1/responses/compact`, `POST /v1/images/generations`, `POST /v1/images/edits`,
 `GET /v1/models`, `GET /healthz`, and the `/api/*` management surface.
 
+### Experimental context management (Codex 0.153+)
+
+For an eligible ChatGPT account, enable the experimental feature in Codex's own
+`config.toml` (merge this into an existing `[features]` table):
+
+```toml
+[features]
+context_management.experimental_mode = true
+```
+
+On the default built-in loopback integration, the next `ocx sync` or proxy start changes the
+managed root `openai_base_url` to `http://127.0.0.1:10100/backend-api/codex`. Codex checks this
+backend path before enabling its `new_context`, history, and notes tools. Start a new Codex
+session after synchronization. The feature remains opt-in; user-owned base URLs and remote
+custom-provider injection are not rewritten. No context-window or compaction-limit override
+is needed or added.
+
+The backend prefix aliases the existing data-plane routes, including Responses WebSocket
+upgrades. The original `/v1` routes and the realtime sideband override remain available. The
+proxy also relays the ten native `alpha/history/v2/*` and `alpha/notes/v2/*` POST endpoints
+through the built-in `openai` provider with the `openai-responses` adapter and canonical
+ChatGPT forward destination. Direct uses the current caller/main login; Pool selects a Codex
+account. `openai-apikey` uses its configured API key, and custom or noncanonical Responses
+providers are not candidates for this context relay and receive no Codex-account credentials
+from it. These private endpoints are not implemented by other model providers or the OpenAI
+API-key route.
+
+Caller headers are restricted to the shared Codex forward allowlist: `authorization`,
+`chatgpt-account-id`, and approved OpenAI beta, originator, session, and Codex protocol metadata.
+The context relay additionally forwards `x-openai-encrypted-tool-arguments` and
+`x-openai-tool-output-truncation-policy`; arbitrary caller headers such as cookies are not
+forwarded. A proxy data-plane key presented as a bearer is replaced with the selected Codex
+credential (the stored main login in Direct); missing credentials fail before forwarding.
+Proxy admission credentials never go upstream. Encrypted arguments, response bodies, and
+upstream error statuses are preserved.
+
+A successful ChatGPT model response records the root session's actual serving account in a
+bounded, process-local ownership registry. History and notes use that recorded owner, including
+an explicitly selected account, even when the current active account changes. Stored-account token
+refresh may continue for the same physical account; a replaced account identity is rejected.
+Direct caller-owned sessions keep the caller credential and cannot be taken over by a proxy bearer.
+This does not migrate server-side history between accounts.
+
+Ownership is partitioned by the opencodex API key that admitted the request, so two keys never
+reach each other's sessions even when both resolve to the same ChatGPT workspace. A workspace id
+names an organization rather than a person, so the registry also binds the stable user carried by
+the credential upstream accepted: an ordinary token refresh for that same user continues the
+session, while a different user in the same workspace does not. When the accepted credential
+proves no stable user, only that exact credential continues. That principal is the opencodex API key the request presents. A remote bind already requires one,
+so ownership works there. On the default loopback bind opencodex admits requests without reading a
+key, and the built-in loopback injection cannot carry the `x-opencodex-api-key` header, so Codex
+presents no opencodex key and context history returns HTTP 403. **The relay is therefore available
+on a remote bind with a configured key, or to a client that sends `x-opencodex-api-key` itself, and
+not through the default built-in loopback integration.** Whether a loopback-bound proxy should be
+able to name a caller at all is an open maintainer decision, so the current behaviour refuses
+rather than guessing.
+
+Unknown, expired, evicted, conflicting, or restart-lost ownership returns HTTP 409 before account
+selection or upstream I/O. The relay does not guess from the current active account. Existing
+sessions should save a checkpoint or other durable summary before enabling the feature or resetting
+context. Enabling it does not backfill earlier history or notes, and a new ownership observation
+does not prove that older backend content exists. After a restart, establish ownership with a
+successful model request before using context tools; start a new session when ownership conflicts.
+
+Existing model affinity, cooldown, and retry rules are unchanged. Context requests are not
+automatically retried, including notes writes; ChatGPT forward requests do not use same-key 429
+replay. History traffic does not consume or settle a model quota-recovery probe.
+
+One 35-second deadline covers the whole relay operation, starting before the request body is read
+and covering credential selection, so a stalled client cannot hold an admitted turn slot open.
+A client disconnect returns 499 and an expired deadline returns 504; nothing is dispatched
+upstream after either.
+
+To disable the feature, remove the experimental key (or set it to `false`), run `ocx sync`,
+and start a new Codex session. The managed root base returns to `/v1`.
+
+While the key is absent or `false` the relay does not exist: the ten endpoints answer 404 for any
+caller, including one that posts them directly, and a model turn records no history ownership.
+opencodex decides this by reading Codex own config itself, so the switch does not depend on the
+injected URL or on anything a client sends, and turning it off takes effect without a restart.
+
 ### Built-in image generation (`image_gen`)
 
 Codex's built-in `image_gen` tool does not go through `/v1/responses` — the codex-rs extension
@@ -288,6 +369,15 @@ The cache remains bounded; this does not extend retention or recover history the
 longer has. HTTP clients must handle the error explicitly and resend their full context without
 `previous_response_id`. Retrying only the same ID cannot recover missing state.
 
+The same recovery signal applies to routed Responses providers configured with
+`statelessResponses: true`, and to routed requests where a custom tool was lowered to a function
+but a delta result has no local call to establish its original type. Full replay preserves the
+call, result, and reasoning together; opencodex does not guess the result type or drop it.
+Stateful providers still resolve native function and native-only custom continuations themselves.
+These checks follow the selected wire protocol and tool declarations, not the model name. For a
+gateway that cannot resolve stored response IDs, enable `statelessResponses` on that provider;
+other providers keep their defaults.
+
 ### Client-side compaction (opt-in)
 
 Authenticated loopback routing normally keeps Codex on its built-in `openai` provider identity.
@@ -706,7 +796,7 @@ Catalog sync makes the selected sub-agent models available to Codex; see [Codex
 
 ## Codex account warmup
 
-When a ChatGPT account is added or reauthenticated, OpenCodex normally verifies it before saving with a small streaming request to the Codex Responses backend. It waits for `response.completed`, defaults to `gpt-5.4-mini`, and retries with `gpt-5.5` and `gpt-5.6-luna` on HTTP 400 or HTTP 404. Public errors contain fixed failure categories rather than raw upstream response bodies.
+When a ChatGPT account is added or reauthenticated, OpenCodex normally verifies it before saving with a small streaming request to the Codex Responses backend. It waits for `response.completed`, defaults to `gpt-5.6-luna`, and retries with `gpt-5.5` on HTTP 400 or HTTP 404. Public errors contain fixed failure categories rather than raw upstream response bodies.
 
 If the new OAuth credential's authenticated usage lookup confirms an exhausted 5-hour, weekly, or monthly quota, the account is saved without this model request and shows **Validation pending**. It cannot serve pool requests, even after a restart or token refresh. Once quota recovers, **Refresh quotas** finishes validation: a fresh, complete usage reading with headroom permits one small model request, and only a completed response enables the account. Failed or incomplete readings and failed validation preserve the restriction. Passive account polling does not trigger deferred validation. Unknown usage during initial registration retains the normal warmup gate.
 
@@ -728,7 +818,7 @@ A main-account refresh that does not complete still answers `503` with `Retry-Af
 ocx config set codexPool '{"excludedPlans":["free"]}'
 ```
 
-This is a selection policy, not a block. An excluded account keeps its credential, quota history, and thread affinity, stays visible on the account surface, and is still reachable by explicit account selection such as `work/gpt-5.4`. What changes is that automatic rotation stops choosing it, including when it is already the active account or already bound to a thread — which is the state a lapsed subscription leaves behind.
+This is a selection policy, not a block. An excluded account keeps its credential, quota history, and thread affinity, stays visible on the account surface, and is still reachable by explicit account selection such as `work/gpt-5.5`. What changes is that automatic rotation stops choosing it, including when it is already the active account or already bound to a thread — which is the state a lapsed subscription leaves behind.
 
 Two deliberate limits. The main Codex account is never excluded by plan, because selection-only routing withholds its plan rather than reading the fenced native credential, so a rule covering it would disagree with itself. And when no unexcluded account remains, the excluded one still answers rather than failing closed; pausing every account is still the way to stop serving entirely. There is no `minimumPlan` counterpart, because ranking ChatGPT plans against each other needs a total ordering that does not exist here.
 
@@ -772,3 +862,9 @@ injection. Explicit external-provider opt-out behavior is unchanged.
 In **Subagents → Delegation settings**, edit the ordered fallback chain and its availability polling interval (5000–600000 ms), then save it separately from the featured roster. A configured target that is no longer advertised remains in the chain until you remove it. The roster and fallback chain are separate settings; this editor does not make the roster replace the fallback policy.
 
 When a routed preferred model may receive V2 work from a native ChatGPT parent, the panel explains the upstream encrypted-task limitation. Readable tasks from routed parents are unaffected. The guidance uses `/api/v2` mode and native V1 pin state; the current API does not expose recovery activation or request-specific eligibility, so the panel reports those as unknown. V1/plaintext-compatible delegation remains an alternative. Experimental V2 recovery, where eligible and explicitly enabled, adds quota usage, latency, backend dependence and possible fidelity loss; it does not repair the upstream protocol. See [sub-agent surfaces](/guides/sub-agent-surface/) and [the upstream limitation](https://github.com/lidge-jun/opencodex/issues/92).
+
+## Paginated history safety refusal
+
+When an affected history store supports paginated records, a provider transition may return `history_paginated_requires_native_writer`. OpenCodex preserves the current configuration, profile, catalog, rollout and restore provenance instead of assigning ordinals outside Codex. This includes legacy rows in a migration-capable store. No-transition exits, such as preserving an external provider, remain available.
+
+Do not delete a provider definition still referenced by a conversation, repeatedly run `ocx sync` or legacy recovery, or rewrite an active rollout to work around this refusal. Keep the current files, close the affected conversation before any recovery, and report the exact error and versions without uploading private history. Use a verified fix with native-writer coordination; a backup or a successful script alone does not prove the conversation is visible again. Check the restored conversation in Codex after reopening.
diff --git a/docs-site/src/content/docs/guides/combos.md b/docs-site/src/content/docs/guides/combos.md
index db94da045f..ef5ccde16c 100644
--- a/docs-site/src/content/docs/guides/combos.md
+++ b/docs-site/src/content/docs/guides/combos.md
@@ -202,6 +202,8 @@ shows the soonest upcoming window reset (five-hour, weekly, monthly, or custom).
 provider that refreshes first. Targets without fresh quota data, and ties, keep configuration
 order. Weights and `stickyLimit` do not affect this strategy.
 
+This ranking and provider exclusion before dispatch require fresh model-inference limits that apply to the current single API key as a whole. OAuth/current-account summaries, caller-forward routes, multiple keys, and snapshots with changed credentials or destinations are display-only for this early decision. The same applies when `Authorization`, `x-api-key`, or `x-goog-api-key` headers override credentials; search-only and MCP-only windows are excluded. If no eligible target has an applicable reset, configuration order wins. Account selection and retries still enforce their normal limits.
+
 ## What happens when a target fails
 
 Combo failures are divided into **hop** failures and **terminal** failures.
@@ -347,10 +349,7 @@ task workflow.
 Open the local dashboard and choose **Models → Combos**. The workspace creates, edits, renames, and removes
 combos, and its target picker excludes disabled models and nested combos.
 
-Each target also shows a live quota badge: **Available**, **Out of quota**, or **Quota unknown**. Save and
-Create are disabled only when every enabled target has fresh, complete evidence that its quota is exhausted.
-Missing, stale, malformed, or incomplete aggregate evidence stays unknown and never locks a control. Polling
-continues while the workspace is visible, so recovery automatically restores the action. The dashboard
+Each target also shows a live quota badge: **Available**, **Out of quota**, or **Quota unknown**. The editor blocks Save and Create for quota only when every usable target has a current server-confirmed exhausted inference limit for its configured credential. Display-only account, model, search and MCP quota, or missing or expired routing evidence, does not cause this block. The block expires at the applicable reset or freshness boundary and is rechecked when the page becomes active or visible; Refresh reloads both Combo data and quota. The dashboard
 editor does not yet expose `cooldownMs` or `waitForCooldownMs`; use the configuration file or management
 API until the follow-up UI work lands.
 
diff --git a/docs-site/src/content/docs/guides/integrations.md b/docs-site/src/content/docs/guides/integrations.md
index 166a848614..60dd516a9e 100644
--- a/docs-site/src/content/docs/guides/integrations.md
+++ b/docs-site/src/content/docs/guides/integrations.md
@@ -1,10 +1,10 @@
 ---
 title: Integrations
-description: Connect opencodex to OpenCode, Pi, OMP, Hermes, OpenClaw, Kimi Code, Gajae Code, DeepSeek Harness, MiniMax Code, ZCode, Prime Agent, Aside and Raycast from the dashboard — one switch per client, with a backup taken before every write.
+description: Connect opencodex to OpenCode, Pi, OMP, Hermes, OpenClaw, Kimi Code, gjc, DeepSeek Harness, MiniMax Code, ZCode, Prime Agent, Aside, Raycast, omo and Cline CLI from the dashboard — one switch per client, with a backup taken before every write.
 ---
 
 The **Integrations** tab writes opencodex's provider block into a client's own config
-file, and removes it again. Thirteen clients work this way, each with a switch:
+file, and removes it again. Fifteen clients work this way, each with a switch:
 
 | Client | Config file | Format | When the change takes effect | Credential |
 |---|---|---|---|---|
@@ -14,13 +14,15 @@ file, and removes it again. Thirteen clients work this way, each with a switch:
 | Hermes | `~/.hermes/config.yaml` | YAML | new sessions | `OPENCODEX_HERMES_API_KEY` |
 | OpenClaw | `~/.openclaw/openclaw.json` | JSON5 | immediately, on a running gateway | `OPENCODEX_OPENCLAW_API_KEY` |
 | Kimi Code | `~/.kimi-code/config.toml` | TOML | on restart, or `/reload` | loopback placeholder |
-| Gajae Code | `~/.gjc/agent/models.yml` | YAML | new sessions, or when you open `/model` |`OPENCODEX_GAJAE_API_KEY` |
+| gjc | `~/.gjc/agent/models.yml` | YAML | new sessions, or when you open `/model` |`OPENCODEX_GAJAE_API_KEY` |
 | DeepSeek Harness (DSH) | `$DSH_HOME/settings.yaml` (default `~/.dsh/settings.yaml`) | YAML | hot reload | non-secret loopback bearer placeholder |
 | MiniMax Code | `~/.minimax/config.yaml` | YAML | new sessions, or after opening the model picker | loopback placeholder |
 | Prime Agent | `~/.prime/agent/models.json` | JSON | new sessions | loopback placeholder |
 | ZCode | `~/.zcode/v2/config.json` | JSON | on restart | loopback placeholder |
 | Aside | `~/.aside/u/<account>/models.json` | JSON | after fully quitting and reopening Aside | loopback placeholder |
 | Raycast | `~/.config/raycast/ai/providers.yaml` | YAML | immediately on save — Raycast watches the file | none — loopback only |
+| omo | `~/.omo/agent/models.json` | JSON | new sessions | loopback placeholder |
+| Cline CLI | `~/.cline/data/settings/providers.json` and sibling `models.json` | JSON pair | after stopping and restarting Cline | loopback placeholder |
 
 Generated catalogs include only enabled models from each provider selection. This applies to both
 downloads and managed integrations, including Pi and Aside. The management model list still shows
@@ -175,7 +177,7 @@ than 1000 levels — which locks the switch instead, so nothing is silently chan
 **OMP, DSH and Hermes** are unaffected by sibling edits too, for a different reason: their writers
 patch only their own managed provider ranges byte-wise, so the rest of the
 file is never rewritten. For the remaining formats that can carry comments
-(OpenClaw, Kimi Code, Gajae Code, MiniMax Code, Raycast — JSON5 and TOML
+(OpenClaw, Kimi Code, gjc, MiniMax Code, Raycast — JSON5 and TOML
 written as whole documents, or generic YAML without source preservation), or
 whenever our own entries were edited, the switch locks and disable refuses rather
 than guessing which edits were yours.
@@ -211,7 +213,7 @@ typed values into quoted strings. This includes values inside arrays and inline
 tables. Quoted date strings remain supported; an unquoted date must be preserved
 by editing the configuration manually.
 
-**Pi, Kimi Code, Gajae Code, MiniMax Code, Prime Agent and the managed DSH integration only work against a loopback bind.**
+**Pi, Kimi Code, gjc, MiniMax Code, Prime Agent, Aside, Raycast, omo and the managed DSH integration only work against a loopback bind.**
 The first four have no config field for the `x-opencodex-api-key` header a non-loopback bind
 requires. DSH has a generic headers map, but rc.6 does not document that dedicated admission
 header as a supported integration contract, so the managed writer fails closed instead of
@@ -261,10 +263,11 @@ ocx integration client enable --client mcode
 ocx mcode
 ```
 
-Once connected, `ocx sync` and `POST /api/sync` refresh owned MCode, Pi, Aside, and
-Raycast catalogs with the current model selection, context windows, and reasoning-effort
-ladders. Proxy startup refreshes an owned Raycast catalog. Changes to model visibility,
-provider selection, or presets also refresh connected Pi, Aside, and Raycast catalogs.
+Once connected, `ocx sync` and `POST /api/sync` refresh owned MCode, Pi, Aside,
+Raycast, and omo catalogs with the current model selection, context windows, and
+reasoning-effort ladders. Proxy startup refreshes an owned Raycast catalog. Changes to
+model visibility, provider selection, or presets also refresh connected Pi, Aside,
+Raycast, and omo catalogs.
 Missing, foreign-edited, or unsafe blocks stay untouched, as do previously owned blocks
 you removed manually.
 An enabled Aside profile is an exception to the usual owned-only refresh: if its account
@@ -342,3 +345,53 @@ the entire change failed. If saving those settings fails, no profile files are c
 Each profile has separate ownership and history. Existing user edits, unsafe paths and linked
 catalogs are refused; the existing explicit overwrite and drift-confirmation controls remain
 available. Fully quit and reopen Aside to load changed model files.
+
+
+## Cline CLI
+
+This integration targets Cline's current CLI/shared SDK provider store, whose native schema has
+`version: 1`. Legacy VS Code extension `globalState`/secret storage is not migrated or detected
+as this integration. Run Cline once to initialize its settings directory.
+
+**Stop Cline before enabling, syncing, disabling or restoring the integration.** OpenCodex writes
+`providers.opencodex` into both `providers.json` and sibling `models.json`. The first file holds
+the OpenAI Responses connection with a non-secret loopback placeholder; the second holds the
+filtered routed model catalog, including available context and image metadata. Existing provider
+entries and the default provider selection remain unchanged.
+
+```bash
+ocx integration client list --json
+ocx integration client enable --client cline
+ocx integration client history --client cline
+ocx integration client restore --op <operation-id>
+```
+
+After enabling, restart Cline and select OpenCodex, or launch with
+`cline --provider opencodex --model <provider/model>`. External catalog changes are read when
+Cline restarts. Cline is excluded from unattended catalog refresh; after changing the routed
+model selection, stop Cline and run `ocx sync` or enable the integration again to refresh it.
+A selected model is preserved while still routed and cleared if removed from the exported catalog.
+
+`CLINE_PROVIDER_SETTINGS_PATH` overrides the primary file. Otherwise `CLINE_DATA_DIR` selects the
+data directory, then `CLINE_DIR` selects the root, then `~/.cline` is used. The model file is always
+`models.json` beside the selected provider file. Overrides must be absolute or start with `~`.
+Mirror command-local Cline `--config` paths with `CLINE_PROVIDER_SETTINGS_PATH` when starting
+OpenCodex. A primary path named `models.json` is refused because the files must be distinct.
+
+Each file replacement is atomic, but no filesystem operation replaces both simultaneously.
+One journal operation snapshots both original files; a write or bookkeeping failure compensates
+both. An interrupted operation retains a private recovery record. Status reports incomplete
+recovery as unsafe, and the next explicit mutation recovers only if neither file nor its
+ownership has an unrelated edit. If recovery refuses, preserve the files and the recovery path
+reported by the operation; resolve the conflict before retrying.
+
+Undo restores **both original byte strings**, including a file that originally did not exist.
+Edits after the operation require the existing explicit `--confirm-drift`; the edited pair is
+backed up first. An occupied OpenCodex entry requires the existing `--overwrite-conflict` opt-in.
+Disable removes the two managed entries; it does not restore a prior foreign entry. Use Undo
+for that. Snapshot retention and expiration follow the same rules as other integrations.
+
+The download `cline-config-bundle.json` contains two native document members: `settings` for
+`providers.json`, and `catalog` for `models.json`. It is not itself a Cline settings file. Prefer
+the integration command for a journaled merge and rollback. Remote admission wiring is not
+supported by this generated integration; it requires unauthenticated loopback access.
diff --git a/docs-site/src/content/docs/guides/model-ordering.md b/docs-site/src/content/docs/guides/model-ordering.md
index 5333b839ce..45ec0666d6 100644
--- a/docs-site/src/content/docs/guides/model-ordering.md
+++ b/docs-site/src/content/docs/guides/model-ordering.md
@@ -122,7 +122,7 @@ featured block:
 ```json
 {
   "modelPickerOrder": [
-    "tyler/deepseek-v4-pro",
+    "tyler/deepseek-v4-flash",
     "jd-chat/kimi-k3",
     "jd-chat/glm-5.2"
   ]
diff --git a/docs-site/src/content/docs/guides/opencode.md b/docs-site/src/content/docs/guides/opencode.md
index 52c95445bf..2c6d7c7008 100644
--- a/docs-site/src/content/docs/guides/opencode.md
+++ b/docs-site/src/content/docs/guides/opencode.md
@@ -51,6 +51,34 @@ No model-level default effort is written. The proxy keeps applying its own confi
 default whenever a request carries no effort, so a default you change in opencodex stays
 in force instead of being frozen into the config.
 
+## Images and attachments
+
+opencode decides whether a model takes an image from the model entry itself, and it cannot ask
+models.dev about `opencodex` — this provider is not there. The generated blocks therefore
+carry opencode's own per-model capability fields, `attachment` and `modalities`, taken from
+the metadata the proxy reports at `GET /api/models`:
+
+```json
+"gpt-5.6-luna": {
+  "name": "gpt-5.6-luna (native)",
+  "limit": { "context": 272000, "output": 32000 },
+  "attachment": true,
+  "modalities": { "input": ["text", "image"], "output": ["text"] }
+}
+```
+
+Without those fields opencode assumes the model is text-only and refuses the paste on the
+client side, so the image never reaches the proxy. That applies to text-only models too: when
+the catalog reports image input for a model the vision sidecar covers, opencode lets the
+attachment through so the sidecar can describe it before the upstream call.
+
+What is written comes from the row's declared input modalities in `GET /api/models`. For a
+discovered model the catalog adds `image` itself for the sidecar case; a custom row is written
+from the modalities stored on it, so a custom entry that declares text only stays text-only
+even when the sidecar would cover it. A row that declares none — an undeclared custom model,
+for example — keeps the plain entry (`name`, plus `limit` when its context window is known),
+and opencode treats it as text-only.
+
 ## Your own config is never modified
 
 The launcher does not copy or rewrite `~/.config/opencode/opencode.json`,
diff --git a/docs-site/src/content/docs/guides/providers.md b/docs-site/src/content/docs/guides/providers.md
index d93dbe0af5..a093f22dc6 100644
--- a/docs-site/src/content/docs/guides/providers.md
+++ b/docs-site/src/content/docs/guides/providers.md
@@ -161,8 +161,10 @@ The ChatGPT passthrough catalog also layers in the bare GPT-5.6 Sol/Terra/Luna s
 Provider presets can use account login — including GitHub Copilot via an experimental unofficial
 device-flow bridge. opencodex stores their credentials in
 `~/.opencodex/auth.json`; refreshable tokens are refreshed automatically, while durable keys are
-reused until the provider revokes them. `chatgpt` is also accepted by the login
-CLI; it acquires a ChatGPT credential while creating a `forward`-mode provider entry.
+reused until the provider revokes them. `ocx login codex` is accepted as well, but it is not one of
+these providers: it routes to the Codex account pool — the same flow as `ocx account login codex`,
+which keeps its own account ledger and needs a running proxy. `chatgpt` and `openai` are aliases of
+that route.
 
 ```bash
 ocx login xai          # xAI Grok
@@ -174,8 +176,9 @@ ocx login google-antigravity
 ocx login cursor       # standalone Cursor PKCE login
 ocx login command-code # Command Code browser OAuth (or import ~/.commandcode/auth.json)
 ocx login orcarouter-oauth # OrcaRouter browser consent + PKCE
+ocx login devin       # Cognition/Devin Auth0 browser sign-in
 ocx login github-copilot  # GitHub device flow → Copilot token (Copilot Pro/Business)
-ocx login chatgpt      # standalone ChatGPT OAuth login
+ocx login codex        # Codex account pool (aliases: chatgpt, openai; needs a running proxy)
 ocx logout <provider>
 ```
 
@@ -189,6 +192,8 @@ ocx logout <provider>
 | `google-antigravity` | `google` | `https://daily-cloudcode-pa.googleapis.com` | Google OAuth over the Cloud Code Assist wire. Live discovery uses CCA's authenticated `v1internal:fetchAvailableModels` endpoint and publishes the agent models available to the signed-in account; the maintained catalog remains the fallback. |
 | `cursor` | `cursor` | `https://api2.cursor.sh` | Experimental PKCE login, live HTTP/2 transport with an opt-in HTTP/1.1 compatibility path, and account-filtered model discovery. |
 | `orcarouter-oauth` | `openai-chat` | `https://api.orcarouter.ai/v1` | Browser consent and key exchange use `https://www.orcarouter.ai` with S256 PKCE. The returned user-owned `sk-orca-…` API key is stored in the existing credential store and reused until revoked. |
+| `devin` | `devin` | `https://server.codeium.com` | Experimental unofficial Cognition/Devin bridge. Login opens Auth0 browser sign-in, then exchanges the token via Cognition's `RegisterUser` for a long-lived API key; models are discovered per account with `GetCascadeModelConfigs`. Not shown in the dashboard preset by default. Chat and usage reporting are verified against a live account across three models. |
+| `devin-cli` | `devin` | `https://server.codeium.com` | Imports the credential your installed Devin CLI already holds (`devin auth login` writes it to its own `credentials.toml`), then streams over Cognition's Connect-RPC api-server like the `devin` provider — no browser sign-in and no key to paste. Model discovery and context windows come from your account's own catalog. For the CLI's local agent loop over ACP stdio instead, use a custom-named row with `"adapter": "devin-cli"`. |
 | `github-copilot` | `openai-chat` | `https://api.githubcopilot.com` | Experimental. GitHub device flow + `copilot_internal` exchange (VS Code OAuth client). Requires an active Copilot subscription; not an official third-party API. |
 
 Google Antigravity account and provider quota probes use fixed Google accounting endpoints, including the models fallback. They support transparent Fake-IP DNS for those destinations while retaining TLS verification, redirect rejection and private-address checks. A custom provider base URL changes model requests, not quota destinations; `NO_PROXY` continues to select the direct-route policy.
@@ -336,8 +341,9 @@ does not strip metadata, retry a request, switch accounts, reset a thread, or ot
 **Diagnostics and reauth.** Human `ocx status` prints an OAuth health block (redacted account ids,
 no tokens). `ocx doctor` adds an OAuth reliability section with writable-store / single-flight checks
 and WARN rows that include a recovery Action. When an OAuth provider account needs reauthentication, run
-`ocx login <provider>` (or use Reauthenticate in the dashboard). Codex pool accounts are not an
-`ocx login` provider — reauthenticate via the dashboard Codex account pool. See
+`ocx login <provider>` (or use Reauthenticate in the dashboard). Codex pool accounts are not one of
+those providers, but `ocx login codex --reauth` routes to their account-pool reauthentication, which
+the dashboard Codex account pool also performs. See
 [`ocx status` / `ocx doctor`](/reference/cli/) in the CLI reference.
 
 ### Kiro credential import
@@ -398,7 +404,7 @@ free-experimentation model.
 
 **OrcaRouter** ([sponsor](https://github.com/lidge-jun/opencodex/blob/main/SPONSORS.md)) is an
 OpenAI-compatible gateway at `https://api.orcarouter.ai/v1` with vendor-namespaced model ids
-(`openai/gpt-5.5`, `anthropic/claude-opus-4.8`, `deepseek/deepseek-v4-pro`, ...) and an adaptive
+(`openai/gpt-5.5`, `anthropic/claude-opus-4.8`, `deepseek/deepseek-v4-flash`, ...) and an adaptive
 router, `orcarouter/auto`, that grades each prompt and picks the model. Create a key in the
 [OrcaRouter console](https://www.orcarouter.ai/console); the preset pins the row near the top of the
 Add provider picker and marks it as a sponsor, and nothing else about routing or defaults changes.
@@ -448,7 +454,7 @@ routing or defaults changes.
 | Moonshot (Kimi API) · Kimi (coding) | `https://api.moonshot.ai/v1` · `https://api.kimi.com/coding/v1` |
 | Hugging Face | `https://router.huggingface.co/v1` |
 | NVIDIA NIM | `https://integrate.api.nvidia.com/v1` |
-| Z.AI (GLM Coding) | `https://api.z.ai/api/coding/paas/v4` |
+| Z.AI (GLM Coding) | `https://api.z.ai` — Responses at `/api/v1/responses` by default; Chat Completions at `/api/coding/paas/v4/chat/completions` per model through `modelAdapters` |
 | Zhipu AI (BigModel) | `https://open.bigmodel.cn/api/paas/v4` |
 | BigModel Coding Plan (Responses, static roster) | `https://open.bigmodel.cn/api/v1` |
 | Qwen Cloud | Token plan (default): `https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1` · Pay as you go: `https://dashscope.aliyuncs.com/compatible-mode/v1` · or Custom |
@@ -470,8 +476,16 @@ inbound value is treated as client input and
 hashed into Go affinity; the internal bridge carries the original value, so native
 Chat, bridged Chat, and Responses derive the same result. Explicit provider-config
 session headers are operator overrides and are sent unchanged. Clients must keep the
-identifier stable within a conversation and distinct across conversations; requests
-without a session identifier cannot receive automatic session affinity.
+identifier stable within a conversation and distinct across conversations. A request
+without any session identifier is not given an inferred cross-request identity; it is
+instead sent under a session allocated for that request alone, isolated from every
+other request (see the provider reference for how that value is carried).
+For Claude Messages, configured OpenCode Go session headers remain authoritative.
+Otherwise, valid explicit session or thread headers take precedence, and valid
+conversation identity in `metadata.user_id` supplies the fallback. This fallback is
+applied to the final Go destination, including random combo selections and fallback
+attempts, rather than the preliminary route. Shared system-prompt cache keys do
+not identify conversations, and Go-specific identity is not sent to non-Go targets.
 Generated Pi provider configurations enable `compat.sendSessionAffinityHeaders`
 so Pi sends its per-session identity to the proxy. Existing manually managed Pi
 configurations can set this option on their `opencodex` provider as well.
@@ -521,7 +535,7 @@ streams close as incomplete rather than being reported as successful.
 > and the Agent Plan gateway has no `/models` resource. Pay-as-you-go defaults to
 > `doubao-seed-2-1-pro-260628`; its curated catalog also includes current DeepSeek and GLM text
 > models. Coding Plan defaults to `ark-code-latest`, while Agent Plan defaults to
-> `deepseek-v4-pro`.
+> `deepseek-v4-flash`.
 
 > **Volcengine Plan usage restriction:** Volcengine documents Coding Plan and Agent Plan quota as
 > valid only inside supported AI coding tools, and warns that using a plan key for general API
@@ -958,7 +972,7 @@ Ollama's own REST API (`POST /api/chat`) rather than the OpenAI-compatible surfa
 the live model roster from the provider, so new Ollama Cloud models appear without a config
 change. opencodex classifies its cloud
 lineup by vision capability so the [vision sidecar](/guides/sidecars/) only kicks in for
-text-only models. Text-only models (e.g. `glm-5.2`, `deepseek-v4-pro`, `gpt-oss`, `qwen3-coder`,
+text-only models. Text-only models (e.g. `glm-5.2`, `deepseek-v4-flash`, `gpt-oss`, `qwen3-coder`,
 `minimax-m2.x`, `nemotron-3-*`) are listed in `noVisionModels`; vision-native models (e.g.
 `kimi-k2.6`, `minimax-m3`, `gemma4`, `qwen3.5`, `gemini-3-flash-preview`) are not. Matching is
 tolerant of Ollama's `:size` tags, so `gpt-oss` covers `gpt-oss:120b` and `gpt-oss:20b`.
diff --git a/docs-site/src/content/docs/guides/sidecars.md b/docs-site/src/content/docs/guides/sidecars.md
index d0c79d272e..cee0da3f07 100644
--- a/docs-site/src/content/docs/guides/sidecars.md
+++ b/docs-site/src/content/docs/guides/sidecars.md
@@ -132,7 +132,7 @@ Combos advertise image input only when every member accepts images, either nativ
 sidecar, and the combo's `imageInput` setting is not disabled, so clients such as the Codex app
 allow attachments instead of blocking them before the sidecar runs. When
 `visionSidecar.model` is absent or blank, the OpenAI execution path, Dashboard, and management API
-use the `gpt-5.4-mini` fallback. Startup still migrates an explicitly persisted legacy
+use the `gpt-5.6-luna` fallback. Startup still migrates an explicitly persisted legacy
 `gpt-5.4-mini` value to `gpt-5.6-luna`; that migration applies to a stored value, not to an absent
 model field.
 
@@ -185,7 +185,7 @@ A model is marked text-only per provider:
   "providers": {
     "ollama-cloud": {
       "baseUrl": "https://ollama.com/v1",
-      "noVisionModels": ["glm-5.2", "gpt-oss", "qwen3-coder", "deepseek-v4-pro"]
+      "noVisionModels": ["glm-5.2", "gpt-oss", "qwen3-coder", "deepseek-v4-flash"]
     }
   }
 }
diff --git a/docs-site/src/content/docs/guides/sub-agent-surface.md b/docs-site/src/content/docs/guides/sub-agent-surface.md
index 8c9a838e77..49faeb9370 100644
--- a/docs-site/src/content/docs/guides/sub-agent-surface.md
+++ b/docs-site/src/content/docs/guides/sub-agent-surface.md
@@ -225,7 +225,7 @@ Use `ocx agent` for delegation, roster, effort-cap, and fallback settings:
 ocx agent status
 ocx agent injection set --model anthropic/claude-sonnet-5 --effort xhigh
 ocx agent subagents set gpt-5.6-sol,anthropic/claude-sonnet-5
-ocx agent fallback set gpt-5.4-mini,xai/grok-4.5 --poll-ms 60000
+ocx agent fallback set gpt-5.6-luna,xai/grok-4.5 --poll-ms 60000
 ocx effort set --subagent max
 ```
 
diff --git a/docs-site/src/content/docs/guides/web-dashboard.md b/docs-site/src/content/docs/guides/web-dashboard.md
index 7e86901233..6550f404fe 100644
--- a/docs-site/src/content/docs/guides/web-dashboard.md
+++ b/docs-site/src/content/docs/guides/web-dashboard.md
@@ -87,7 +87,7 @@ badge or the version value to read the full value.
 | **Windows tray** | Install a per-user login tray for one-click proxy start, stop, restart, dashboard access, and status. The tray is a controller, not a proxy restart service. |
 | **Codex autostart** | Allow an already-installed Codex launcher shim to run `ocx ensure`. This toggle does not install a shim or background service. |
 | **Providers** | Add, edit, set the default (enabled providers only), enable/disable, and remove providers; manage OAuth account pools and API-key pools where supported. Removing the current default switches to the first remaining enabled provider when one exists; otherwise deletion is refused and the current default is kept. Provider Settings can disable live model discovery for endpoints with missing, slow, or oversized `/models` catalogs. For Claude (Anthropic) OAuth pools, each logged-in account shows its own 5-hour and weekly rate-limit bars (usage is per credential); a failed probe keeps the last-known bars and marks them unavailable until the next successful refresh. The Provider Overview shown when no provider is selected carries a **Refresh all quotas** control that forces one server-side re-read of every configured provider; a provider whose upstream probe fails keeps its last-good row, so the status line reports that the check completed rather than claiming every value is fresh, and each row's own age stays the per-provider freshness signal. |
-| **Add provider** | Search registry-backed presets for account login, API-key services, local servers, or a custom endpoint. |
+| **Add provider** | One search above the tabs reaches all four at once — Accounts, Free, Local, Paid. While a query is live the results are grouped by tab with a count each, and the selected tab stays put rather than jumping. Press ArrowDown in the search box to focus the first available result action, skipping disabled buttons; if no action is available, focus stays in the search box. Local runtimes (Ollama, vLLM, LM Studio, LiteLLM) have their own tab, and a long provider note clamps to two lines with the full text one click away. |
 | **Codex Auth** | Add ChatGPT/Codex pool accounts, select the next-session account, refresh 5h / weekly / 30d quotas, enable or disable quota auto-switch, set its 1–100% threshold, and configure transient-failure failover. |
 | **Subagents** | Feature up to five bare native or namespaced routed models in the `spawn_agent` override list. |
 | **Models** | Toggle native GPT and routed models, set provider allowlists and context caps, choose v1/base/v2, and configure the v2 thread limit. Configured providers stay visible as zero-model groups when discovery is off or returns no rows. |
diff --git a/docs-site/src/content/docs/ja/getting-started/quickstart.md b/docs-site/src/content/docs/ja/getting-started/quickstart.md
index 4d251fc1d7..dddd327cbb 100644
--- a/docs-site/src/content/docs/ja/getting-started/quickstart.md
+++ b/docs-site/src/content/docs/ja/getting-started/quickstart.md
@@ -67,7 +67,7 @@ codex -m "ollama-cloud/glm-5.2"      "Write a SQL migration"
 
 ## サブエージェント モデルの選択 (オプション)
 
-新しい設定には、Codex のサブエージェント ピッカーの 5 つのネイティブ モデル、`gpt-5.5`、`gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna`、および `gpt-5.4-mini` が含まれています。 `ocx gui` を開いて、最大 5 つのネイティブ モデルまたはルーティング モデルを置換または並べ替えます。ダッシュボードでは、優先サブエージェント モデルと推論負荷を 1 つ設定することもできます。 v1/base/v2 を選択し、ガイダンス、ネイティブのデフォルト、およびフォールバックがいつ適用されるかを理解するには、[サブエージェントサーフェス](/guides/sub-agent-surface/) を参照してください。
+新しい設定には、Codex のサブエージェント ピッカーの 5 つのネイティブ モデル、`gpt-5.5`、`gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna`、および `gpt-6-astra` が含まれています。 `ocx gui` を開いて、最大 5 つのネイティブ モデルまたはルーティング モデルを置換または並べ替えます。ダッシュボードでは、優先サブエージェント モデルと推論負荷を 1 つ設定することもできます。 v1/base/v2 を選択し、ガイダンス、ネイティブのデフォルト、およびフォールバックがいつ適用されるかを理解するには、[サブエージェントサーフェス](/guides/sub-agent-surface/) を参照してください。
 
 ## キーを貼り付ける代わりにログインする
 
diff --git a/docs-site/src/content/docs/ja/guides/claude-code.md b/docs-site/src/content/docs/ja/guides/claude-code.md
index adc8703340..1d3c2da548 100644
--- a/docs-site/src/content/docs/ja/guides/claude-code.md
+++ b/docs-site/src/content/docs/ja/guides/claude-code.md
@@ -494,3 +494,5 @@ Anthropic バックエンドを明示すると意図的に失敗後停止しま
 **サブエージェントが誤ったモデルにディスパッチされる** — ロスターエージェント(`ocx-*`)は Agent ツールの `model`
 引数ではなく `<!-- ocx-route: ... -->` ディレクティブを使います。ディレクティブが希望ルートと一致するか確認し、
 モデルプレースホルダとして `"haiku"` を渡してください。
+
+`config.json` の `claudeCode.stabilizePromptCache` を `true` にすると、変換ルートのシステム指示末尾にある対応済み Claude 通知を最後のユーザーメッセージへ移します。既定値は `false` です。このロール変更が適切なクライアントでのみ有効にしてください。コードフェンス内の例と一致しない本文は保持され、Anthropic のネイティブ転送は変わりません。メタデータがない場合のキャッシュキーは安定化した指示から計算されます。会話 ID の生成やキャッシュヒットの保証は行いません。
diff --git a/docs-site/src/content/docs/ja/guides/codex-app-models.md b/docs-site/src/content/docs/ja/guides/codex-app-models.md
index 93385300ec..13f9b6517b 100644
--- a/docs-site/src/content/docs/ja/guides/codex-app-models.md
+++ b/docs-site/src/content/docs/ja/guides/codex-app-models.md
@@ -48,7 +48,7 @@ visibility = "list"
 
 ## 現在の安定したモデルの範囲
 
-ネイティブ フォールバック セットには、`gpt-5.5`、`gpt-5.4`、`gpt-5.4-mini`、`gpt-5.3-codex-spark`、および GPT-5.6 Sol/Terra/Luna が含まれます。 GPT-5.5/5.4 ファミリの場合、opencodex は、インストールされている Codex カタログの豊富なライブ エントリを保存し、欠落しているエントリのみを合成します。バンドルされたアップストリーム スナップショットは GPT-5.6 でのみ使用され、古いテンプレートの近似値の代わりに実際のモデルごとの ID とメタデータが提供されます。
+ネイティブ フォールバック セットには、`gpt-5.5`、`gpt-5.3-codex-spark`、および GPT-5.6 Sol/Terra/Luna が含まれます。 GPT-5.5 ファミリの場合、opencodex は、インストールされている Codex カタログの豊富なライブ エントリを保存し、欠落しているエントリのみを合成します。バンドルされたアップストリーム スナップショットは GPT-5.6 でのみ使用され、古いテンプレートの近似値の代わりに実際のモデルごとの ID とメタデータが提供されます。
 
 |ルート |ピッカー ID とカタログのメタデータ |
 | --- | --- |
diff --git a/docs-site/src/content/docs/ja/guides/codex-integration.md b/docs-site/src/content/docs/ja/guides/codex-integration.md
index 4ce54074d3..5425e9e193 100644
--- a/docs-site/src/content/docs/ja/guides/codex-integration.md
+++ b/docs-site/src/content/docs/ja/guides/codex-integration.md
@@ -241,7 +241,7 @@ ocx service install    # persistent: auto-starts on login and respawns on crash
 
 ## Codex アカウントのウォームアップ
 
-アカウントの追加・再認証では通常、保存前に小さなモデルリクエストで `response.completed` を確認します。既定モデルは `gpt-5.4-mini` で、HTTP 400 または HTTP 404 の場合は `gpt-5.5` および `gpt-5.6-luna` で再試行します。公開エラーには固定の分類のみを表示し、生の応答本文は公開しません。
+アカウントの追加・再認証では通常、保存前に小さなモデルリクエストで `response.completed` を確認します。既定モデルは `gpt-5.6-luna` で、HTTP 400 または HTTP 404 の場合は `gpt-5.5` で再試行します。公開エラーには固定の分類のみを表示し、生の応答本文は公開しません。
 
 新しい OAuth トークンによる使用量取得で5時間・週次・月次の上限到達が確認された場合、モデルを呼ばずに保存し、**検証待ち**と表示します。再起動やトークン更新後も使用できません。上限回復後に使用量を更新すると、十分な空き容量を示す完全な最新情報を確認してから小さなモデルリクエストを送り、完了した場合のみ使用可能になります。取得や検証の失敗では待機状態を維持します。通常の状態ポーリングは検証リクエストを送りません。初回登録時の使用量が不明な場合は通常の検証が必要です。
 
@@ -263,7 +263,7 @@ ocx service install    # persistent: auto-starts on login and respawns on crash
 ocx config set codexPool '{"excludedPlans":["free"]}'
 ```
 
-これはブロックではなく選択ポリシーです。除外されたアカウントも資格情報・使用量履歴・スレッドアフィニティを保持し、アカウント一覧に表示され、`work/gpt-5.4` のような明示的な指定では引き続き利用できます。変わるのは自動ローテーションが選ばなくなる点で、すでにアクティブなアカウントやスレッドに紐づいている場合も含みます。サブスクリプションが失効した直後は、まさにその状態です。
+これはブロックではなく選択ポリシーです。除外されたアカウントも資格情報・使用量履歴・スレッドアフィニティを保持し、アカウント一覧に表示され、`work/gpt-5.5` のような明示的な指定では引き続き利用できます。変わるのは自動ローテーションが選ばなくなる点で、すでにアクティブなアカウントやスレッドに紐づいている場合も含みます。サブスクリプションが失効した直後は、まさにその状態です。
 
 意図的な制限が2つあります。メインの Codex アカウントはプランによって除外されません。選択のみのルーティングは保護されたネイティブ資格情報を読まずにプランを伏せるため、メインを対象にすると挙動が食い違うからです。また、除外されていないアカウントが1つも残らない場合は、失敗させずに除外済みのアカウントが応答します。完全に停止したい場合は従来どおり全アカウントを一時停止してください。`minimumPlan` に相当する設定はありません。ChatGPT のプランを順位付けするには、ここに存在しない全順序が必要になるためです。
 
@@ -280,3 +280,9 @@ ocx restore back # point plain Codex at the running proxy again
 ```
 
 opencodex が管理対象 [バックグラウンドサービス](/reference/cli/#ocx-service) として実行される場合、`OCX_SERVICE=1` が設定されるため、サービス主導の再起動によって Codex 設定がスラッシングされなくなります。明示的な `ocx stop` / `ocx service stop` のみがネイティブ Codex を復元します。
+
+## ページ分割履歴の保護による拒否
+
+対象の履歴ストアがページ分割をサポートする場合、プロバイダー変更は `history_paginated_requires_native_writer` で拒否されることがあります。Codex の外で番号を割り当てず、設定、プロファイル、カタログ、履歴ファイル、復元情報を保持します。移行可能なストアの legacy 行も対象です。外部プロバイダーを保持するだけの経路は利用できます。
+
+会話が参照するプロバイダー定義を削除したり、`ocx sync` や旧式の復元を繰り返したり、使用中の履歴を書き換えたりしないでください。ファイルを保持し、復元前に対象の会話を閉じ、個人の履歴を公開せず正確なエラーとバージョンを報告してください。ネイティブの書き込み処理と連携する検証済みの修正が必要です。バックアップやスクリプトの成功だけでは表示の復元は証明されません。再度開いた Codex で確認してください。
diff --git a/docs-site/src/content/docs/ja/guides/combos.md b/docs-site/src/content/docs/ja/guides/combos.md
index 655dae2232..70c902ec6e 100644
--- a/docs-site/src/content/docs/ja/guides/combos.md
+++ b/docs-site/src/content/docs/ja/guides/combos.md
@@ -113,6 +113,8 @@ ocx combo set balanced \
 
 `reset-window` は、キャッシュされたプロバイダーのクォータスナップショットで、次回のウィンドウリセット（5 時間、週次、月次、またはカスタム）が最も早い適格なターゲットへ、各リクエストをルーティングします。これにより、最初にクォータが補充されるプロバイダーを先に使用します。新しいクォータデータがないターゲットと、リセット時刻が同じターゲットでは、構成順序が維持されます。`weight` と `stickyLimit` はこの戦略に影響しません。
 
+この順位付けと送信前のプロバイダー除外には、現在の単一 API キー全体に適用される最新のモデル推論制限が必要です。OAuth／現在のアカウントの概要、呼び出し元の認証情報を転送するルート、複数キー、認証情報や送信先が変わったスナップショットは、この事前判断では表示専用です。`Authorization`、`x-api-key`、`x-goog-api-key` ヘッダーで認証情報を上書きする場合も同様で、検索専用および MCP 専用ウィンドウは対象外です。適用可能なリセット情報を持つ適格な対象がなければ、設定順序を使用します。アカウント選択と再試行には引き続き通常の制限が適用されます。
+
 ## ターゲットが失敗すると何が起こるか
 
 コンボ障害は、**ホップ** 障害と **ターミナル** 障害に分類されます。
@@ -180,8 +182,7 @@ v1/base/v2 モードと完全な暗号化タスクのワークフローについ
 ローカル ダッシュボードを開き、**Models → コンボ**を選択します。ワークスペースはコンボを作成、編集、名前変更、削除し、そのターゲット ピッカーは無効なモデルとネストされたコンボを除外します。
 
 各ターゲットには **利用可能**、**クォータを使い切りました**、**クォータ不明** のライブバッジも表示されます。
-保存と作成が無効になるのは、有効な全ターゲットについて、クォータ枯渇を示す新鮮で完全な証拠がある場合だけです。
-欠落、古い、不正、または不完全な集約データは不明のままで、操作をロックしません。クォータが回復すると操作は自動で再び有効になります。ダッシュボードのエディターではまだ `cooldownMs` と `waitForCooldownMs` を設定できません。後続の UI 作業が完了するまでは、構成ファイルまたは管理 API を使用してください。
+エディターがクォータを理由に保存と作成をブロックするのは、使用可能なすべてのターゲットについて、設定された認証情報の推論上限に達したことを示す、サーバーによる確認が現在も有効な場合だけです。表示専用のアカウント・モデル・検索・MCP クォータや、ルーティングの根拠情報の欠落・期限切れによって、このブロックが発生することはありません。ブロックは該当するリセット時刻またはデータの有効期限に解除され、ページがアクティブになるか表示状態になると再確認されます。「更新」はコンボデータとクォータの両方を再読み込みします。ダッシュボードのエディターではまだ `cooldownMs` と `waitForCooldownMs` を設定できません。後続の UI 作業が完了するまでは、構成ファイルまたは管理 API を使用してください。
 
 ### CLI
 
diff --git a/docs-site/src/content/docs/ja/guides/providers.md b/docs-site/src/content/docs/ja/guides/providers.md
index 346c3552fa..d67f53e15e 100644
--- a/docs-site/src/content/docs/ja/guides/providers.md
+++ b/docs-site/src/content/docs/ja/guides/providers.md
@@ -86,8 +86,10 @@ ChatGPT パススルーカタログには GPT-5.6 Sol/Terra/Luna の名前空間
 
 OAuth ログインを使うプロバイダープリセットは 8 つで、これに実験的な非公式デバイスフロー
 ブリッジ経由の GitHub Copilot が加わります。認証情報は `~/.opencodex/auth.json` に保存され、
-自動更新されます。ログイン CLI は `chatgpt` も受け付けます。このコマンドは ChatGPT 認証情報を
-発行し `forward` モードのプロバイダーエントリを作成します。
+自動更新されます。`ocx login codex` も受け付けますが、これは上記のプロバイダーではありません。
+Codex アカウントプールのログイン (`ocx account login codex` と同じフロー) に転送されます。
+プールは独自の台帳を持ち、この経路はプロキシの起動を必要とします。`chatgpt` と `openai` は
+同じ経路の別名です。
 
 ```bash
 ocx login xai          # xAI Grok
@@ -98,8 +100,9 @@ ocx login kiro         # kiro-cli 認証情報の取り込み(トークンフォ
 ocx login google-antigravity
 ocx login cursor       # Cursor 専用 PKCE ログイン
 ocx login command-code # Command Code のブラウザ OAuth (または ~/.commandcode/auth.json を取り込み)
+ocx login devin       # Cognition/Devin の Auth0 ブラウザサインイン
 ocx login github-copilot  # GitHub デバイスフロー → Copilot トークン (Copilot Pro/Business)
-ocx login chatgpt      # 別途 ChatGPT OAuth ログイン
+ocx login codex        # Codex アカウントプール (別名: chatgpt, openai / プロキシの起動が必要)
 ocx logout <provider>
 ```
 
@@ -112,6 +115,8 @@ ocx logout <provider>
 | `kiro` | `kiro` | `https://runtime.us-east-1.kiro.dev` | 初回ログインは、インストール済みでサインインした `kiro-cli` セッションを取り込みます（Unix では `curl -fsSL https://cli.kiro.dev/install` &#124; `bash`、Windows PowerShell では `irm 'https://cli.kiro.dev/install.ps1'` &#124; `iex` でインストールしてから `kiro-cli login` を実行）。**アカウントを追加**は `kiro-cli` をログアウトして新しいブラウザログインを開始し、`kiro-cli` 自体のアカウントを切り替えてアカウント別プロファイルメタデータを保存します。既存の OpenCodex アカウントは保持され、キャンセルまたは失敗時には以前の `kiro-cli` セッションが復元されます。 |
 | `google-antigravity` | `google` | `https://daily-cloudcode-pa.googleapis.com` | Google OAuth を Cloud Code Assist wire で使用。ライブ探索は認証済みの CCA `v1internal:fetchAvailableModels` エンドポイントを使用し、ログイン中のアカウントで利用可能な agent モデルのみを公開します。管理されたカタログはフォールバックとして残ります。 |
 | `cursor` | `cursor` | `https://api2.cursor.sh` | 実験的 PKCE ログイン、HTTP/2 トランスポート、アカウント別モデル探索をサポート。 |
+| `devin` | `devin` | `https://server.codeium.com` | 実験的な非公式 Cognition/Devin ブリッジ。ログインは Auth0 のブラウザサインインを開き、取得したトークンを `RegisterUser` で長期 API キーに交換します。モデル一覧は `GetCascadeModelConfigs` でアカウントごとに取得し、ストリーミングは Connect-RPC 上の `runTurn` 経路のみを使います。ダッシュボードのプリセットには既定で含まれません。 |
+| `devin-cli` | `devin` | `https://server.codeium.com` | インストール済み Devin CLI がすでに保持している認証情報を取り込みます（`devin auth login` が自身の `credentials.toml` に書き込みます）。以降は `devin` プロバイダと同じく Cognition の Connect-RPC api-server へストリーミングします。ブラウザサインインも貼り付けるキーも不要です。モデル一覧とコンテキストウィンドウはアカウントのカタログから取得します。CLI 自身のローカルエージェントループ（ACP stdio）を使う場合は、別名の行に `"adapter": "devin-cli"` を指定してください。|
 | `github-copilot` | `openai-chat` | `https://api.githubcopilot.com` | 実験的。GitHub デバイスフロー + `copilot_internal` 交換（VS Code OAuth クライアント）。有効な Copilot サブスクリプションが必要で、公式のサードパーティ API ではありません。 |
 
 Google Antigravity のアカウント・プロバイダーのクォータ確認は、モデル一覧へのフォールバックも含め、固定の Google エンドポイントを使用します。その宛先では透過 Fake-IP DNS に対応し、TLS 検証、リダイレクト拒否、プライベートアドレス検査を維持します。カスタム base URL はモデル要求にのみ適用されます。`NO_PROXY` は直接接続のポリシーを維持します。
@@ -248,7 +253,7 @@ Volcengine Agent Plan は `openai-responses` アダプターでネイティブ R
 > Agent Plan ゲートウェイには `/models` リソースがありません。従量課金のデフォルトは
 > `doubao-seed-2-1-pro-260628` で、静的カタログには現在の DeepSeek と GLM のテキストモデルも
 > 含まれます。Coding Plan のデフォルトは `ark-code-latest`、Agent Plan は
-> `deepseek-v4-pro` です。
+> `deepseek-v4-flash` です。
 
 **Chutes の discovery:** `chutes` preset は Chutes の固定された共有 OpenAI 互換 LLM gateway を使います。
 公開 `/v1/models` catalog から `supported_features` が `tools` を示す行だけを残し、スラッシュを含む
@@ -425,7 +430,7 @@ Ollama Cloud はホステッド型(ローカルではない)Ollama です。`htt
 サーフェスではなく Ollama 自身の REST API(`POST /api/chat`)で接続し、モデル一覧はプロバイダーから
 動的に取得するため、新しい Ollama Cloud モデルは設定変更なしで現れます。opencodex はクラウド
 ラインナップをビジョン機能で分類し、[ビジョンサイドカー](/ja/guides/sidecars/)がテキスト専用モデルにのみ
-動作するようにします。テキスト専用モデル(例: `glm-5.2`、`deepseek-v4-pro`、`gpt-oss`、`qwen3-coder`、
+動作するようにします。テキスト専用モデル(例: `glm-5.2`、`deepseek-v4-flash`、`gpt-oss`、`qwen3-coder`、
 `minimax-m2.x`、`nemotron-3-*`)は `noVisionModels` に列挙され、ビジョンネイティブモデル(例:
 `kimi-k2.6`、`minimax-m3`、`gemma4`、`qwen3.5`、`gemini-3-flash-preview`)は含まれません。マッチングは
 Ollama の `:size` タグに寛容なので `gpt-oss` は `gpt-oss:120b` と `gpt-oss:20b` の両方を含みます。
diff --git a/docs-site/src/content/docs/ja/guides/sidecars.md b/docs-site/src/content/docs/ja/guides/sidecars.md
index dec111160f..30a7f5a404 100644
--- a/docs-site/src/content/docs/ja/guides/sidecars.md
+++ b/docs-site/src/content/docs/ja/guides/sidecars.md
@@ -76,7 +76,7 @@ stall は全体生成 timeout ではありません。SSE 開始前の失敗は
 サイドカー対象の各モデルに画像入力を広告します。コンボは、すべてのメンバーがネイティブまたはサイドカーを
 通じて画像を受け入れ、かつコンボの `imageInput` 設定が無効でない場合にのみ画像入力を広告します。これにより
 Codex アプリなどのクライアントは、サイドカー実行前に添付をブロックせず許可できます。`visionSidecar.model` が未設定または空の場合、
-OpenAI 実行経路、ダッシュボード、管理 API は `gpt-5.4-mini` をフォールバックとして使います。起動時には
+OpenAI 実行経路、ダッシュボード、管理 API は `gpt-5.6-luna` をフォールバックとして使います。起動時には
 明示的に保存された旧 `gpt-5.4-mini` 値を引き続き `gpt-5.6-luna` にマイグレーションしますが、この
 マイグレーションは保存済みの値だけが対象で、モデルフィールドがない場合には適用されません。
 
@@ -125,7 +125,7 @@ OpenAI 実行経路、ダッシュボード、管理 API は `gpt-5.4-mini` を
   "providers": {
     "ollama-cloud": {
       "baseUrl": "https://ollama.com/v1",
-      "noVisionModels": ["glm-5.2", "gpt-oss", "qwen3-coder", "deepseek-v4-pro"]
+      "noVisionModels": ["glm-5.2", "gpt-oss", "qwen3-coder", "deepseek-v4-flash"]
     }
   }
 }
diff --git a/docs-site/src/content/docs/ja/guides/sub-agent-surface.md b/docs-site/src/content/docs/ja/guides/sub-agent-surface.md
index 8d2be3b2e8..c8d4e06b54 100644
--- a/docs-site/src/content/docs/ja/guides/sub-agent-surface.md
+++ b/docs-site/src/content/docs/ja/guides/sub-agent-surface.md
@@ -119,7 +119,7 @@ ocx v2 threads 8
 ocx agent status
 ocx agent injection set --model anthropic/claude-sonnet-5 --effort xhigh
 ocx agent subagents set gpt-5.6-sol,anthropic/claude-sonnet-5
-ocx agent fallback set gpt-5.4-mini,xai/grok-4.5 --poll-ms 60000
+ocx agent fallback set gpt-5.6-luna,xai/grok-4.5 --poll-ms 60000
 ocx agent effort set --subagent max
 ```
 
diff --git a/docs-site/src/content/docs/ja/reference/adapters.md b/docs-site/src/content/docs/ja/reference/adapters.md
index 0fea01bc2b..50c206d541 100644
--- a/docs-site/src/content/docs/ja/reference/adapters.md
+++ b/docs-site/src/content/docs/ja/reference/adapters.md
@@ -175,6 +175,16 @@ model discovery の両方に適用されます。
   モデルを送信し、個別の `effort` および `fast=true` 値は `requested_model.parameters` に格納します。
 - Cursor ネイティブのローカルファイルシステム/shell/network 実行はデフォルトで拒否します。明示的な `mcpServers` と `desktopExecutor` 統合はそれぞれ別の opt-in です。`nativeLocalExec: "on"` はより広い組み込み executor を有効にし、Codex の承認/サンドボックスルールを迂回します。従来の `unsafeAllowNativeLocalExec: true` は、`nativeLocalExec` が設定されていない場合にのみ同等です。
 
+## `devin`
+
+**対象:** Cognition の `exa.api_server_pb.ApiServerService/GetChatMessage`（`server.codeium.com`、Connect ストリーミング）。
+**認証:** `provider.apiKey` または転送された authorization ヘッダーの Devin/Cognition API キー。ログインは Auth0 のブラウザサインインを開き、`SeatManagementService.RegisterUser` で長期キーに交換します。
+
+- 通常の fetch/parse ではなく `runTurn` を使います。リクエストとサーバーイベントは `devin/cloud-direct/wire.ts` の手動 protobuf フレーミングで扱います。
+- `GetCascadeModelConfigs` でアカウントごとにモデルを取得し、プランに含まれないモデルはリクエスト時ではなく一覧の段階で外れます。
+- Cognition はツール説明の長さ制限と完全一致のブロックリストを課します。アダプターが既知の語句を書き換え、長すぎる説明を切り詰めます。
+- キーは更新されません。失効したら `ocx login devin` をやり直してください。
+
 ## `azure-openai`（別名: `azure`）
 
 **対象:** **Azure OpenAI**。`openai-responses` を包むため、同じく `passthrough: true` です。
diff --git a/docs-site/src/content/docs/ja/reference/cli/agents.md b/docs-site/src/content/docs/ja/reference/cli/agents.md
index a223362a56..a74f20a817 100644
--- a/docs-site/src/content/docs/ja/reference/cli/agents.md
+++ b/docs-site/src/content/docs/ja/reference/cli/agents.md
@@ -125,7 +125,7 @@ Grok Build モデル フェンスを管理および適用します。
 
 ## クライアント設定のエクスポート
 
-### `ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|prime|aside|raycast>`
+### `ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|prime|aside|raycast|omo>`
 
 実行中のプロキシに接続するクライアント設定を出力します。このコマンドは、ベース URL、モデル一覧、およびクライアントに応じた認証情報参照または `opencodex-loopback` プレースホルダーを含む `opencodex` プロバイダーブロックを、選択したクライアントのネイティブ形式でシリアル化します。
 
@@ -133,7 +133,7 @@ Grok Build モデル フェンスを管理および適用します。
 
 |旗 |アクション |
 | --- | --- |
-| `--client <opencode\|pi\|omp\|hermes\|openclaw\|kimi\|gajae\|dsh\|mcode\|zcode\|prime\|aside\|raycast>` |必須。クライアントの設定形式を選択します。 |
+| `--client <opencode\|pi\|omp\|hermes\|openclaw\|kimi\|gajae\|dsh\|mcode\|zcode\|prime\|aside\|raycast\|omo>` |必須。クライアントの設定形式を選択します。 |
 | `--json` |構成 JSON のみを標準出力に出力するため、リダイレクトはバイト正確な出力をキャプチャします。 `--out` 書き込みメモを含むすべての診断は stderr に送られます。 |
 | `--out <path>` |設定を `<path>` に書き込みます。既存のファイルの置き換えを拒否します。 |
 | `--force` | `--out` が既存のファイルを置き換えることを許可します。 |
@@ -160,7 +160,9 @@ ocx export --client opencode --out ~/opencodex-opencode.json
 | `mcode` | `~/.minimax/config.yaml` (`MINIMAX_DATA_DIR`、次に旧 `MAVIS_DATA_DIR` が設定時に優先。相対値は拒否されます) | `mcode-config.yaml` | なし — loopback placeholder |
 | `zcode` | `~/.zcode/v2/config.json` (`ZCODE_DATA_DIR` が設定時に優先。相対値は拒否されます) | `config.json` | なし — loopback placeholder |
 | `prime` | `~/.prime/agent/models.json` (`PRIME_AGENT_CODING_AGENT_DIR` が設定時に優先。相対値は拒否されます) | `prime-models.json` | なし — loopback placeholder |
+| `aside` | `~/.aside/u/<account>/models.json`。Aside 自身の `accounts.json` が現在のアカウントとして指す account を使います。マニフェストが読めない場合は、既定のアカウントに落とさず拒否します | `aside-models.json` | なし — loopback placeholder |
 | `raycast` | `~/.config/raycast/ai/providers.yaml` (macOS と Windows で同じ。Raycast は `XDG_CONFIG_HOME` を尊重しません) | `raycast-providers.yaml` | なし — loopback のみ。`api_keys` エントリは書き込まれません |
+| `omo` | `~/.omo/agent/models.json` (`OMO_CODING_AGENT_DIR`、次に `SENPI_CODING_AGENT_DIR`、次に `PI_CODING_AGENT_DIR` の順で設定時に優先。相対値は拒否されます) | `omo-models.json` | なし — loopback placeholder |
 
 Raycast のエクスポートは、`providers` シーケンスに `id: opencodex` 要素を 1 つだけ持つ独立した `providers.yaml` 文書です。内容は `name: OpenCodex`、プロキシの `/v1` ベース URL、および `abilities` 付きのルーティング済み全モデルです (`tools` と `system_message` は常にサポート、`vision` はカタログの入力モダリティから、`reasoning_effort` はモデルに effort ラダーがある場合、`temperature` は推論モデルではオフ)。Custom Providers は Raycast Pro の機能で、Raycast はこのファイルを監視しているため、保存した変更は再起動なしで反映されます。形式は [manual.raycast.com/ai/custom-providers](https://manual.raycast.com/ai/custom-providers) に記載されています。`api_keys` エントリは書き込まれないため、このエクスポートは loopback 専用で、loopback 以外のバインドは拒否されます。
 
@@ -170,7 +172,7 @@ opencode は `{env:OPENCODEX_OPENCODE_API_KEY}` を補間します。opencodex 
 `ocx export` は実際のクライアント設定を書き込むことはありません。宛先は手動でマージできるように出力されます。`--out` は、`--force` なしで既存のファイルを上書きすることを拒否します。これは、設定を置き換えると、その中にすでに含まれている他のプロバイダー、エージェント、および MCP エントリが破壊されるためです。
 :::
 
-キーはシリアル化されません。生成される設定には、文書化された環境参照か、秘密ではないループバック用プレースホルダーのいずれかが入ります。ループバック プロキシ (`127.0.0.1`、デフォルト) にはアドミッション キーはまったく必要ありません。プロキシがループバックを超えてバインドする場合は、対応する `OPENCODEX_OPENCODE_API_KEY`、`OPENCODEX_HERMES_API_KEY`、または `OPENCODEX_OPENCLAW_API_KEY` を設定します。`OPENCODEX_GAJAE_API_KEY` は Gajae の provider 認証値を環境から渡しますが、remote admission header は送れないため、生成される Gajae 統合はループバック専用のままです。アドミッションキーの発行方法については、[リモートアクセス](/reference/configuration/#remote-access) を参照してください。上流プロバイダー自体のキーは完全に別のものであり、[プロバイダー](/guides/providers/) ごとに構成されます。
+キーはシリアル化されません。生成される設定には、文書化された環境参照か、秘密ではないループバック用プレースホルダーのいずれかが入ります。ループバック プロキシ (`127.0.0.1`、デフォルト) にはアドミッション キーはまったく必要ありません。プロキシがループバックを超えてバインドする場合は、対応する `OPENCODEX_OPENCODE_API_KEY`、`OPENCODEX_HERMES_API_KEY`、または `OPENCODEX_OPENCLAW_API_KEY` を設定します。`OPENCODEX_GAJAE_API_KEY` は gjc の provider 認証値を環境から渡しますが、remote admission header は送れないため、生成される gjc 統合はループバック専用のままです。アドミッションキーの発行方法については、[リモートアクセス](/reference/configuration/#remote-access) を参照してください。上流プロバイダー自体のキーは完全に別のものであり、[プロバイダー](/guides/providers/) ごとに構成されます。
 
 同じペイロードが `GET /api/client-config` によって提供され、ダッシュボードの [API] タブにレンダリングされるため、CLI、API、および GUI は同じバイトを使用します。
 
diff --git a/docs-site/src/content/docs/ja/reference/cli/providers-accounts.md b/docs-site/src/content/docs/ja/reference/cli/providers-accounts.md
index 594d1fc30e..a13a5b310e 100644
--- a/docs-site/src/content/docs/ja/reference/cli/providers-accounts.md
+++ b/docs-site/src/content/docs/ja/reference/cli/providers-accounts.md
@@ -61,7 +61,7 @@ ocx models live --provider ark --json
 
 プロバイダーの登録済みログイン フローを開始します。 OAuth プロバイダーはブラウザを開き、自動更新された認証情報を `~/.opencodex/` に保存します。 API キー ログイン プロバイダーは、キー ダッシュボードを開き、キーの入力を求め、可能な場合は検証し、結果のプロバイダー設定を保存します。名前が欠落しているか不明な場合、このコマンドは現在受け入れられている OAuth および API キーのプロバイダー ID を出力します。
 
-`ocx status` / `ocx doctor` が再認証が必要であるか、端末の更新失敗を報告した後、同じコマンドを使用して **再認証**します (またはダッシュボードで再認証を使用します)。 Codex プール アカウントはパブリック `ocx login` プロバイダーではありません。代わりに、ダッシュボード Codex アカウント プール (再認証) またはヘッドレス `ocx account reauth` フローを介して再認証します。
+`ocx status` / `ocx doctor` が再認証が必要であるか、端末の更新失敗を報告した後、同じコマンドを使用して **再認証**します (またはダッシュボードで再認証を使用します)。 Codex プール アカウントは上記の OAuth / API キーのプロバイダーではありませんが、`ocx login codex` から到達できます。このコマンドはアカウントプールのログインに転送されるため、`ocx login codex --reauth` は `ocx account reauth codex` と同じです。ダッシュボードの Codex アカウントプール (再認証) でも行えます。この経路はプロキシ内部で動くため、プロキシの起動が必要です。
 
 ```bash
 ocx login xai
@@ -79,7 +79,7 @@ ocx login anthropic
 実行中のプロキシを介してプロバイダー アカウントと API キー プールを一覧表示し、切り替えます。出荷されたヘルプ画面は次のとおりです。
 
 ```text
-Usage: ocx account <list|current|use|refresh|auto-switch|priority|login|reauth|code|cancel|remove|add-key|reset-credits> ...
+Usage: ocx account <list|current|use|refresh|auto-switch|priority|login|reauth|code|cancel|remove|add-key|reset-credits|grok-reset-coupons> ...
 
 list [provider]     Codex account pool, OAuth accounts and API keys (identifiers shown masked as the API returns them).
 current <provider>  Show the active account or key.
@@ -91,6 +91,7 @@ remove <provider> <id> --yes  Remove a stored account or key after an existence
 add-key <provider> [--label <label>]  Add a key read only from piped stdin.
 login/reauth/code/cancel  Run browser or manual-code auth from a headless shell.
 reset-credits <id|main> [--consume --yes]  Inspect or consume Codex reset credits.
+grok-reset-coupons [<id>] [--consume --yes] [--token-id <token-id>] [--operation-id <uuid>]  Inspect or redeem Grok reset coupons.
 Codex pool selection applies to the next request after clearing existing affinity; in-flight requests keep their captured account.
 ```
 
@@ -152,11 +153,11 @@ OAuth プロバイダーと API キー プロバイダーの場合、これに
 
 ### `ocx account auto-switch <provider> <on|off|status|threshold <0-100>> [--json]`
 
-`openai` Codex プールのしきい値を制御するか、汎用 OAuth プールのしきい値を保存します。`on` は 80%、`off` は 0%、`threshold <n>` は 0–100 を保存します。汎用プールのしきい値は現在適用されません。保存しても、しきい値による切り替え、プロバイダーの有効化設定、429 エラー時のローテーションは変更されません。汎用プールの照会と変更の結果はサーバーの確認値を使用します。汎用プールの `poolEnabled` は保存された設定で、`null` は未指定です。継承後の実効状態ではありません。`inert: true` は未適用を示し、機能が不明な場合も `enabled: true` とは表示しません。API キープロバイダー、Anthropic、不正な値は拒否されます。
+`openai` Codex プールのしきい値を制御するか、汎用 OAuth プールのしきい値を保存します。`on` は 80%、`off` は 0%、`threshold <n>` は 0–100 を保存します。汎用プールのしきい値は `pool.kernel` が有効で `strategy: "fill-first"` の場合にのみ選択へ反映されます。フラグが無効なら、保存してもしきい値による切り替えは有効になりません。いずれの場合もプロバイダーの有効化設定と 429 エラー時のローテーションは変更されません。汎用プールの照会と変更の結果はサーバーの確認値を使用します。汎用プールの `poolEnabled` は保存された設定で、`null` は未指定です。継承後の実効状態ではありません。`inert: true` は保存済みで未適用、`inert: false` はプールが適用中であることを示します。`inert` が無い場合は機能が不明であり、その場合も `enabled: true` とは表示しません。API キープロバイダー、Anthropic、不正な値は拒否されます。
 
 ```text
 openai: { provider, autoSwitchThreshold: number, enabled: boolean }
-generic OAuth: { provider, autoSwitchThreshold: number | null, enabled: boolean, poolEnabled: boolean | null, inert: true | null }
+generic OAuth: { provider, autoSwitchThreshold: number | null, enabled: boolean, poolEnabled: boolean | null, inert: boolean | null }
 ```
 
 ### `ocx account priority <provider> <account-id|main> [<-100..100|first|earlier|normal|later|last|reset>] [--json]`
@@ -213,6 +214,26 @@ security find-generic-password -w openrouter | ocx account add-key openrouter --
 
 アカウントの Codex リセット クレジットを検査します。クレジットの消費は破壊的であり、`--consume` と `--yes` の両方が必要です。
 
+### `ocx account grok-reset-coupons [<account-id>] [--consume --yes [--token-id <id>] [--operation-id <uuid>]] [--json]`
+
+xAI / Grok アカウントの残りリセット クーポンを検査または換金します。
+
+`--consume` を付けずに実行すると、利用可能なクーポン トークンと有効期限ウィンドウを返します:
+
+```bash
+ocx account grok-reset-coupons
+ocx account grok-reset-coupons acc_xai_01 --json
+```
+
+リセット クーポンの換金は請求状態を変更し、クーポン トークンを 1 つ恒久的に消費します。`--consume` には `--yes` が厳密に必要です:
+
+```bash
+ocx account grok-reset-coupons --consume --yes
+ocx account grok-reset-coupons --consume --yes --token-id <token-id>
+```
+
+`--operation-id <uuid>`（有効な UUIDv4 である必要があります）を指定すると、冪等な確定が保証されます。ネットワークが切断されたりコマンドが再試行されたりしても、同一の操作 ID は 2 つ目のクーポンを消費する代わりに、永続化された結果を再生します。
+
 ### `ocx account main <subcommand>`
 
 OpenCodex のアカウントプールルーティングを変更せずに、名前付きのネイティブ Codex メインログインプロファイルを管理します。
diff --git a/docs-site/src/content/docs/ja/reference/configuration/agents.md b/docs-site/src/content/docs/ja/reference/configuration/agents.md
index b4a5106b81..def092132c 100644
--- a/docs-site/src/content/docs/ja/reference/configuration/agents.md
+++ b/docs-site/src/content/docs/ja/reference/configuration/agents.md
@@ -72,9 +72,9 @@ opencodex は、無効、ルーティング不能、異常、冷却期間、ま
   "injectionModel": "gpt-5.5",
   "injectionEffort": "high",
   "syncCodexSubagentDefaults": true,
-  "subagentModelFallback": ["gpt-5.4-mini"],
+  "subagentModelFallback": ["gpt-5.6-luna"],
   "subagentModelFallbackByModel": {
-    "gpt-5.5": ["gpt-5.4-mini"]
+    "gpt-5.5": ["gpt-5.6-luna"]
   },
   "subagentModelFallbackPollMs": 60000,
   "subagentEffortCap": "high"
diff --git a/docs-site/src/content/docs/ja/reference/configuration/providers.md b/docs-site/src/content/docs/ja/reference/configuration/providers.md
index 608e66deb2..5523430c80 100644
--- a/docs-site/src/content/docs/ja/reference/configuration/providers.md
+++ b/docs-site/src/content/docs/ja/reference/configuration/providers.md
@@ -36,8 +36,9 @@ GUI で登録または OAuth ログインが完了すると、Models ページ
 | `codexAccountPickerEnabled?` | `boolean` | map が空なら off | 有効な `codexAccountNamespaces` mapping から account-qualified Codex picker row を生成するかを制御します。`true` は mapping された行の表示を許可します。空でない map で省略した場合は後方互換性のため有効として扱われ、map が空なら off です。`false` は mapping を削除せず、明示的な `<selector>/<native-openai-model>` routing も無効にせずに、生成行を非表示にして picker の bare native 行を復元します。 |
 | `activeCodexAccountId?` | `string` | — |次のリクエスト用に手動で選択されたプール アカウント。選択するとスレッドのアフィニティがクリアされます。実行中のリクエストでは、取得された資格情報が保持されます。 |
 | `codexAccountPriorities?` | `Record<string,number>` | — | Codex pool のアカウント別選択順。アカウント ID → `-100` から `100` の整数で、**大きいほど先に使われ**、未設定は `0` です。これは eligibility ではなく順序の境界です。選択は適格なアカウントを、まだ quota に余裕がある最上位 tier に絞り込み、その tier の中を `accountPoolStrategy` が選びます。tier が飛ばされるのは、そのメンバー全員が `autoSwitchThreshold` 超過、cooldown 中、soft-avoid、一時停止、または再認証待ちのときだけで、usage 不明が tier を drain させることはありません。順序付けが不適格なアカウントを選択可能にすることはなく、すでにアカウントが結び付いた thread を再 bind することもありません。メインの `__main__` も同じ条件で参加するため、Codex Desktop ログインを最後に使わせられます。エントリが 1 つもなければ挙動は従来どおりです。map が不正な場合は警告を出して順序付けを無効にします（config の修復処理は走りません）。`ocx account priority` と Codex Auth ページで管理します。 |
-| `autoSwitchThreshold?` | `number` | `80` | 使用量ベースのプロアクティブ切り替えしきい値。`quota` は紐付け済み/未紐付けタスクの次のリクエストを再評価でき、`fill-first` は未紐付け割り当ての使い切り基準としてのみ使用し、通常の `round-robin` 選択は使用しません。既知の 5 時間、週次、30 日 quota window の最大スコアを使います。`0` は使用量ベースの切り替えだけを無効にし、未紐付け割り当てや障害回復は無効にしません。 |
-| `accountPoolStrategy?` | `"quota" \| "round-robin" \| "fill-first"` | `"quota"` | 新規/未紐付け Codex リクエストの割り当て戦略。live な `(parent thread id, quota scope)` affinity がなければ未紐付けで、プロキシ再起動や affinity リセット後は既存の表示タスクも未紐付けになり得ます。`quota` はアクティブアカウントがなければ既知 usage 最小の適格アカウントを選び、適格なアクティブアカウントが `autoSwitchThreshold` 未満なら維持します。しきい値到達後は、未紐付けリクエストまたは紐付け済みタスクの次のリクエストを usage の低い適格アカウントへ移せます。`round-robin` は未紐付けリクエストを均等分散し、`fill-first` は cooldown、使用不可、または drain threshold までアクティブアカウントへ割り当てます。 |
+| `autoSwitchThreshold?` | `number` | `80` | 使用量ベースのプロアクティブ切り替えしきい値。`quota` は未紐付けタスクの次のリクエストを再評価でき、既定では使用量がこのしきい値を超えると紐付け済みタスクも再評価します。`pool.cacheAffinity` がオンなら、紐付け済みタスクはアカウントが使い切られるか処理できなくなるまでしきい値超過後も同じアカウントを維持します。`fill-first` は未紐付け割り当ての使い切り基準としてのみ使用し、通常の `round-robin` 選択は使用しません。既知の 5 時間、週次、30 日 quota window の最大スコアを使います。`0` は使用量ベースの切り替えだけを無効にし、未紐付け割り当てや障害回復は無効にしません。 |
+| `accountPoolStrategy?` | `"quota" \| "round-robin" \| "fill-first"` | `"quota"` | 新規/未紐付け Codex リクエストの割り当て戦略。live な `(parent thread id, quota scope)` affinity がなければ未紐付けで、プロキシ再起動や affinity リセット後は既存の表示タスクも未紐付けになり得ます。`quota` はアクティブアカウントがなければ既知 usage 最小の適格アカウントを選び、適格なアクティブアカウントが `autoSwitchThreshold` 未満なら維持します。しきい値到達後は未紐付けリクエストを移せます。`pool.cacheAffinity` がオフなら紐付け済みタスクの次のリクエストも usage の低い適格アカウントへ移せます。オンなら紐付け済みタスクはアカウントが使い切られるか（既知 usage 100%）処理できなくなるまで維持されます。`round-robin` は未紐付けリクエストを均等分散し、`fill-first` は cooldown、使用不可、または drain threshold までアクティブアカウントへ割り当てます。 |
+| `pool.cacheAffinity?` | `boolean` | `false` | 紐付け済み Codex スレッド向けのオプトイン cache-affinity 順序。`pool.kernel` とは独立で、既定はオフです。不正な値はオフとして読みます。オンにすると live な紐付けが quota 余裕より優先されます。`quota` は使用量が `autoSwitchThreshold` を超えたという理由だけではスレッドを移しません。一時停止、使用不可、または実際に使い切られたアカウント（既知 usage 100%）では離れるので、affinity は固定ではなく並べ替えです。 |
 | `accountPoolStickyLimit?` | `number` | `1` | 1 回の round-robin 選択で次へ進む前に保持する新規/未紐付けタスク割り当て数。カウンターは上流の成功後ではなくタスクの紐付け時に増えます。範囲 1–100。`accountPoolStrategy` が `round-robin` のときのみ。 |
 | `upstreamFailoverThreshold?` | `number` | `3` |今後の新しいセッションがフェイルオーバーする前に一時的なエラーが連続して発生する。 `0` を無効に設定します。通常のResponses送信とネイティブcompact送信では、実証済みの接続前DNS/TCP到達不能障害はprovider-host単位で記録され、アカウントの健全性、アカウントのクールダウン、スレッド/セッションの親和性、アクティブアカウントの選択、Poolルーティングには影響せず、この閾値にもカウントされません。 |
 | `upstreamHostCircuitThreshold?` | `number` | `0` | ネイティブOpenAI forwardのResponses送信とcompact送信で、実証済みの接続前DNS/TCP障害に適用するオプトインのサーキットしきい値です。`0`で無効、`1`〜`20`ではその回数の終端論理リクエストが失敗するとprovider-originを30秒間遮断します。遮断中はアカウント選択やupstream送信の前に`Retry-After`付き`503`を返し、時間経過後はhalf-openリクエストを1件だけ許可します。タイムアウトとHTTP応答は数えず、HTTP応答が1件でもあれば回路を閉じます。 Codex Pool ルーティングでアカウントが固定されていない場合にのみ適用され、`codexAccountMode: "direct"` とアカウント修飾セレクターでは動作しません。 |
@@ -122,6 +123,7 @@ account を削除しても mapping は保持され、同じ id を再追加す
 | `noTopPModels?` | `string[]` |発信者指定の`top_p`を拒否するモデル。 |
 | `noPenaltyModels?` | `string[]` |存在/周波数ペナルティを拒否するモデル。 |
 | `noStructuredOutputModels?` | `string[]` | `openai-chat` エンドポイントが `response_format` を拒否する正確なモデル ID。要求モデルが項目と完全一致する場合だけフィールドを省略し、その他の `openai-chat` モデルでは structured-output 変換を維持します。 |
+| `noJsonSchemaModels?` | `string[]` | `openai-chat` エンドポイントが `json_schema` 形式は拒否しつつ `json_object` は受け入れる正確なモデル ID。この要求はフィールドを削除せず `json_object` に降格して送るため、JSON を求めた呼び出し側は散文ではなく JSON を受け取れます。両方の一覧に載るモデルでは `noStructuredOutputModels` が優先します。`opencode go` / `opencode zen` / `opencode free` プリセットが DeepSeek 経路に既定で載せます。 |
 | `parallelToolCalls?` | `boolean` |並列ツール呼び出しを切り替えます。 OpenAI Chat はデフォルトでオンになっています。非チャット アダプターは明示的な `true` でのみアドバタイズします。 |
 | `responsesItemIdRepair?` | `{ message?: string[]; reasoning?: string[]; repairMissingTerminalIds?: boolean; repairInvalidIds?: boolean }` |正確なプレースホルダー ID、欠落している端末 ID、および（`repairInvalidIds` で）正規の `msg_`/`rs_` 接頭辞を欠く message/reasoning ID に対するダウンストリーム SSE 修復はデフォルトで無効になっています。関数呼び出し ID は決して書き換えられません。組み込み DeepSeek は最後の 2 つをデフォルトで有効にします。 |
 | `responsesSnapshotRepair?` | `boolean` | デフォルトで無効のクライアント向け修復です。SSE と JSON の Responses ライフサイクルで欠落した status、output、ツールメタデータを補完し、raw 検査と永続化は変更しません。 |
@@ -161,7 +163,8 @@ Clash / Surge / Mihomo 利用者向けの fake-IP DNS 例外は 2 種類あり
 pool アカウントの追加と quota 更新はダッシュボードの **Codex Auth** ページで処理してください。設定には secret で
 ないアカウント metadata だけを保存し、access/refresh token は強化された Codex アカウント credential store に別途
 保管します。Pool routing は新規/未紐付け割り当て、使用量ベースのプロアクティブ切り替え、障害回復に分かれます。
-紐付け済みタスクは通常 affinity を維持しますが、`quota` はしきい値超過後の次のリクエストで再紐付けでき、
+紐付け済みタスクは通常 affinity を維持します。既定では `quota` はしきい値超過後の次のリクエストで再紐付けでき、
+`pool.cacheAffinity` がオンなら、紐付け先アカウントが使い切られるか処理できなくなるまでその再紐付けを延期します。
 pause、cooldown、再認証、障害処理も独立して routing を消去または変更できます。未紐付けリクエストには
 プロキシ再起動や affinity リセット後の既存タスクも含まれます。出力前の **429/402** は使用量ベースの
 切り替えがオフでも同じリクエストで適格な代替アカウントへ 1 回再試行できます。アカウント変更後も会話
@@ -175,7 +178,7 @@ pause、cooldown、再認証、障害処理も独立して routing を消去ま
 別の適格な Pool アカウントへリクエストを切り替えることがあります。これらの障害回復は
 `autoSwitchThreshold: 0` でも有効であり、`0` が無効にするのは使用量に基づく予防的な切り替えだけです。
 
-**割り当てとプロアクティブ切り替え戦略：** `quota`（既定）はアクティブアカウントがない場合に最小 usage の適格アカウントを選び、適格なアクティブアカウントが `autoSwitchThreshold` 未満なら維持します。`autoSwitchThreshold` 超過後は紐付け済みタスクの次のリクエストも再紐付けできます。`round-robin` は
+**割り当てとプロアクティブ切り替え戦略：** `quota`（既定）はアクティブアカウントがない場合に最小 usage の適格アカウントを選び、適格なアクティブアカウントが `autoSwitchThreshold` 未満なら維持します。`autoSwitchThreshold` 超過後は未紐付けリクエストを移せます。`pool.cacheAffinity` がオフなら紐付け済みタスクの次のリクエストも再紐付けできます。オンなら cache affinity が quota 余裕より優先され、紐付け済みタスクはアカウントが使い切られるか（既知 usage 100%）処理できなくなるまで維持されます。`round-robin` は
 未紐付けリクエストを均等分散し、しきい値は通常の rotation を変えません。`accountPoolStickyLimit`
 （既定 `1`、1–100）は成功応答ではなく割り当て/紐付け数を数えます。`fill-first` は未紐付けリクエストを
 cooldown、再認証、または drain threshold までアクティブアカウントへ割り当て、正常な紐付け済みタスクは
@@ -216,7 +219,7 @@ Anthropic アカウント ポリシーのリスクを理解していない限り
 | `failureBackoffMaxSeconds?` | `number` | `3600` |バックオフの上限と永続的な障害による遅延。 |
 | `codexWarmupEnabled?` | `boolean` | `false` |合成 Codex プールアカウント検証をオプトインします。 |
 | `codexWarmupMaxAgeSeconds?` | `number` | `691200` | 8 日後にアカウントを再認証します。 |
-| `codexWarmupModel?` | `string` | `gpt-5.4-mini` |オプションのウォームアップに使用されるネイティブ モデル。 |
+| `codexWarmupModel?` | `string` | `gpt-5.6-luna` |オプションのウォームアップに使用されるネイティブ モデル。 |
 
 ## 固定プロバイダーエンドポイント
 
@@ -436,7 +439,7 @@ Vercel AI Gateway は、1 つのモデルを複数の基盤となる推論プロ
       "baseUrl": "https://ollama.com/v1",
       "apiKey": "${OLLAMA_API_KEY}",
       "defaultModel": "glm-5.2",
-      "noVisionModels": ["glm-5.2", "gpt-oss", "qwen3-coder", "deepseek-v4-pro"]
+      "noVisionModels": ["glm-5.2", "gpt-oss", "qwen3-coder", "deepseek-v4-flash"]
     }
   },
   "subagentModels": ["anthropic/claude-opus-5", "ollama-cloud/glm-5.2"],
diff --git a/docs-site/src/content/docs/ja/reference/configuration/server.md b/docs-site/src/content/docs/ja/reference/configuration/server.md
index b1dd316c7f..0dd9cf59e4 100644
--- a/docs-site/src/content/docs/ja/reference/configuration/server.md
+++ b/docs-site/src/content/docs/ja/reference/configuration/server.md
@@ -153,7 +153,7 @@ OpenAI バックエンドには、ChatGPT ログインと有効な ChatGPT `forw
 | --- | --- | --- | --- |
 | `enabled?` | `boolean` |使用可能な場合はオン |マスターイメージと説明のスイッチ。 |
 | `backend?` | `"openai" \| "anthropic"` |自動 | 明示的な値が優先されます。未設定の場合、使用可能な保存済み Anthropic OAuth 認証情報が優先され、それ以外は `openai` になります。 |
-| `model?` | `string` |バックエンド依存 | OpenAI の場合は `gpt-5.4-mini`、Anthropic の場合は `claude-sonnet-5`。 |
+| `model?` | `string` |バックエンド依存 | OpenAI の場合は `gpt-5.6-luna`、Anthropic の場合は `claude-sonnet-5`。 |
 | `reasoning?` | `"low" \| "medium" \| "high" \| "xhigh" \| "max"` | `"low"` | OpenAI Responses の推論負荷。Anthropic は無視します。 |
 | `maxDescriptionsPerTurn?` | `number` | `8` |新しい説明のキャッシュミスはメインターンごとに許可されます。 `0` は通話を無効にします。無効な値にはデフォルトが使用されます。 |
 | `timeoutMs?` | `number` | `45000` |サイドカーのフェッチタイムアウト。整数 1–2147483647。 |
diff --git a/docs-site/src/content/docs/ja/reference/management-api.md b/docs-site/src/content/docs/ja/reference/management-api.md
index fecada7216..35ebec9131 100644
--- a/docs-site/src/content/docs/ja/reference/management-api.md
+++ b/docs-site/src/content/docs/ja/reference/management-api.md
@@ -64,11 +64,15 @@ Authorization: Bearer <admin-token>
 | `GET /api/grok` | Grok 管理対象設定のステータスと候補モデルを読む | 400 ステータス読み取り失敗 |
 | `PUT /api/grok/selection` |除外された Grok モデルを永続化します。 400 個の無効な選択またはサイズが大きすぎる選択 |
 | `POST /api/grok/apply` |管理された同期を通じて永続的な Grok 設定を適用する | 409 `grok_apply_busy`; 400/500 適用失敗 |
+| `GET /api/grok/reset-coupons?accountId=...` | アクティブまたは指定された xAI アカウントの残り Grok 請求リセット トークンと有効期限ウィンドウを読む | 400 アカウントがありません; 401 未認証; 502 上流 gRPC-Web エラー |
+| `POST /api/grok/reset-coupons/consume` | 対象となるリセット クーポンを換金します。本文は `{ accountId?, tokenId?, operationId? }`。任意の `operationId`（UUIDv4）により換金は冪等になります: 同じ ID を繰り返すと、二重換金せずに永続化された結果を再生します。 | 400 無効な JSON/UUID; 401 未認証; 409 `identity_mismatch`; 502 上流エラー; 503 台帳容量 |
 | `GET, PUT /api/claude-desktop` | Claude Desktop のルーティング/ネイティブ プロファイルを読み取るか永続化する | 400 無効または使用できない割り当て |
 | `POST /api/claude-desktop/apply` |保存したプロファイルを Claude Desktop の管理対象設定に書き込みます。 400/500 書き込み失敗 |
 | `GET /api/claude-desktop/status` |保存済みプロファイルと適用済みプロファイルおよびデスクトップの健全性を検査する | 400 ステータス読み取り失敗 |
 | `GET, PUT /api/claude-code` |クロード コードのゲートウェイ、認証モード、モデル マップ、コンテキスト、エージェント、サイドカー設定の読み取りまたは更新 | 400 無効なフィールドまたは図形 |
 
+ダッシュボードは **Providers > xAI Grok > Accounts** から両方のクーポン パスを操作します。サインイン済みの各アカウント行には残りのクーポン数を示すチケット バッジがあり、バッジは有効期限ウィンドウを一覧し、期限が最も近いクーポンを換金するダイアログを開きます。ダイアログはクライアントが発行した `operationId` を送り、再試行せずタイムアウト後に送信を止めます。ジャーナル記録がまだ開いている換金は再実行されてしまうためです。`ocx account grok-reset-coupons` はターミナル側の同等コマンドです。
+
 モデルロスターと暗号化されたワーカータスクの動作の背後にある概念については、「[サブエージェントサーフェス](/guides/sub-agent-surface/)」を参照してください。
 
 ### クライアント統合のロールバックジャーナル
diff --git a/docs-site/src/content/docs/ja/reference/proxy-formats.md b/docs-site/src/content/docs/ja/reference/proxy-formats.md
index a04596512a..7f875af2f5 100644
--- a/docs-site/src/content/docs/ja/reference/proxy-formats.md
+++ b/docs-site/src/content/docs/ja/reference/proxy-formats.md
@@ -249,6 +249,8 @@ Responses 系列と Chat のリクエストは、専用ヘッダーまたは Bea
 
 キーがなく OAuth を使用しない Cursor ルートは、別途指定された呼び出し元 bearer を使用できますが、プロキシ secret や自動補完された ChatGPT main 認証は使用しません。Combo/policy の選択と実際の shadow/thread-spawn ルート変更では、呼び出し元の生の認証情報を新しい対象へ渡しません。正規の OpenAI ルーティングでは、JWT に ChatGPT アカウントの claim が含まれ、明示的なアカウントヘッダーがある場合はその claim と一致するときに限り、内部ルート変更後にプロキシキーではない呼び出し元の単一 bearer を復元できます。 オプションの OpenAI sidecar に呼び出し元の認証を転送するには、単一の JWT とそれに一致する明示的な `chatgpt-account-id` が必要です。Opaque bearer は、明示的なアカウントヘッダーがあっても、ルート変更をまたいで復元されません。 それ以外の最終対象には自身の設定済み・OAuth・保存済み認証情報が必要で、なければローカルで失敗します。ルート変更のない thread-spawn マーカーだけでは認証情報を削除しません。
 
+設定済みキーのない Cursor への Chat リクエストでは、保存済み main 認証による任意の補完を、OpenAI 補助呼び出しが実際に計画され、canonical Direct の候補が利用可能になるまで延期します。無関係な Cursor リクエストはこの経路で native main を占有せず、プロファイル切り替えを遅らせません。補助認証は起動時と切り替え時の保護に従い、Cursor bearer とは分離されます。Pool およびアカウント指定の補助呼び出しは既存のアカウント選択を維持します。
+
 Claude replay は、その turn が所有権を確保した main 認証だけをメモリ内 snapshot に保持し、最終対象が正規の ChatGPT ルートである場合にのみ復元します。
 
 :::caution
diff --git a/docs-site/src/content/docs/ko/getting-started/quickstart.md b/docs-site/src/content/docs/ko/getting-started/quickstart.md
index 971c15785e..bc83df1b21 100644
--- a/docs-site/src/content/docs/ko/getting-started/quickstart.md
+++ b/docs-site/src/content/docs/ko/getting-started/quickstart.md
@@ -65,7 +65,7 @@ codex -m "ollama-cloud/glm-5.2"      "Write a SQL migration"
 
 ## Sub-agent 모델 선택(선택 사항)
 
-새 구성에는 Codex의 sub-agent 선택기에 네이티브 모델 다섯 개인 `gpt-5.5`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, `gpt-5.4-mini`가 표시됩니다. `ocx gui`를 열어 네이티브 또는 라우팅 모델을 최대 다섯 개까지 바꾸거나 순서를 다시 정할 수 있습니다. 대시보드에서는 선호하는 sub-agent 모델과 추론 강도도 설정할 수 있습니다. [Sub-agent Surface](/guides/sub-agent-surface/)에서 v1/base/v2를 고르고, guidance, 네이티브 기본값, fallback이 언제 적용되는지 확인합니다.
+새 구성에는 Codex의 sub-agent 선택기에 네이티브 모델 다섯 개인 `gpt-5.5`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, `gpt-6-astra`가 표시됩니다. `ocx gui`를 열어 네이티브 또는 라우팅 모델을 최대 다섯 개까지 바꾸거나 순서를 다시 정할 수 있습니다. 대시보드에서는 선호하는 sub-agent 모델과 추론 강도도 설정할 수 있습니다. [Sub-agent Surface](/guides/sub-agent-surface/)에서 v1/base/v2를 고르고, guidance, 네이티브 기본값, fallback이 언제 적용되는지 확인합니다.
 
 ## 키를 붙여넣는 대신 로그인하기
 
diff --git a/docs-site/src/content/docs/ko/guides/claude-code.md b/docs-site/src/content/docs/ko/guides/claude-code.md
index 527c810d42..ca3f5dfb33 100644
--- a/docs-site/src/content/docs/ko/guides/claude-code.md
+++ b/docs-site/src/content/docs/ko/guides/claude-code.md
@@ -559,3 +559,5 @@ Anthropic 백엔드를 명시하면 의도적으로 실패 후 중단해요.
 **서브에이전트가 잘못된 모델로 디스패치됨** — 로스터 에이전트(`ocx-*`)는 Agent 도구의 `model`
 인자가 아니라 `<!-- ocx-route: ... -->` 지시문을 사용해요. 지시문이 원하는 라우트와 일치하는지
 확인하고, 모델 자리 표시자로 `"haiku"`를 전달하세요.
+
+`config.json`에서 `claudeCode.stabilizePromptCache`를 `true`로 설정하면 번역 경로의 시스템 지시 끝에 붙은 지원 대상 Claude 알림을 마지막 사용자 메시지로 옮깁니다. 기본값은 `false`입니다. 사용하는 클라이언트에서 이 역할 변경을 허용할 때만 켜세요. 코드 펜스 안의 예제와 일치하지 않는 원문은 보존하며, Anthropic 원본 전달 경로는 바꾸지 않습니다. 메타데이터가 없는 요청의 캐시 키는 정리된 지시문을 기준으로 계산합니다. 대화 식별자를 만들거나 상위 서비스의 캐시 적중을 보장하는 기능은 아닙니다.
diff --git a/docs-site/src/content/docs/ko/guides/codex-app-models.md b/docs-site/src/content/docs/ko/guides/codex-app-models.md
index 0642712082..23dfd131c6 100644
--- a/docs-site/src/content/docs/ko/guides/codex-app-models.md
+++ b/docs-site/src/content/docs/ko/guides/codex-app-models.md
@@ -97,8 +97,8 @@ visibility = "list"
 
 ## 현재 안정 모델 범위
 
-네이티브 폴백 목록에는 `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`,
-`gpt-5.3-codex-spark`, 그리고 GPT-5.6 Sol/Terra/Luna가 들어 있습니다. GPT-5.5/5.4 계열은 설치된
+네이티브 폴백 목록에는 `gpt-5.5`,
+`gpt-5.3-codex-spark`, 그리고 GPT-5.6 Sol/Terra/Luna가 들어 있습니다. GPT-5.5 계열은 설치된
 Codex 카탈로그의 더 풍부한 실시간 항목을 보존하고, 빠진 항목만 합성합니다. 번들 업스트림 스냅샷은
 GPT-5.6에만 사용합니다. 오래된 템플릿으로 근사하지 않고 모델별 실제 식별 정보와 메타데이터를
 제공하기 위해서입니다.
diff --git a/docs-site/src/content/docs/ko/guides/codex-integration.md b/docs-site/src/content/docs/ko/guides/codex-integration.md
index 584e77adb0..f0c9d87848 100644
--- a/docs-site/src/content/docs/ko/guides/codex-integration.md
+++ b/docs-site/src/content/docs/ko/guides/codex-integration.md
@@ -46,6 +46,83 @@ loopback `openai_base_url` 형태에서만 쓰이고, 그 키와 함께 제거
 
 프록시는 기본적으로 포트 `10100`에서 듣고 `POST /v1/responses`, `POST /v1/responses/compact`, `POST /v1/images/generations`, `POST /v1/images/edits`, `GET /v1/models`, `GET /healthz`, 그리고 `/api/*` 관리 표면을 제공합니다.
 
+### 실험적 컨텍스트 관리 (Codex 0.153+)
+
+지원되는 ChatGPT 계정에서는 Codex의 `config.toml`에 다음 설정을 추가합니다.
+기존 `[features]` 테이블이 있으면 그 안에 병합하세요.
+
+```toml
+[features]
+context_management.experimental_mode = true
+```
+
+기본 내장 loopback 통합에서는 다음 `ocx sync` 또는 프록시 시작 시 관리되는 루트
+`openai_base_url`이 `http://127.0.0.1:10100/backend-api/codex`로 바뀝니다. Codex는 이 경로를
+확인한 뒤 `new_context`, history, notes 도구를 활성화합니다. 동기화 후 새 Codex 세션을
+시작하세요. 이 기능은 명시적으로 켜야 하며, 사용자 소유 URL과 원격 사용자 지정 provider
+주입은 변경하지 않습니다. 컨텍스트 창이나 압축 한도를 덮어쓰지 않습니다.
+
+이 backend 접두사는 Responses WebSocket 업그레이드를 포함한 기존 데이터 경로의 별칭입니다.
+원래 `/v1` 경로와 realtime sideband 오버라이드도 유지됩니다. 열 개의 네이티브
+`alpha/history/v2/*`, `alpha/notes/v2/*` POST 엔드포인트는 `openai-responses` 어댑터와 정식
+ChatGPT forward 목적지를 사용하는 내장 `openai` provider로만 전달합니다. Direct는 현재
+호출자/메인 로그인을, Pool은 선택된 Codex 계정을 사용합니다. `openai-apikey`는 설정된 API
+키를 사용하는 별도 경로이며 이 비공개 엔드포인트를 지원하지 않습니다. 사용자 지정 또는
+비정식 Responses provider는 이 컨텍스트 relay의 후보가 아니며 Codex 계정 자격 증명을
+전달받지 않습니다.
+
+호출자 헤더는 공통 Codex forward 허용 목록으로 제한됩니다. `authorization`,
+`chatgpt-account-id`, 승인된 OpenAI beta, originator, session 및 Codex 프로토콜 메타데이터와
+추가 헤더 `x-openai-encrypted-tool-arguments`, `x-openai-tool-output-truncation-policy`만
+전달합니다. 쿠키 등 임의 헤더는 전달하지 않습니다. 프록시 데이터 키를 bearer로 사용하면
+선택된 Codex 자격 증명으로 교체하며, Direct에서는 저장된 메인 로그인을 사용합니다.
+자격 증명이 없으면 전달 전에 실패합니다. 프록시 인증 자격 증명은 upstream으로 보내지
+않습니다. 암호화된 인수, 응답 본문, upstream 오류 상태는 보존합니다.
+
+소유권은 요청을 받아들인 opencodex API 키 단위로 분리됩니다. 두 키가 같은 ChatGPT 워크스페이스를
+가리키더라도 서로의 세션에 접근할 수 없습니다. 워크스페이스 ID는 사람이 아니라 조직을 가리키므로,
+레지스트리는 업스트림이 실제로 수락한 자격 증명이 담고 있는 사용자 식별자까지 함께 묶습니다. 같은
+사용자의 토큰 갱신은 세션을 이어가지만, 같은 워크스페이스의 다른 사용자는 이어받지 못합니다. 수락된
+자격 증명이 사용자 식별자를 증명하지 못하면 정확히 그 자격 증명만 세션을 이어갈 수 있습니다.
+여기서 principal은 요청이 제시한 opencodex API 키입니다. 원격 바인드는 이미 키를 요구하므로
+소유권이 정상 동작합니다. 기본 loopback 바인드는 키를 읽지 않고 요청을 받아들이고, 내장 loopback
+주입은 `x-opencodex-api-key` 헤더를 실을 수 없습니다. 따라서 Codex가 opencodex 키를 보내지 못해
+context history는 HTTP 403을 반환합니다. **즉 이 relay는 키가 설정된 원격 바인드, 또는
+`x-opencodex-api-key`를 직접 보내는 클라이언트에서 사용할 수 있고 기본 내장 loopback 통합에서는
+사용할 수 없습니다.** loopback 바인드에서 호출자를 식별할 수 있게 할지는 메인테이너가 정할 문제이며,
+지금은 추측하지 않고 거부합니다.
+
+relay 작업 전체는 35초 deadline 하나로 묶입니다. 본문을 읽기 전에 시작해서 자격 증명 선택까지
+포함하므로, 멈춘 클라이언트가 처리 슬롯을 붙잡고 있을 수 없습니다. 클라이언트가 끊으면 499,
+deadline이 지나면 504를 반환하며 두 경우 모두 업스트림으로 아무것도 보내지 않습니다.
+
+성공한 ChatGPT 모델 응답은 루트 세션을 실제로 처리한 계정을 크기가 제한된 프로세스 로컬
+소유권 레지스트리에 기록합니다. History와 notes는 현재 활성 계정이 바뀌어도 명시적으로
+선택된 계정을 포함해 기록된 소유 계정을 사용합니다. 저장된 계정의 토큰은 같은 실제 계정에
+한해 갱신할 수 있으며, 다른 실제 계정으로 교체되면 거부합니다. Direct 호출자 소유 세션은
+호출자 자격 증명을 유지하며 프록시 bearer로 인계할 수 없습니다. 서버 측 history를 계정 간에
+이동하는 기능은 아닙니다.
+
+소유권이 없거나 만료, 제거, 충돌 또는 재시작으로 소실된 경우 계정 선택이나 upstream 요청
+전에 HTTP 409를 반환합니다. 현재 활성 계정으로 추측하지 않습니다. 기존 세션에서는 기능을
+켜거나 컨텍스트를 초기화하기 전에 체크포인트 또는 지속적으로 보관할 요약을 먼저 저장하세요.
+기능을 켜도 이전 history나 notes를 소급해서 채우지 않으며, 소유권이 새로 확인되어도 이전
+backend 콘텐츠가 존재한다는 뜻은 아닙니다. 재시작 후에는 성공한 모델 요청으로 소유권을
+확립한 뒤 컨텍스트 도구를 사용하고, 소유권이 충돌하면 새 세션을 시작하세요.
+
+기존 모델 affinity, cooldown 및 재시도 규칙은 변경하지 않습니다. Notes 쓰기를 포함한
+컨텍스트 요청은 자동 재시도하지 않으며, ChatGPT forward 요청에 같은 키를 사용한 429
+재시도를 추가하지 않습니다. History 트래픽은 모델의 quota-recovery probe를 점유하거나
+완료 처리하지 않습니다.
+
+끄려면 실험 설정을 삭제하거나 `false`로 바꾼 뒤 `ocx sync`를 실행하고 새 세션을 시작하세요.
+관리되는 루트 URL은 `/v1`로 돌아갑니다.
+
+키가 없거나 `false`인 동안에는 relay 자체가 존재하지 않습니다. 열 개 엔드포인트는 직접 POST하는
+호출자에게도 404를 반환하고, 모델 턴은 history 소유권을 기록하지 않습니다. opencodex가 Codex 설정을
+직접 읽어 판단하므로 주입된 URL이나 클라이언트가 보내는 값에 의존하지 않으며, 끄면 재시작 없이
+반영됩니다.
+
 ### 내장 이미지 생성 (`image_gen`)
 
 Codex의 내장 `image_gen` 도구는 `/v1/responses`를 거치지 않습니다. codex-rs 확장은 채팅과 같은 ChatGPT bearer 인증을 사용해서 `{base_url}/images/generations`를 직접 POST하며, 참조 이미지가 붙어 있으면 `/images/edits`를 POST합니다. 주입된 `base_url`이 opencodex를 가리키므로, 프록시가 이 호출을 OpenAI upstream으로 전달합니다.
@@ -134,6 +211,14 @@ upstream 요청 전에 `previous_response_not_found`를 반환합니다. Codex W
 `previous_response_id` 없이 전체 컨텍스트를 다시 보내야 합니다. 같은 ID만 재시도해서는
 누락된 상태를 복구할 수 없습니다.
 
+`statelessResponses: true`로 설정한 routed Responses provider에도 같은 복구 신호가 적용됩니다.
+routed 경로에서 custom 도구를 function으로 낮췄는데 증분 결과에 대응하는 로컬 호출 기록이
+없을 때도 전체 기록을 다시 요청합니다. 호출과 결과, reasoning을 함께 재생하며 결과 유형을
+추측하거나 버리지 않습니다. 상태를 저장하는 provider의 네이티브 function 및 네이티브 custom
+전용 continuation은 그대로 전달됩니다. 이 검사는 모델명이 아니라 선택된 wire protocol과 도구
+선언을 따릅니다. 저장된 response ID를 복원하지 못하는 gateway에는 해당 provider의
+`statelessResponses`를 명시적으로 켜세요. 다른 provider의 기본값은 바뀌지 않습니다.
+
 ## 스레드 식별자와 대화 기록
 
 기본 loopback 형식은 새 thread에 네이티브 `openai` provider 태그를 유지하므로 일반적인 resume history는 다시 매핑할 필요가 없습니다. sync와 restore는 일치하는 백업 manifest만 적용하여 각 thread의 원래 provider, source, event marker를 정확히 복원합니다. manifest가 없는 `opencodex` row는 변경하지 않으며, legacy 재태깅을 명시적으로 강제하려는 경우에만 `ocx recover-history --legacy-openai --yes`를 사용합니다. 이 명령은 의도적으로 범위가 넓습니다. 사용자 메시지가 있고 현재 `opencodex`로 표시된 모든 thread를 `openai`로 바꾸고, `exec`를 `cli`로 정규화하며 event marker를 설정합니다. 정상적인 dedicated-provider history도 포함됩니다. 상태를 백업하고 이 전체 범위를 의도한 경우에만 사용하세요. non-loopback 전용 provider 모드는 활성 상태일 때만 history를 `opencodex` provider 아래로 미러링하고, 종료할 때는 백업된 메타데이터를 복원합니다. history를 건드리지 않으려면 `syncResumeHistory: false`로 설정하세요.
@@ -252,7 +337,7 @@ catalog sync는 선택된 서브에이전트 모델을 Codex가 쓸 수 있게 
 
 ## Codex 계정 워밍업
 
-ChatGPT 계정을 추가하거나 재인증할 때 OpenCodex는 일반적으로 저장 전에 작은 모델 요청으로 확인합니다. `gpt-5.4-mini`의 `response.completed`를 기다리며 HTTP 400 또는 HTTP 404이면 `gpt-5.5`와 `gpt-5.6-luna`로 재시도합니다. 오류에는 고정된 실패 분류만 표시하고 원본 응답 본문은 노출하지 않습니다.
+ChatGPT 계정을 추가하거나 재인증할 때 OpenCodex는 일반적으로 저장 전에 작은 모델 요청으로 확인합니다. `gpt-5.6-luna`의 `response.completed`를 기다리며 HTTP 400 또는 HTTP 404이면 `gpt-5.5`로 재시도합니다. 오류에는 고정된 실패 분류만 표시하고 원본 응답 본문은 노출하지 않습니다.
 
 새 OAuth 토큰으로 인증된 사용량 조회에서 5시간·주간·월간 한도 소진이 확인되면 모델 요청 없이 계정을 저장하고 **검증 대기**로 표시합니다. 재시작이나 토큰 갱신 후에도 요청에 사용되지 않습니다. 한도 회복 후 **사용량 새로고침**을 실행하면, 여유가 있는 완전한 최신 사용량을 확인한 뒤 작은 모델 요청을 보내고 완료 응답을 받아야 계정을 사용할 수 있습니다. 조회나 검증 실패 시 대기 상태를 유지합니다. 일반적인 화면 상태 조회는 이 모델 요청을 보내지 않습니다. 최초 등록 때 사용량이 불명확하면 기존 워밍업 검증이 필요합니다.
 
@@ -274,7 +359,7 @@ ChatGPT 계정을 추가하거나 재인증할 때 OpenCodex는 일반적으로
 ocx config set codexPool '{"excludedPlans":["free"]}'
 ```
 
-차단이 아니라 선택 정책입니다. 제외된 계정도 자격 증명과 사용량 기록, 스레드 어피니티를 그대로 유지하고 계정 목록에도 계속 보이며 `work/gpt-5.4` 같은 명시적 지정으로는 여전히 쓸 수 있습니다. 달라지는 것은 자동 로테이션이 그 계정을 고르지 않는다는 점이고, 이미 활성 계정이거나 스레드에 묶여 있는 경우도 포함합니다. 구독이 만료된 계정이 바로 그 상태입니다.
+차단이 아니라 선택 정책입니다. 제외된 계정도 자격 증명과 사용량 기록, 스레드 어피니티를 그대로 유지하고 계정 목록에도 계속 보이며 `work/gpt-5.5` 같은 명시적 지정으로는 여전히 쓸 수 있습니다. 달라지는 것은 자동 로테이션이 그 계정을 고르지 않는다는 점이고, 이미 활성 계정이거나 스레드에 묶여 있는 경우도 포함합니다. 구독이 만료된 계정이 바로 그 상태입니다.
 
 의도한 제한이 두 가지 있습니다. 메인 Codex 계정은 플랜으로 제외하지 않습니다. 선택 전용 라우팅은 보호된 네이티브 자격 증명을 읽지 않고 플랜을 감추기 때문에, 메인까지 적용하면 상황에 따라 판정이 어긋납니다. 그리고 제외되지 않은 계정이 하나도 남지 않으면 실패시키지 않고 제외된 계정이 그대로 응답합니다. 완전히 멈추려면 지금처럼 모든 계정을 일시 중지하면 됩니다. `minimumPlan`에 해당하는 설정은 없습니다. ChatGPT 플랜에 순위를 매기려면 여기 존재하지 않는 전순서가 필요합니다.
 
@@ -291,3 +376,9 @@ ocx restore back # point plain Codex at the running proxy again
 ```
 
 opencodex가 managed [background service](/reference/cli/#ocx-service)로 실행될 때는 `OCX_SERVICE=1`을 설정하므로 service-driven restart가 Codex config를 흔들지 **않습니다**. 네이티브 Codex를 복원하는 것은 명시적인 `ocx stop` / `ocx service stop`뿐입니다.
+
+## 페이지 분할 기록 보호에 따른 거부
+
+영향받는 기록 저장소가 페이지 분할을 지원하면 프로바이더 전환이 `history_paginated_requires_native_writer`로 거부될 수 있습니다. OpenCodex는 Codex 밖에서 순번을 지정하는 대신 현재 설정, 프로필, 카탈로그, 대화 원본과 복원 근거를 보존합니다. 변환 가능한 저장소의 `legacy` 행도 포함됩니다. 외부 프로바이더 보존처럼 전환을 하지 않는 경로는 계속 사용할 수 있습니다.
+
+대화가 참조하는 프로바이더 정의를 삭제하거나, `ocx sync`·레거시 복구를 반복하거나, 실행 중인 대화 원본을 고쳐 우회하지 마세요. 현재 파일을 보존하고 복구 전에 해당 대화를 닫은 뒤, 개인 대화 내용을 올리지 말고 정확한 오류와 버전을 보고하세요. 네이티브 기록 작성자와 조정하는 검증된 수정이 필요합니다. 백업이나 스크립트 성공만으로 표시 복구가 증명되지는 않으므로 Codex를 다시 열어 확인하세요.
diff --git a/docs-site/src/content/docs/ko/guides/combos.md b/docs-site/src/content/docs/ko/guides/combos.md
index 633feb838b..80eac32c2d 100644
--- a/docs-site/src/content/docs/ko/guides/combos.md
+++ b/docs-site/src/content/docs/ko/guides/combos.md
@@ -119,6 +119,8 @@ ocx combo set balanced \
 
 `reset-window`는 캐시된 공급자 할당량 스냅샷에서 가장 가까운 다음 기간 재설정(5시간, 주간, 월간 또는 사용자 지정)이 표시되는 적합한 대상으로 각 요청을 라우팅합니다. 이렇게 하면 가장 먼저 새로 충전되는 공급자를 사용합니다. 최신 할당량 데이터가 없는 대상과 동률인 대상은 설정 순서를 유지합니다. `weight`와 `stickyLimit`은 이 전략에 영향을 주지 않습니다.
 
+이 순위 결정과 전송 전 공급자 제외에는 현재 단일 API 키의 전체 모델 추론에 적용되는 최신 한도 정보가 필요합니다. OAuth·현재 계정 요약, 호출자 인증을 전달하는 경로, 여러 키, 인증 정보나 목적지가 달라진 스냅샷은 이 사전 판단에서 표시 용도로만 사용합니다. `Authorization`, `x-api-key`, `x-goog-api-key` 헤더로 인증을 덮어쓰는 경우도 같으며, 검색 전용·MCP 전용 기간은 제외합니다. 적격 대상 중 적용 가능한 초기화 정보가 없으면 설정 순서를 따릅니다. 실제 계정 선택과 재시도에는 기존 제한이 계속 적용됩니다.
+
 ## 대상 실패 시 동작
 
 콤보 실패는 **홉** 실패와 **종결** 실패로 나뉩니다.
@@ -185,9 +187,7 @@ v1/base/v2 모드와 암호화된 작업의 전체 흐름은 [Sub-agent Surface]
 
 로컬 대시보드를 열고 **Models → Combos**를 선택합니다. 워크스페이스는 콤보를 만들고, 편집하고, 이름을 바꾸고, 제거할 수 있으며, 대상 선택기에서는 비활성 모델과 중첩 콤보를 제외합니다.
 
-각 대상에는 **사용 가능**, **할당량 소진**, **할당량 알 수 없음** 실시간 배지도 표시됩니다. 저장과 만들기 버튼은
-활성화된 모든 대상에 할당량 소진을 입증하는 최신의 완전한 증거가 있을 때만 비활성화됩니다. 누락되거나 오래되거나
-형식이 잘못되었거나 집계가 불완전한 데이터는 알 수 없음으로 남으며 버튼을 잠그지 않습니다. 할당량이 복구되면 버튼도 자동으로 다시 활성화됩니다. 대시보드 편집기에서는 아직 `cooldownMs`나 `waitForCooldownMs`를 설정할 수 없습니다. 후속 UI 작업이 완료될 때까지 구성 파일이나 관리 API를 사용하세요.
+각 대상에는 **사용 가능**, **할당량 소진**, **할당량 알 수 없음** 실시간 배지도 표시됩니다. 편집기는 사용 가능한 모든 대상에 대해 설정된 인증 정보의 추론 한도가 소진되었다는 서버 확인이 현재 유효할 때만 할당량을 이유로 저장과 만들기를 차단합니다. 표시 전용 계정·모델·검색·MCP 할당량이나 누락되거나 만료된 라우팅 근거 정보는 이 차단을 일으키지 않습니다. 차단은 해당 한도의 초기화 시점이나 데이터 유효기간이 끝나면 해제되며 페이지가 활성화되거나 표시될 때 다시 확인됩니다. 새로 고침은 콤보 데이터와 할당량을 모두 다시 불러옵니다. 대시보드 편집기에서는 아직 `cooldownMs`나 `waitForCooldownMs`를 설정할 수 없습니다. 후속 UI 작업이 완료될 때까지 구성 파일이나 관리 API를 사용하세요.
 
 ### CLI
 
diff --git a/docs-site/src/content/docs/ko/guides/providers.md b/docs-site/src/content/docs/ko/guides/providers.md
index 20b5b4fe77..4f35396cff 100644
--- a/docs-site/src/content/docs/ko/guides/providers.md
+++ b/docs-site/src/content/docs/ko/guides/providers.md
@@ -85,8 +85,9 @@ ChatGPT 패스스루 카탈로그에는 GPT-5.6 Sol/Terra/Luna의 네임스페
 
 OAuth 로그인을 사용하는 프로바이더 프리셋은 여덟 개이며, 여기에 실험적 비공식 디바이스 플로우
 브리지를 쓰는 GitHub Copilot이 추가됩니다. 자격 증명은 `~/.opencodex/auth.json`에 저장되고
-자동으로 갱신됩니다. 로그인 CLI는 `chatgpt`도 받습니다. 이 명령은 ChatGPT 자격 증명을
-발급받고 `forward` 모드 프로바이더 항목을 만듭니다.
+자동으로 갱신됩니다. `ocx login codex`도 받지만 이건 위 프로바이더가 아닙니다. Codex 계정 풀
+로그인(`ocx account login codex`와 같은 흐름)으로 연결되고, 이 풀은 자체 계정 원장을 쓰기 때문에
+프록시가 실행 중이어야 합니다. `chatgpt`와 `openai`는 같은 경로의 별칭입니다.
 
 ```bash
 ocx login xai          # xAI Grok
@@ -97,8 +98,9 @@ ocx login kiro         # kiro-cli 자격 증명 가져오기(토큰 폴백 지
 ocx login google-antigravity
 ocx login cursor       # Cursor 전용 PKCE 로그인
 ocx login command-code # Command Code 브라우저 OAuth (또는 ~/.commandcode/auth.json 가져오기)
+ocx login devin       # Cognition/Devin Auth0 브라우저 로그인
 ocx login github-copilot  # GitHub 디바이스 플로우 → Copilot 토큰 (Copilot Pro/Business)
-ocx login chatgpt      # 별도 ChatGPT OAuth 로그인
+ocx login codex        # Codex 계정 풀 (별칭: chatgpt, openai / 프록시가 실행 중이어야 함)
 ocx logout <provider>
 ```
 
@@ -111,6 +113,8 @@ ocx logout <provider>
 | `kiro` | `kiro` | `https://runtime.us-east-1.kiro.dev` | 최초 로그인은 설치하고 로그인한 `kiro-cli` 세션을 가져옵니다(Unix에서는 `curl -fsSL https://cli.kiro.dev/install` &#124; `bash`, Windows PowerShell에서는 `irm 'https://cli.kiro.dev/install.ps1'` &#124; `iex`로 설치한 뒤 `kiro-cli login` 실행). **계정 추가**는 `kiro-cli`에서 로그아웃한 뒤 새 브라우저 로그인을 시작하여 `kiro-cli` 자체의 계정을 전환하고, 계정별 프로필 메타데이터를 저장합니다. 기존 OpenCodex 계정은 유지되며, 취소되거나 실패하면 이전 `kiro-cli` 세션을 복원합니다. |
 | `google-antigravity` | `google` | `https://daily-cloudcode-pa.googleapis.com` | Google OAuth를 Cloud Code Assist wire로 사용합니다. 실시간 탐색은 인증된 CCA `v1internal:fetchAvailableModels` 엔드포인트를 사용하며 로그인한 계정에서 사용할 수 있는 agent 모델만 게시합니다. 유지 관리되는 카탈로그는 폴백으로 남습니다. |
 | `cursor` | `cursor` | `https://api2.cursor.sh` | 실험적 PKCE 로그인, HTTP/2 전송, 계정별 모델 탐색을 지원합니다. |
+| `devin` | `devin` | `https://server.codeium.com` | 실험적인 비공식 Cognition/Devin 브리지. 로그인은 Auth0 브라우저 사인인을 열고, 받은 토큰을 `RegisterUser`로 교환해 장기 API 키를 얻습니다. 모델 목록은 `GetCascadeModelConfigs`로 계정마다 조회하며, 스트리밍은 Connect-RPC 위에서 `runTurn` 경로만 씁니다. 대시보드 프리셋에는 기본으로 없으니 직접 추가하세요. |
+| `devin-cli` | `devin` | `https://server.codeium.com` | 설치된 Devin CLI가 이미 들고 있는 자격증명을 가져옵니다(`devin auth login`이 자기 `credentials.toml`에 씁니다). 그다음은 `devin` 프로바이더와 똑같이 Cognition의 Connect-RPC api-server로 스트리밍합니다. 브라우저 로그인도, 붙여넣을 키도 없습니다. 모델 목록과 컨텍스트 윈도우는 계정 카탈로그에서 실시간으로 옵니다. CLI 자체의 로컬 에이전트 루프(ACP stdio)를 쓰려면 이름이 다른 행에 `"adapter": "devin-cli"`를 지정하세요. |
 | `github-copilot` | `openai-chat` | `https://api.githubcopilot.com` | 실험적. GitHub 디바이스 플로우 + `copilot_internal` 교환(VS Code OAuth 클라이언트). 활성 Copilot 구독 필요; 공식 서드파티 API가 아닙니다. |
 
 Google Antigravity 계정·제공자 할당량 확인은 모델 목록 폴백을 포함해 고정된 Google 회계 엔드포인트를 사용합니다. 해당 목적지의 투명 Fake-IP DNS를 지원하며 TLS 검증, 리다이렉트 거부, 사설 주소 검사는 유지합니다. 사용자 지정 base URL은 모델 요청에만 적용되며 할당량 목적지는 바꾸지 않습니다. `NO_PROXY`는 기존 직접 연결 정책을 유지합니다.
@@ -247,7 +251,7 @@ Volcengine Agent Plan은 `openai-responses` 어댑터로 네이티브 Responses
 > Embedding, 이미지, 비디오, 3D 리소스도 반환하고 Coding 게이트웨이도 같은 광범위한 카탈로그를
 > 반환합니다. Agent Plan 게이트웨이에는 `/models` 리소스가 없습니다. 종량제 기본값은
 > `doubao-seed-2-1-pro-260628`이며 정적 카탈로그에는 현재 DeepSeek와 GLM 텍스트 모델도
-> 포함됩니다. Coding Plan의 기본값은 `ark-code-latest`, Agent Plan은 `deepseek-v4-pro`입니다.
+> 포함됩니다. Coding Plan의 기본값은 `ark-code-latest`, Agent Plan은 `deepseek-v4-flash`입니다.
 
 **Chutes 검색:** `chutes` 프리셋은 Chutes의 고정된 공유 OpenAI 호환 LLM gateway를 사용합니다.
 공개 `/v1/models` catalog에서 `supported_features`가 `tools`를 명시한 행만 유지하고, 슬래시가 포함된
@@ -416,7 +420,7 @@ Ollama Cloud는 호스팅형(로컬이 아님) Ollama입니다. `https://ollama.
 표면이 아니라 Ollama 자체 REST API(`POST /api/chat`)로 연결하며, 모델 목록을 공급자에서 직접
 발견하므로 새 Ollama Cloud 모델이 설정 변경 없이 나타납니다. opencodex는 클라우드
 라인업을 비전 기능에 따라 분류하여 [비전 사이드카](/ko/guides/sidecars/)가 텍스트 전용 모델에만
-작동하도록 합니다. 텍스트 전용 모델(예: `glm-5.2`, `deepseek-v4-pro`, `gpt-oss`, `qwen3-coder`,
+작동하도록 합니다. 텍스트 전용 모델(예: `glm-5.2`, `deepseek-v4-flash`, `gpt-oss`, `qwen3-coder`,
 `minimax-m2.x`, `nemotron-3-*`)은 `noVisionModels`에 나열되며, 비전 네이티브 모델(예:
 `kimi-k2.6`, `minimax-m3`, `gemma4`, `qwen3.5`, `gemini-3-flash-preview`)은 포함되지 않습니다. 매칭은
 Ollama의 `:size` 태그에 관대하므로 `gpt-oss`는 `gpt-oss:120b`와 `gpt-oss:20b`를 모두 포괄합니다.
diff --git a/docs-site/src/content/docs/ko/guides/sidecars.md b/docs-site/src/content/docs/ko/guides/sidecars.md
index 55af37a150..b3d4309dbf 100644
--- a/docs-site/src/content/docs/ko/guides/sidecars.md
+++ b/docs-site/src/content/docs/ko/guides/sidecars.md
@@ -78,7 +78,7 @@ stall은 전체 생성 timeout이 아닙니다. SSE가 시작되기 전 실패
 콤보는 모든 멤버가 네이티브로 또는 사이드카를 통해 이미지를 수용하고 콤보의 `imageInput` 설정이 비활성화되지 않은
 경우에만 image input을 알립니다. 따라서 Codex 앱 같은 클라이언트는 사이드카가 실행되기 전에 첨부를 차단하지 않고 허용합니다.
 `visionSidecar.model`이 없거나 빈 값이면
-OpenAI 실행 경로, Dashboard, 관리 API는 `gpt-5.4-mini`를 폴백으로 사용합니다. 시작 시 명시적으로
+OpenAI 실행 경로, Dashboard, 관리 API는 `gpt-5.6-luna`를 폴백으로 사용합니다. 시작 시 명시적으로
 저장된 기존 `gpt-5.4-mini` 값은 계속 `gpt-5.6-luna`로 마이그레이션되지만, 이 마이그레이션은 저장된
 값에만 적용되고 모델 필드가 없는 경우에는 적용되지 않습니다.
 
@@ -127,7 +127,7 @@ OpenAI 실행 경로, Dashboard, 관리 API는 `gpt-5.4-mini`를 폴백으로 
   "providers": {
     "ollama-cloud": {
       "baseUrl": "https://ollama.com/v1",
-      "noVisionModels": ["glm-5.2", "gpt-oss", "qwen3-coder", "deepseek-v4-pro"]
+      "noVisionModels": ["glm-5.2", "gpt-oss", "qwen3-coder", "deepseek-v4-flash"]
     }
   }
 }
diff --git a/docs-site/src/content/docs/ko/guides/sub-agent-surface.md b/docs-site/src/content/docs/ko/guides/sub-agent-surface.md
index 1372ed7c15..c0273412ec 100644
--- a/docs-site/src/content/docs/ko/guides/sub-agent-surface.md
+++ b/docs-site/src/content/docs/ko/guides/sub-agent-surface.md
@@ -117,7 +117,7 @@ ocx v2 threads 8
 ocx agent status
 ocx agent injection set --model anthropic/claude-sonnet-5 --effort xhigh
 ocx agent subagents set gpt-5.6-sol,anthropic/claude-sonnet-5
-ocx agent fallback set gpt-5.4-mini,xai/grok-4.5 --poll-ms 60000
+ocx agent fallback set gpt-5.6-luna,xai/grok-4.5 --poll-ms 60000
 ocx agent effort set --subagent max
 ```
 
diff --git a/docs-site/src/content/docs/ko/guides/web-dashboard.md b/docs-site/src/content/docs/ko/guides/web-dashboard.md
index efdd80179f..4ae2762b1a 100644
--- a/docs-site/src/content/docs/ko/guides/web-dashboard.md
+++ b/docs-site/src/content/docs/ko/guides/web-dashboard.md
@@ -39,7 +39,7 @@ bun run dev:gui
 | **Windows 트레이** | 로그인할 때 사용자 전용 트레이를 시작하고 프록시 시작·중지·재시작·대시보드·상태를 클릭으로 제어합니다. 트레이는 재시작 서비스가 아닙니다. |
 | **Codex 자동 시작** | 이미 설치된 Codex launcher shim이 `ocx ensure`를 실행하도록 허용합니다. 이 토글은 shim이나 백그라운드 서비스를 설치하지 않습니다. |
 | **Providers** | 프로바이더를 추가, 편집, 기본으로 설정(활성만), 활성화/비활성화, 제거하고, 지원되는 OAuth 계정 풀과 API key 풀을 관리합니다. 현재 기본 프로바이더를 제거하면 남아 있는 첫 번째 활성 프로바이더로 전환됩니다(있는 경우); 없으면 삭제가 거부되고 현재 기본이 유지됩니다. Claude(Anthropic) OAuth 풀에서는 로그인한 계정마다 자체 5시간·주간 한도 막대가 표시되며(사용량은 자격 증명 단위), 조회 실패 시 마지막 값을 유지하고 일시 불가 상태로 표시합니다. 프로바이더를 선택하지 않았을 때 보이는 Provider Overview에는 **전체 할당량 갱신** 버튼이 있어 설정된 모든 프로바이더를 서버에서 한 번에 다시 읽습니다. 조회에 실패한 프로바이더는 마지막 값을 유지하므로, 상태 문구는 모든 값이 새로 왔다고 말하지 않고 조회가 끝났다고만 알리며, 각 행의 확인 시각이 프로바이더별 신선도를 보여 줍니다. |
-| **Add provider** | 레지스트리 기반 프리셋에서 계정 로그인, API key 서비스, 로컬 서버, custom endpoint를 검색합니다. |
+| **Add provider** | 탭 위의 검색창 하나가 계정·무료·로컬·유료 네 탭을 한 번에 찾습니다. 검색 중에는 선택한 탭이 움직이지 않고, 결과를 탭별로 묶어 개수와 함께 보여 줍니다. 로컬 런타임(Ollama, vLLM, LM Studio, LiteLLM)은 별도 탭을 쓰며, 긴 설명은 두 줄로 줄고 클릭하면 전체가 열립니다. |
 | **Codex Auth** | ChatGPT/Codex 풀 계정을 추가하고, 다음 세션 계정을 선택하고, 5시간 / 주간 / 30일 할당량을 갱신하며, 할당량 자동 전환을 켜거나 끄고 1~100% 임계값과 일시적 실패 failover를 설정합니다. |
 | **Subagents** | `spawn_agent` override 목록에 네이티브 또는 라우팅 모델을 최대 5개까지 우선 노출합니다. |
 | **Models** | 네이티브 GPT와 라우팅 모델을 켜고 끄고, 프로바이더 allowlist와 컨텍스트 상한, v1/base/v2, v2 thread 수를 설정합니다. |
diff --git a/docs-site/src/content/docs/ko/reference/adapters.md b/docs-site/src/content/docs/ko/reference/adapters.md
index c086eb4c11..ceadeb5cc4 100644
--- a/docs-site/src/content/docs/ko/reference/adapters.md
+++ b/docs-site/src/content/docs/ko/reference/adapters.md
@@ -210,6 +210,16 @@ discovery에 모두 적용됩니다.
   더 넓은 내장 executor를 켜며 Codex 승인/샌드박스 규칙을 우회합니다. 예전 설정인
   `unsafeAllowNativeLocalExec: true`는 `nativeLocalExec`을 지정하지 않았을 때만 같은 뜻입니다.
 
+## `devin`
+
+**대상:** Cognition의 `exa.api_server_pb.ApiServerService/GetChatMessage`(`server.codeium.com`, Connect 스트리밍).
+**인증:** `provider.apiKey` 또는 전달된 authorization 헤더의 Devin/Cognition API 키. 로그인은 Auth0 브라우저 사인인을 연 뒤 `SeatManagementService.RegisterUser`로 장기 키를 받습니다.
+
+- 일반 fetch/parse 대신 `runTurn`을 씁니다. 요청과 서버 이벤트는 `devin/cloud-direct/wire.ts`의 수동 protobuf 프레이밍으로 다룹니다.
+- `GetCascadeModelConfigs`로 계정별 모델을 조회하고, 플랜에 없는 모델은 요청 시점이 아니라 목록에서 걸러집니다.
+- Cognition은 도구 설명 길이 제한과 정확 문구 차단 목록을 적용합니다. 어댑터가 알려진 문구를 바꾸고 긴 설명을 잘라냅니다.
+- 키는 갱신되지 않습니다. 만료되거나 폐기되면 `ocx login devin`을 다시 실행하세요.
+
 ## `azure-openai` (별칭: `azure`)
 
 **대상:** **Azure OpenAI**. `openai-responses`를 감싸므로 마찬가지로 `passthrough: true`입니다.
diff --git a/docs-site/src/content/docs/ko/reference/cli/agents.md b/docs-site/src/content/docs/ko/reference/cli/agents.md
index 76cef4bda7..82f776b782 100644
--- a/docs-site/src/content/docs/ko/reference/cli/agents.md
+++ b/docs-site/src/content/docs/ko/reference/cli/agents.md
@@ -152,7 +152,7 @@ Grok Build model fence를 관리하고 적용합니다.
 
 ## 클라이언트 설정 내보내기
 
-### `ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|prime|aside|raycast>`
+### `ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|prime|aside|raycast|omo>`
 
 실행 중인 프록시에 연결할 client config를 출력합니다. 이 명령은 base URL, model list, 그리고 client에 따라 credential reference 또는 `opencodex-loopback` placeholder를 포함한 `opencodex` provider block을 선택한 client의 네이티브 형식으로 직렬화합니다.
 
@@ -160,7 +160,7 @@ Grok Build model fence를 관리하고 적용합니다.
 
 | 플래그 | 동작 |
 | --- | --- |
-| `--client <opencode\|pi\|omp\|hermes\|openclaw\|kimi\|gajae\|dsh\|mcode\|zcode\|prime\|aside\|raycast>` | 필수입니다. 클라이언트 설정 형식을 선택합니다. |
+| `--client <opencode\|pi\|omp\|hermes\|openclaw\|kimi\|gajae\|dsh\|mcode\|zcode\|prime\|aside\|raycast\|omo>` | 필수입니다. 클라이언트 설정 형식을 선택합니다. |
 | `--json` | config JSON만 stdout에 출력하므로, redirect가 byte-exact 출력을 캡처합니다. `--out` write note를 포함한 모든 진단 메시지는 stderr로 갑니다. |
 | `--out <path>` | config를 `<path>`에 씁니다. 기존 파일이 있으면 덮어쓰지 않습니다. |
 | `--force` | `--out`이 기존 파일을 덮어쓰도록 허용합니다. |
@@ -187,7 +187,9 @@ ocx export --client opencode --out ~/opencodex-opencode.json
 | `mcode` | `~/.minimax/config.yaml` (`MINIMAX_DATA_DIR`, 그다음 레거시 `MAVIS_DATA_DIR`가 설정되면 우선. 상대 경로는 거부됩니다) | `mcode-config.yaml` | 없음 — loopback placeholder |
 | `zcode` | `~/.zcode/v2/config.json` (`ZCODE_DATA_DIR`가 설정되면 우선. 상대 경로는 거부됩니다) | `config.json` | 없음 — loopback placeholder |
 | `prime` | `~/.prime/agent/models.json` (`PRIME_AGENT_CODING_AGENT_DIR`가 설정되면 우선. 상대 경로는 거부됩니다) | `prime-models.json` | 없음 — loopback placeholder |
+| `aside` | `~/.aside/u/<account>/models.json`. Aside의 `accounts.json`이 현재 계정으로 지정한 account를 사용합니다. 매니페스트를 읽을 수 없으면 임의의 계정으로 넘어가지 않고 거부합니다 | `aside-models.json` | 없음 — loopback placeholder |
 | `raycast` | `~/.config/raycast/ai/providers.yaml` (macOS와 Windows 모두 동일. Raycast는 `XDG_CONFIG_HOME`을 따르지 않습니다) | `raycast-providers.yaml` | 없음 — loopback 전용. `api_keys` 항목은 쓰지 않습니다 |
+| `omo` | `~/.omo/agent/models.json` (`OMO_CODING_AGENT_DIR`, `SENPI_CODING_AGENT_DIR`, `PI_CODING_AGENT_DIR` 순서로 설정된 값이 우선. 상대 경로는 거부됩니다) | `omo-models.json` | 없음 — loopback placeholder |
 
 Raycast 내보내기는 `providers` 시퀀스에 `id: opencodex` 요소 하나만 담은 독립 `providers.yaml` 문서입니다. 내용은 `name: OpenCodex`, proxy의 `/v1` base URL, 그리고 `abilities`가 붙은 라우팅된 모든 모델입니다(`tools`와 `system_message`는 항상 지원, `vision`은 카탈로그의 입력 모달리티를 따름, `reasoning_effort`는 모델에 effort 사다리가 있을 때, `temperature`는 추론 모델에서 꺼짐). Custom Providers는 Raycast Pro 기능이며, Raycast가 이 파일을 감시하므로 저장한 변경은 재시작 없이 적용됩니다. 형식은 [manual.raycast.com/ai/custom-providers](https://manual.raycast.com/ai/custom-providers)에 문서화되어 있습니다. `api_keys` 항목은 쓰지 않으므로 이 내보내기는 loopback 전용이며, loopback이 아닌 bind는 거부됩니다.
 
@@ -197,7 +199,7 @@ opencode는 `{env:OPENCODEX_OPENCODE_API_KEY}`를 보간합니다. opencodex가
 `ocx export`는 실제 client config를 절대 쓰지 않습니다. 대상 경로는 손으로 병합하라고 출력되며, `--out`은 `--force` 없이 기존 파일을 덮어쓰지 않습니다. config를 바꾸어 덮어쓰면 이미 들어 있던 다른 provider, agent, MCP entry가 사라지기 때문입니다.
 :::
 
-어떤 key도 직렬화되지 않습니다. 생성되는 config에는 문서화된 env reference 또는 비밀이 아닌 loopback placeholder 중 하나가 들어갑니다. loopback proxy(`127.0.0.1`, 기본값)는 admission key가 전혀 필요하지 않습니다. proxy가 loopback을 넘어 바인딩할 때는 해당하는 `OPENCODEX_OPENCODE_API_KEY`, `OPENCODEX_HERMES_API_KEY`, `OPENCODEX_OPENCLAW_API_KEY`를 설정하십시오. `OPENCODEX_GAJAE_API_KEY`는 Gajae provider 인증 값을 환경에서 전달하지만 remote admission header를 보낼 수는 없으므로, 생성되는 Gajae 통합은 loopback 전용으로 남습니다. admission key가 어떻게 발급되는지는 [Remote access](/reference/configuration/#remote-access)를 보십시오. upstream provider 자체의 key는 완전히 별개의 것으로, 각 [Providers](/guides/providers/)에 맞게 설정합니다.
+어떤 key도 직렬화되지 않습니다. 생성되는 config에는 문서화된 env reference 또는 비밀이 아닌 loopback placeholder 중 하나가 들어갑니다. loopback proxy(`127.0.0.1`, 기본값)는 admission key가 전혀 필요하지 않습니다. proxy가 loopback을 넘어 바인딩할 때는 해당하는 `OPENCODEX_OPENCODE_API_KEY`, `OPENCODEX_HERMES_API_KEY`, `OPENCODEX_OPENCLAW_API_KEY`를 설정하십시오. `OPENCODEX_GAJAE_API_KEY`는 gjc provider 인증 값을 환경에서 전달하지만 remote admission header를 보낼 수는 없으므로, 생성되는 gjc 통합은 loopback 전용으로 남습니다. admission key가 어떻게 발급되는지는 [Remote access](/reference/configuration/#remote-access)를 보십시오. upstream provider 자체의 key는 완전히 별개의 것으로, 각 [Providers](/guides/providers/)에 맞게 설정합니다.
 
 같은 payload는 `GET /api/client-config`로 제공되고 dashboard의 API 탭에도 렌더링되므로, CLI, API, GUI가 모두 같은 바이트를 사용합니다.
 
diff --git a/docs-site/src/content/docs/ko/reference/cli/providers-accounts.md b/docs-site/src/content/docs/ko/reference/cli/providers-accounts.md
index fd99e29147..0fc4bc2608 100644
--- a/docs-site/src/content/docs/ko/reference/cli/providers-accounts.md
+++ b/docs-site/src/content/docs/ko/reference/cli/providers-accounts.md
@@ -61,7 +61,7 @@ ocx models live --provider ark --json
 
 제공자에 등록된 로그인 흐름을 시작합니다. OAuth 제공자는 브라우저를 열고 자동 갱신되는 자격 증명을 `~/.opencodex/` 아래에 저장합니다. API 키 로그인 제공자는 키 대시보드를 열고, 키 입력을 요청한 뒤, 가능한 경우 검증하고, 그 결과 나온 제공자 설정을 저장합니다. 이름이 없거나 알 수 없으면 현재 허용되는 OAuth 및 API 키 제공자 id를 출력합니다.
 
-`ocx status` / `ocx doctor`가 재인증 필요 또는 터미널 새로고침 실패를 보고한 뒤에는 같은 명령으로 **재인증**하면 됩니다(대시보드의 Reauthenticate를 써도 됩니다). Codex 풀 계정은 공개 `ocx login` 제공자가 아닙니다. 대신 대시보드의 Codex 계정 풀(Reauthenticate)이나 헤드리스 `ocx account reauth` 흐름으로 재인증해야 합니다.
+`ocx status` / `ocx doctor`가 재인증 필요 또는 터미널 새로고침 실패를 보고한 뒤에는 같은 명령으로 **재인증**하면 됩니다(대시보드의 Reauthenticate를 써도 됩니다). Codex 풀 계정은 위 OAuth·API 키 제공자 중 하나가 아니지만 `ocx login codex`로 닿습니다. 이 명령은 계정 풀 로그인으로 연결되므로 `ocx login codex --reauth`는 `ocx account reauth codex`와 같습니다. 대시보드의 Codex 계정 풀(Reauthenticate)로도 됩니다. 이 경로는 프록시 안에서 돌기 때문에 프록시가 실행 중이어야 합니다.
 
 ```bash
 ocx login xai
@@ -145,7 +145,7 @@ Luna 메타데이터임을 표시해 사용합니다. 목록에 보인다는 사
 실행 중인 프록시를 통해 제공자 계정과 API 키 풀을 나열하고 전환합니다. 제공되는 도움말 표면은 다음과 같습니다:
 
 ```text
-Usage: ocx account <list|current|use|refresh|auto-switch|priority|login|reauth|code|cancel|remove|add-key|reset-credits> ...
+Usage: ocx account <list|current|use|refresh|auto-switch|priority|login|reauth|code|cancel|remove|add-key|reset-credits|grok-reset-coupons> ...
 
 list [provider]     Codex account pool, OAuth accounts and API keys (identifiers shown masked as the API returns them).
 current <provider>  Show the active account or key.
@@ -157,6 +157,7 @@ remove <provider> <id> --yes  Remove a stored account or key after an existence
 add-key <provider> [--label <label>]  Add a key read only from piped stdin.
 login/reauth/code/cancel  Run browser or manual-code auth from a headless shell.
 reset-credits <id|main> [--consume --yes]  Inspect or consume Codex reset credits.
+grok-reset-coupons [<id>] [--consume --yes] [--token-id <token-id>] [--operation-id <uuid>]  Inspect or redeem Grok reset coupons.
 Codex pool selection applies to the next request after clearing existing affinity; in-flight requests keep their captured account.
 ```
 
@@ -218,11 +219,11 @@ OAuth 및 API 키 제공자에는 제공자의 할당량 보고 엔드포인트
 
 ### `ocx account auto-switch <provider> <on|off|status|threshold <0-100>> [--json]`
 
-`openai` Codex 풀의 임계값을 제어하거나 일반 OAuth 풀의 임계값을 저장합니다. `on`은 80%, `off`는 0%, `threshold <n>`은 0–100을 저장합니다. 일반 풀의 임계값은 현재 동작에 적용되지 않습니다. 저장해도 임계값 기반 전환이나 제공자 활성화 설정이 바뀌지 않고, 429 오류에 따른 회전도 비활성화되지 않습니다. 일반 풀의 조회와 변경 결과는 서버가 확인한 값을 사용합니다. 일반 풀의 `poolEnabled`는 저장된 제공자별 설정이며 `null`은 미지정입니다. 전역 설정을 상속한 실제 상태를 뜻하지 않습니다. `inert: true`이면 임계값이 적용되지 않으며, 기능 지원을 알 수 없을 때도 `enabled: true`로 표시하지 않습니다. API 키 제공자, Anthropic 및 잘못된 값은 거부합니다.
+`openai` Codex 풀의 임계값을 제어하거나 일반 OAuth 풀의 임계값을 저장합니다. `on`은 80%, `off`는 0%, `threshold <n>`은 0–100을 저장합니다. 일반 풀의 임계값은 `pool.kernel`이 켜져 있고 `strategy: "fill-first"`일 때만 선택에 반영됩니다. 플래그가 꺼져 있으면 저장해도 임계값 기반 전환이 켜지지 않습니다. 어느 쪽이든 제공자 활성화 설정은 바뀌지 않고, 429 오류에 따른 회전도 비활성화되지 않습니다. 일반 풀의 조회와 변경 결과는 서버가 확인한 값을 사용합니다. 일반 풀의 `poolEnabled`는 저장된 제공자별 설정이며 `null`은 미지정입니다. 전역 설정을 상속한 실제 상태를 뜻하지 않습니다. `inert: true`는 임계값이 저장만 되고 적용되지 않는 상태, `inert: false`는 풀이 실제로 적용하고 있는 상태를 뜻합니다. `inert`가 아예 없으면 기능 지원을 알 수 없는 경우이며, 이때도 `enabled: true`로 표시하지 않습니다. API 키 제공자, Anthropic 및 잘못된 값은 거부합니다.
 
 ```text
 openai: { provider, autoSwitchThreshold: number, enabled: boolean }
-generic OAuth: { provider, autoSwitchThreshold: number | null, enabled: boolean, poolEnabled: boolean | null, inert: true | null }
+generic OAuth: { provider, autoSwitchThreshold: number | null, enabled: boolean, poolEnabled: boolean | null, inert: boolean | null }
 ```
 
 ### `ocx account priority <provider> <account-id|main> [<-100..100|first|earlier|normal|later|last|reset>] [--json]`
@@ -278,6 +279,26 @@ security find-generic-password -w openrouter | ocx account add-key openrouter --
 
 계정의 Codex reset credits를 확인합니다. credit을 소비하는 동작은 파괴적이므로 `--consume`와 `--yes`를 둘 다 요구합니다.
 
+### `ocx account grok-reset-coupons [<account-id>] [--consume --yes [--token-id <id>] [--operation-id <uuid>]] [--json]`
+
+xAI / Grok 계정의 남은 reset coupon을 확인하거나 하나를 교환합니다.
+
+`--consume` 없이 실행하면 사용 가능한 쿠폰 토큰과 유효 기간을 반환합니다:
+
+```bash
+ocx account grok-reset-coupons
+ocx account grok-reset-coupons acc_xai_01 --json
+```
+
+reset coupon을 교환하면 billing 상태가 변경되고 쿠폰 토큰 하나를 영구적으로 소진합니다. `--consume`에는 `--yes`가 엄격하게 요구됩니다:
+
+```bash
+ocx account grok-reset-coupons --consume --yes
+ocx account grok-reset-coupons --consume --yes --token-id <token-id>
+```
+
+`--operation-id <uuid>`(유효한 UUIDv4여야 함)를 전달하면 멱등한 정산이 보장됩니다. 네트워크가 끊기거나 명령이 재시도되더라도 동일한 operation id는 쿠폰을 다시 소진하는 대신 저장된 결과를 재생합니다.
+
 ### `ocx account main <subcommand>`
 
 OpenCodex 계정 풀 라우팅을 변경하지 않고 이름이 지정된 네이티브 Codex 기본 로그인 프로필을 관리합니다.
diff --git a/docs-site/src/content/docs/ko/reference/configuration/agents.md b/docs-site/src/content/docs/ko/reference/configuration/agents.md
index da3b95fbd5..5393052849 100644
--- a/docs-site/src/content/docs/ko/reference/configuration/agents.md
+++ b/docs-site/src/content/docs/ko/reference/configuration/agents.md
@@ -72,9 +72,9 @@ opencodex는 비활성, 라우팅 불가, 비정상, 쿨다운 중, 또는 할
   "injectionModel": "gpt-5.5",
   "injectionEffort": "high",
   "syncCodexSubagentDefaults": true,
-  "subagentModelFallback": ["gpt-5.4-mini"],
+  "subagentModelFallback": ["gpt-5.6-luna"],
   "subagentModelFallbackByModel": {
-    "gpt-5.5": ["gpt-5.4-mini"]
+    "gpt-5.5": ["gpt-5.6-luna"]
   },
   "subagentModelFallbackPollMs": 60000,
   "subagentEffortCap": "high"
diff --git a/docs-site/src/content/docs/ko/reference/configuration/providers.md b/docs-site/src/content/docs/ko/reference/configuration/providers.md
index 342441eca1..c63dfc9bc7 100644
--- a/docs-site/src/content/docs/ko/reference/configuration/providers.md
+++ b/docs-site/src/content/docs/ko/reference/configuration/providers.md
@@ -36,8 +36,9 @@ GUI에서 등록이나 OAuth 로그인을 마치면 Models 페이지로 이동
 | `codexAccountPickerEnabled?` | `boolean` | map이 비어 있으면 꺼짐 | 유효한 `codexAccountNamespaces` 매핑에서 account-qualified Codex 선택기 행을 생성할지 제어합니다. `true`는 매핑된 행의 표시를 허용합니다. 비어 있지 않은 map에서 생략하면 이전 버전과의 호환성을 위해 활성화된 것으로 취급되며, map이 비어 있으면 꺼집니다. `false`는 매핑을 삭제하거나 명시적 `<selector>/<native-openai-model>` 라우팅을 비활성화하지 않은 채 생성 행을 숨기고 선택기에 bare native 행을 복원합니다. |
 | `activeCodexAccountId?` | `string` | — | 다음 요청에 수동으로 선택한 Pool 계정입니다. 선택하면 thread 결속이 해제되며, 진행 중인 요청은 캡처한 자격 증명을 유지합니다. |
 | `codexAccountPriorities?` | `Record<string,number>` | — | Codex pool의 계정별 선택 순서. 계정 ID → `-100`부터 `100`까지의 정수이며 **값이 클수록 먼저** 쓰이고, 항목이 없으면 `0`입니다. 이는 eligibility 경계가 아니라 순서 경계입니다. 선택은 이미 적격한 계정들을 quota 여유가 남은 최상위 tier로 좁히고, 그 tier 안에서 `accountPoolStrategy`가 계정을 고릅니다. tier를 건너뛰는 경우는 그 구성원 전부가 `autoSwitchThreshold` 초과, cooldown, soft-avoid, 일시 중지 또는 재인증 대기일 때뿐이며, usage를 알 수 없다고 해서 tier가 소진되지는 않습니다. 순서는 부적격 계정을 선택 가능하게 만들지 않고, 이미 계정에 묶인 thread를 다시 bind하지도 않습니다. 메인 `__main__` 계정도 동일한 조건으로 참여하므로 Codex Desktop 로그인을 마지막에 쓰도록 둘 수 있습니다. 항목이 하나도 없으면 동작은 이전과 같습니다. map이 잘못된 경우 경고를 출력하고 순서 지정을 끕니다(config 복구는 하지 않습니다). `ocx account priority`와 Codex Auth 페이지에서 관리합니다. |
-| `autoSwitchThreshold?` | `number` | `80` | 사용량 기반 선제 전환 임계값입니다. `quota`는 바인딩된 작업과 바인딩 없는 작업의 다음 요청을 모두 재평가할 수 있고, `fill-first`는 바인딩 없는 작업 배정의 소진 기준으로만 사용하며, 기본 `round-robin` 선택은 이 값을 사용하지 않습니다. 알려진 5시간, 주간, 30일 quota window 중 가장 높은 점수를 씁니다. `0`은 사용량 기반 전환만 끄며 바인딩 없는 작업 배정이나 실패 복구는 끄지 않습니다. |
-| `accountPoolStrategy?` | `"quota" \| "round-robin" \| "fill-first"` | `"quota"` | 새 작업/바인딩 없는 Codex 요청의 계정 배정 전략입니다. `(parent thread id, quota scope)`의 live affinity가 없으면 바인딩 없는 요청이며, 프록시 재시작이나 affinity 초기화 뒤에는 기존에 보이던 작업도 바인딩이 없어질 수 있습니다. `quota`는 활성 계정이 없을 때 알려진 usage가 가장 낮은 적격 계정을 선택하고, 적격 활성 계정이 `autoSwitchThreshold` 미만이면 유지합니다. 임계값 도달 뒤에는 바인딩 없는 요청이나 바인딩된 작업의 다음 요청을 usage가 더 낮은 적격 계정으로 옮길 수 있습니다. `round-robin`은 바인딩 없는 요청을 균등 분배하고, `fill-first`는 cooldown, 사용 불가 또는 drain threshold까지 활성 계정에 배정합니다. |
+| `autoSwitchThreshold?` | `number` | `80` | 사용량 기반 선제 전환 임계값입니다. `quota`는 바인딩 없는 작업의 다음 요청을 재평가할 수 있고, 기본값에서는 사용량이 이 임계값을 넘으면 바인딩된 작업도 재평가합니다. `pool.cacheAffinity`가 켜져 있으면 바인딩된 작업은 해당 계정이 소진되었거나 더 이상 처리할 수 없을 때까지 임계값을 넘어도 계정을 유지합니다. `fill-first`는 바인딩 없는 작업 배정의 소진 기준으로만 사용하며, 기본 `round-robin` 선택은 이 값을 사용하지 않습니다. 알려진 5시간, 주간, 30일 quota window 중 가장 높은 점수를 씁니다. `0`은 사용량 기반 전환만 끄며 바인딩 없는 작업 배정이나 실패 복구는 끄지 않습니다. |
+| `accountPoolStrategy?` | `"quota" \| "round-robin" \| "fill-first"` | `"quota"` | 새 작업/바인딩 없는 Codex 요청의 계정 배정 전략입니다. `(parent thread id, quota scope)`의 live affinity가 없으면 바인딩 없는 요청이며, 프록시 재시작이나 affinity 초기화 뒤에는 기존에 보이던 작업도 바인딩이 없어질 수 있습니다. `quota`는 활성 계정이 없을 때 알려진 usage가 가장 낮은 적격 계정을 선택하고, 적격 활성 계정이 `autoSwitchThreshold` 미만이면 유지합니다. 임계값 도달 뒤에는 바인딩 없는 요청을 옮길 수 있고, `pool.cacheAffinity`가 꺼져 있으면 바인딩된 작업의 다음 요청도 usage가 더 낮은 적격 계정으로 옮길 수 있습니다. `pool.cacheAffinity`가 켜져 있으면 바인딩된 작업은 계정이 소진되었거나(알려진 usage 100%) 더 이상 처리할 수 없을 때까지 유지됩니다. `round-robin`은 바인딩 없는 요청을 균등 분배하고, `fill-first`는 cooldown, 사용 불가 또는 drain threshold까지 활성 계정에 배정합니다. |
+| `pool.cacheAffinity?` | `boolean` | `false` | 바인딩된 Codex 스레드의 선택적 cache-affinity 순서입니다. `pool.kernel`과는 별개이며 기본값은 꺼짐입니다. 잘못된 값은 꺼진 것으로 읽습니다. 켜면 live 바인딩이 quota 여유보다 우선합니다. `quota`는 사용량이 `autoSwitchThreshold`를 넘었다는 이유만으로 스레드를 옮기지 않습니다. 해당 계정이 일시 중지되었거나 사용할 수 없거나 실제로 소진된 경우(알려진 usage 100%)에는 여전히 떠나므로, affinity는 고정이 아니라 재정렬입니다. |
 | `accountPoolStickyLimit?` | `number` | `1` | 한 round-robin 선택이 다음으로 넘어가기 전에 유지하는 새 작업/바인딩 없는 작업 배정 수입니다. 카운터는 업스트림 성공 뒤가 아니라 작업을 바인딩할 때 증가합니다. 범위 1–100이며 `accountPoolStrategy`가 `round-robin`일 때만 적용됩니다. |
 | `upstreamFailoverThreshold?` | `number` | `3` | 연속된 일시적 실패가 이 횟수에 도달하면 이후 새 세션은 failover됩니다. `0`으로 두면 비활성화됩니다. 일반 Responses와 네이티브 compact 전송에서 입증된 연결 전 DNS/TCP 도달 불가 실패는 provider-host 범위로 기록되며 계정 상태, 계정 쿨다운, 스레드/세션 선호도, 활성 계정 선택 또는 Pool 라우팅에 영향을 주지 않고 이 임계값에도 집계되지 않습니다. |
 | `upstreamHostCircuitThreshold?` | `number` | `0` | 네이티브 OpenAI forward Responses와 compact 전송에서 입증된 연결 전 DNS/TCP 실패에 적용하는 선택적 회로 차단 임계값입니다. `0`은 비활성화하며, `1`~`20`은 이 횟수만큼 최종 논리 요청이 실패하면 provider-origin을 30초 동안 차단합니다. 차단 중에는 계정 선택이나 업스트림 전송 전에 `Retry-After`가 포함된 `503`을 반환하고, 시간이 지나면 반개방 요청 하나만 허용합니다. 타임아웃과 HTTP 응답은 집계하지 않으며, HTTP 응답이 하나라도 오면 회로를 닫습니다. Codex Pool 라우팅에서 계정이 고정되지 않은 경우에만 적용되며, `codexAccountMode: "direct"` 및 계정 한정 선택자에서는 동작하지 않습니다. |
@@ -122,6 +123,7 @@ managed map을 활성화하면 privacy-safe selector를 만들고, 이후 계정
 | `noTopPModels?` | `string[]` | 호출자가 지정한 `top_p`를 거부하는 모델입니다. |
 | `noPenaltyModels?` | `string[]` | presence/frequency penalty를 허용하지 않는 모델입니다. |
 | `noStructuredOutputModels?` | `string[]` | `openai-chat` 엔드포인트가 `response_format`을 거부하는 정확한 모델 ID입니다. 요청 모델이 항목과 정확히 일치할 때만 필드를 생략하며, 그 외 `openai-chat` 모델에서는 structured-output 변환을 유지합니다. |
+| `noJsonSchemaModels?` | `string[]` | `openai-chat` 엔드포인트가 `json_schema` 형식은 거부하지만 `json_object`는 받는 정확한 모델 ID입니다. 이런 요청은 필드를 지우는 대신 `json_object`로 낮춰 보내므로, JSON을 요청한 클라이언트가 산문 대신 JSON을 받습니다. 한 모델이 두 목록에 모두 있으면 `noStructuredOutputModels`가 우선합니다. `opencode go`, `opencode zen`, `opencode free` 프리셋이 DeepSeek 경로에 기본으로 싣습니다. |
 | `parallelToolCalls?` | `boolean` | 병렬 도구 호출을 켜거나 끕니다. OpenAI Chat은 기본으로 켜져 있고, 비-chat 어댑터는 명시적으로 `true`일 때만 이를 노출합니다. |
 | `responsesItemIdRepair?` | `{ message?: string[]; reasoning?: string[]; repairMissingTerminalIds?: boolean; repairInvalidIds?: boolean }` | 기본값이 꺼진 downstream SSE 복구입니다. 정확한 자리표시자 id, 누락된 종료 id, 그리고(`repairInvalidIds`) 정규 `msg_`/`rs_` 접두사가 없는 message/reasoning id를 복구합니다. function-call id는 다시 쓰지 않습니다. 내장 DeepSeek은 마지막 두 가지를 기본으로 켭니다. |
 | `responsesSnapshotRepair?` | `boolean` | 기본값이 꺼진 클라이언트용 복구입니다. SSE와 JSON의 Responses 수명 주기에서 누락된 status, output, 도구 메타데이터를 채우며 raw 검사와 영속화는 변경하지 않습니다. |
@@ -161,9 +163,10 @@ Clash / Surge / Mihomo 사용자를 위한 fake-IP DNS 예외는 두 가지이
 pool 계정 추가와 quota 갱신은 대시보드의 **Codex Auth** 페이지에서 처리하세요. 설정에는 secret이
 아닌 계정 metadata만 저장하고, access/refresh token은 강화된 Codex 계정 credential store에 따로
 보관합니다. Pool 라우팅은 새 작업/바인딩 없는 작업 배정, 사용량 기반 선제 전환, 실패 복구로
-구분됩니다. 바인딩된 작업은 보통 affinity를 유지하지만 `quota`는 사용량 임계값을 넘은 뒤 다음
-요청에서 재바인딩할 수 있고, 일시 중지, cooldown, 재인증, 실패 처리도 독립적으로 라우팅을
-지우거나 바꿀 수 있습니다. 바인딩 없는 요청은 live 계정 바인딩이 없는 요청이며, 프록시 재시작이나
+구분됩니다. 바인딩된 작업은 보통 affinity를 유지합니다. 기본값에서 `quota`는 사용량 임계값을 넘은 뒤
+다음 요청에서 재바인딩할 수 있고, `pool.cacheAffinity`가 켜져 있으면 바인딩된 계정이 소진되었거나
+더 이상 처리할 수 없을 때까지 그 재바인딩을 미룹니다. 일시 중지, cooldown, 재인증, 실패 처리도
+독립적으로 라우팅을 지우거나 바꿀 수 있습니다. 바인딩 없는 요청은 live 계정 바인딩이 없는 요청이며, 프록시 재시작이나
 affinity 초기화 뒤의 기존 작업도 포함될 수 있습니다. 출력 전 **429/402**는 사용량 기반 선제
 전환이 꺼져 있어도 같은 요청에서 적격 대체 계정으로 한 번 재시도할 수 있습니다. 계정이 바뀌어도
 대화 문맥은 보존·재생되지만 계정 간 프로바이더 측 prompt cache 재사용은 보장되지 않아 다시
@@ -178,7 +181,7 @@ affinity 초기화 뒤의 기존 작업도 포함될 수 있습니다. 출력 
 `autoSwitchThreshold: 0`에서도 계속 작동하며, `0`은 사용량 기반 선제 전환만 비활성화합니다.
 
 **배정 및 선제 전환 전략:** `quota`(기본)는 활성 계정이 없을 때 최저 usage의 적격 계정을 선택하고,
-적격 활성 계정이 `autoSwitchThreshold` 미만이면 유지합니다. 임계값 도달 뒤에는 바인딩 없는 요청이나 바인딩된 작업의 다음 요청을 usage가 더 낮은 적격 계정으로 옮길 수 있습니다.
+적격 활성 계정이 `autoSwitchThreshold` 미만이면 유지합니다. 임계값 도달 뒤에는 바인딩 없는 요청을 옮길 수 있고, `pool.cacheAffinity`가 꺼져 있으면 바인딩된 작업의 다음 요청도 usage가 더 낮은 적격 계정으로 옮길 수 있습니다. 플래그가 켜져 있으면 cache affinity가 quota 여유보다 우선하며, 바인딩된 작업은 계정이 소진되었거나(알려진 usage 100%) 처리할 수 없을 때까지 유지됩니다.
 `round-robin`은 바인딩 없는 요청을 균등 분배하며 임계값은 기본 순환에 영향을 주지 않습니다.
 `accountPoolStickyLimit`(기본 `1`, 1–100)은 성공 응답이 아니라 배정/바인딩 횟수를 셉니다.
 `fill-first`는 바인딩 없는 요청을 cooldown, 재인증 또는 drain threshold까지 활성 계정에 배정하고,
@@ -220,7 +223,7 @@ Anthropic 계정 정책 위험을 이해하지 못한다면 이 기능은 꺼두
 | `failureBackoffMaxSeconds?` | `number` | `3600` | backoff 상한이자 영구 실패 지연입니다. |
 | `codexWarmupEnabled?` | `boolean` | `false` | 합성 Codex 풀 계정 검증을 선택적으로 켭니다. |
 | `codexWarmupMaxAgeSeconds?` | `number` | `691200` | 8일 후 계정을 다시 검증합니다. |
-| `codexWarmupModel?` | `string` | `gpt-5.4-mini` | 선택적 워밍업에 쓰는 네이티브 모델입니다. |
+| `codexWarmupModel?` | `string` | `gpt-5.6-luna` | 선택적 워밍업에 쓰는 네이티브 모델입니다. |
 
 ## 고정 공급자 엔드포인트
 
@@ -441,7 +444,7 @@ Vercel AI Gateway는 하나의 모델을 여러 기반 추론 공급자에 걸
       "baseUrl": "https://ollama.com/v1",
       "apiKey": "${OLLAMA_API_KEY}",
       "defaultModel": "glm-5.2",
-      "noVisionModels": ["glm-5.2", "gpt-oss", "qwen3-coder", "deepseek-v4-pro"]
+      "noVisionModels": ["glm-5.2", "gpt-oss", "qwen3-coder", "deepseek-v4-flash"]
     }
   },
   "subagentModels": ["anthropic/claude-opus-5", "ollama-cloud/glm-5.2"],
diff --git a/docs-site/src/content/docs/ko/reference/configuration/server.md b/docs-site/src/content/docs/ko/reference/configuration/server.md
index 163685a645..577379fed9 100644
--- a/docs-site/src/content/docs/ko/reference/configuration/server.md
+++ b/docs-site/src/content/docs/ko/reference/configuration/server.md
@@ -201,7 +201,7 @@ OpenAI 백엔드는 ChatGPT 로그인과 활성화된 ChatGPT `forward` provider
 | --- | --- | --- | --- |
 | `enabled?` | `boolean` | on when usable | 주 이미지 설명 스위치입니다. |
 | `backend?` | `"openai" \| "anthropic"` | auto | 명시값이 우선하며, 미설정 시 사용 가능한 저장된 Anthropic OAuth 자격 증명을 우선하고 없으면 `openai`를 사용합니다. |
-| `model?` | `string` | backend-dependent | OpenAI는 `gpt-5.4-mini`, Anthropic은 `claude-sonnet-5`입니다. |
+| `model?` | `string` | backend-dependent | OpenAI는 `gpt-5.6-luna`, Anthropic은 `claude-sonnet-5`입니다. |
 | `reasoning?` | `"low" \| "medium" \| "high" \| "xhigh" \| "max"` | `"low"` | OpenAI Responses 추론 강도입니다. Anthropic은 무시합니다. |
 | `maxDescriptionsPerTurn?` | `number` | `8` | 메인 턴당 허용되는 새 설명 캐시 미스 수입니다. `0`이면 호출이 비활성화되며, 잘못된 값은 기본값을 사용합니다. |
 | `timeoutMs?` | `number` | `45000` | 사이드카 fetch 제한 시간입니다. 정수 1–2147483647. |
diff --git a/docs-site/src/content/docs/ko/reference/management-api.md b/docs-site/src/content/docs/ko/reference/management-api.md
index 086dc5aa49..c0056af61d 100644
--- a/docs-site/src/content/docs/ko/reference/management-api.md
+++ b/docs-site/src/content/docs/ko/reference/management-api.md
@@ -64,11 +64,19 @@ Authorization: Bearer <admin-token>
 | `GET /api/grok` | Grok 관리 구성 상태와 후보 모델을 읽습니다 | 400 상태 읽기 실패 |
 | `PUT /api/grok/selection` | 제외할 Grok 모델을 영속화합니다 | 400 잘못되었거나 너무 큰 선택 |
 | `POST /api/grok/apply` | 관리형 동기화를 통해 영속화된 Grok 구성을 적용합니다 | 409 `grok_apply_busy`; 400/500 적용 실패 |
+| `GET /api/grok/reset-coupons?accountId=...` | 활성 또는 지정된 xAI 계정의 남은 Grok billing reset 토큰과 유효 기간을 읽습니다 | 400 누락된 account; 401 인증되지 않음; 502 upstream gRPC-Web 오류 |
+| `POST /api/grok/reset-coupons/consume` | 사용할 수 있는 reset coupon을 교환합니다. 본문은 `{ accountId?, tokenId?, operationId? }`. 선택적 `operationId`(UUIDv4)는 교환을 멱등하게 만듭니다 — 같은 id를 반복하면 이중 교환 없이 저장된 결과를 재생합니다. | 400 잘못된 JSON/UUID; 401 인증되지 않음; 409 `identity_mismatch`; 502 upstream 오류; 503 ledger 용량 |
 | `GET, PUT /api/claude-desktop` | Claude Desktop 라우팅/네이티브 프로필을 읽거나 저장합니다 | 400 잘못되었거나 사용할 수 없는 할당 |
 | `POST /api/claude-desktop/apply` | 저장된 프로필을 Claude Desktop의 관리형 구성에 기록합니다 | 400/500 기록 실패 |
 | `GET /api/claude-desktop/status` | 저장된 프로필과 적용된 프로필, Desktop 상태를 확인합니다 | 400 상태 읽기 실패 |
 | `GET, PUT /api/claude-code` | Claude Code gateway, auth-mode, model-map, context, agent, sidecar 설정을 읽거나 갱신합니다 | 400 잘못된 필드 또는 형태 |
 
+대시보드는 **Providers > xAI Grok > Accounts**에서 두 coupon 경로를 모두 사용합니다. 로그인한 각
+계정 행에는 남은 coupon 개수가 표시된 티켓 배지가 있으며, 이 배지는 유효 기간을 나열하고 만료가
+가장 가까운 coupon을 교환하는 대화 상자를 엽니다. 대화 상자는 클라이언트가 생성한 `operationId`를
+보내며, 재시도하는 대신 타임아웃 후 전송을 중단합니다. 저널 기록이 아직 열린 교환이 다시 실행되기
+때문입니다. `ocx account grok-reset-coupons`는 터미널 대응 명령으로 그대로 남습니다.
+
 모델 목록과 암호화된 worker-task 동작의 개념은 [Sub-agent Surface](/guides/sub-agent-surface/)를 참고하십시오.
 
 ### 클라이언트 연동 롤백 저널
@@ -171,7 +179,8 @@ Authorization: Bearer <admin-token>
 | `POST /api/oauth/logout` | 선택된 provider 자격 증명을 제거합니다 | 400 알 수 없는 provider; `oauth_mutation_busy` |
 | `GET, DELETE /api/oauth/accounts` | 마스킹된 계정을 나열하거나 계정 하나를 제거합니다 | 400 잘못된 provider/id; 404 계정 없음; `oauth_mutation_busy` |
 | `PUT /api/oauth/accounts/active` | 활성 OAuth 계정을 선택합니다 | 400 잘못된 provider/account; `oauth_mutation_busy` |
-| `GET, PUT, PATCH /api/oauth/accounts/pool` | Anthropic OAuth pool policy를 읽거나 업데이트합니다 | 400 Anthropic이 아닌 provider 또는 잘못된 policy |
+| `GET, PUT, PATCH /api/pool/settings` | 모든 pool 종류(codex, anthropic, generic)의 policy를 읽거나 업데이트합니다. 세 종류 모두 같은 키로 응답하고, 해당 종류가 실제로 적용하는 필드는 `supported`에 나옵니다 | 400 알 수 없는 provider, 해당 종류가 지원하지 않는 필드, 잘못된 값 |
+| `GET, PUT, PATCH /api/oauth/accounts/pool` | Anthropic과 일반 OAuth provider의 기존 pool policy입니다. `/api/pool/settings`로 대체되었고 기존 클라이언트를 위해 유지합니다 | 400 codex 또는 API 키 provider, 잘못된 policy |
 | `POST /api/oauth/accounts/clear-cooldown` | OAuth 계정 하나의 런타임 cooldown을 지웁니다 | 400 잘못된 provider/account |
 | `PUT /api/oauth/accounts/alias` | OAuth 계정 alias를 설정하거나 지웁니다 | 400 잘못된 provider/account/alias |
 | `GET, POST, DELETE /api/providers/keys` | 마스킹된 provider key를 나열, 추가/활성화, 또는 제거합니다 | 400 잘못된 입력; 404 provider/key 없음 |
diff --git a/docs-site/src/content/docs/ko/reference/proxy-formats.md b/docs-site/src/content/docs/ko/reference/proxy-formats.md
index fbabaf0cb3..a537d77a73 100644
--- a/docs-site/src/content/docs/ko/reference/proxy-formats.md
+++ b/docs-site/src/content/docs/ko/reference/proxy-formats.md
@@ -314,6 +314,8 @@ Responses 계열과 Chat 요청은 전용 헤더 또는 Bearer 필드의 프록
 
 키가 없고 OAuth를 쓰지 않는 Cursor 경로는 별도의 호출자 bearer를 사용할 수 있지만, 프록시 secret이나 자동으로 보충한 ChatGPT main 인증은 사용할 수 없습니다. Combo/policy 선택과 실제 shadow/thread-spawn 경로 변경은 호출자의 원본 자격 증명을 새 대상으로 넘기지 않습니다. 정규 OpenAI 라우팅은 JWT에 ChatGPT 계정 claim이 포함되어 있고 명시적 계정 헤더가 있으면 그 claim과 일치하는 경우에만, 내부 경로 변경 후 프록시 키가 아닌 호출자의 단일 bearer를 복원할 수 있습니다. 선택적 OpenAI sidecar에 호출자 인증을 전달하려면 단일 JWT와 이에 일치하는 명시적 `chatgpt-account-id`가 필요합니다. Opaque bearer는 명시적 계정 헤더가 있어도 경로 변경을 거쳐 복원되지 않습니다. 그 외의 최종 대상에는 자체 설정·OAuth·저장 자격 증명이 필요하며, 없으면 로컬에서 실패합니다. thread-spawn 표지만 있고 경로가 바뀌지 않으면 자격 증명을 제거하지 않습니다.
 
+설정된 키가 없고 OAuth를 쓰지 않는 Cursor Chat 요청의 선택적 저장 main 인증 보강은 실제 OpenAI 보조 호출이 계획되고 canonical Direct 대상이 있을 때까지 미룹니다. 무관한 Cursor 요청은 이 과정에서 native main을 점유하지 않아 프로필 전환을 지연시키지 않습니다. 보조 호출 인증은 시작·전환 소유권 차단을 따르며 Cursor bearer와 분리됩니다. Pool 및 계정을 지정한 보조 호출은 기존 계정 선택을 유지합니다.
+
 Claude replay는 해당 turn이 소유권을 확보한 main 인증만 메모리 snapshot으로 유지하며, 최종 대상이 정규 ChatGPT 경로일 때만 복원합니다.
 
 :::caution
diff --git a/docs-site/src/content/docs/reference/adapters.md b/docs-site/src/content/docs/reference/adapters.md
index 596fc2255f..af7e3055c0 100644
--- a/docs-site/src/content/docs/reference/adapters.md
+++ b/docs-site/src/content/docs/reference/adapters.md
@@ -422,6 +422,65 @@ bare `exec_command` and `shell_command` names are reserved for non-freeform shel
 bridges. Namespace a custom freeform tool that uses either name. These schema
 declarations do not grant approval or change execution policy.
 
+## `devin`
+
+**Targets:** Cognition's `exa.api_server_pb.ApiServerService/GetChatMessage` over HTTPS Connect
+streaming at `server.codeium.com`.
+**Auth:** Devin/Cognition API key from `provider.apiKey` or the forwarded authorization header.
+Login opens Auth0 browser sign-in, then exchanges the Firebase ID token via
+`SeatManagementService.RegisterUser` for a long-lived API key.
+
+- Uses `runTurn` rather than the ordinary fetch/parse path. Requests and server events are encoded
+  with manual protobuf framing in `devin/cloud-direct/wire.ts`; the ordinary `buildRequest` /
+  `parseStream` path is disabled.
+- Live model discovery via `GetCascadeModelConfigs`; the static seed is filtered against the
+  account's live roster so models not on the plan drop out instead of failing at request time.
+- Tool definitions are encoded in the request and tool-call events are decoded from the response
+  stream. Cognition enforces a per-tool-description length limit (6,998 chars) and an exact-phrase
+  blocklist; the adapter sanitizes known triggers and truncates over-long descriptions before
+  encoding.
+- Devin/Cognition API keys do not refresh. Run `ocx login devin` again when the key expires or is
+  revoked.
+- The chat request is calibrated, not guessed. Three things gate it together: the credential is the
+  session token doubled and dash-joined in an `Authorization: Basic` header while the protobuf body
+  keeps one copy, the request envelope goes up uncompressed, and `Metadata` #31 carries a
+  732-character device fingerprint whose length — not value — the service checks. Inside
+  `CompletionConfiguration`, #2 is the output cap and #3 is the context window; swapping those two
+  makes every turn fail with an opaque `invalid_argument`. A temperature of exactly 0 is refused, so
+  it is clamped to the smallest accepted value.
+- Experimental unofficial bridge; not shown in the dashboard preset by default. See the
+  [provider guide](/guides/providers/) for login instructions.
+
+## `devin-cli`
+
+**Targets:** Cognition's `exa.api_server_pb.ApiServerService/GetChatMessage`, the same Connect
+streaming endpoint the `devin` provider uses.
+**Auth:** imported from the installed Devin CLI. After `devin auth login` the CLI writes a
+`devin-session-token` to its own `credentials.toml`, which is the same credential
+`SeatManagementService.RegisterUser` mints for `ocx login devin`; signing in from the dashboard
+adopts it, with no browser step and no key to paste. opencodex reads only that token and the
+api-server URL beside it, and never the file's other fields.
+
+- Uses `runTurn` on the shared cloud-direct client, so it inherits that adapter's live catalog,
+  per-account context windows and tool-description handling.
+- For the CLI's own local agent loop over ACP stdio instead, configure a **custom-named** provider
+  row with `"adapter": "devin-cli"` — for example `"devin-acp"`. A row named `devin-cli` cannot
+  select it, because the router pins the adapter from the registry for any registry id.
+- One turn is one ACP session: `initialize`, `session/new`, `session/prompt`, with `session/update`
+  notifications streaming in between and a unary reply carrying the stop reason and usage. The
+  conversation is flattened into the single prompt string a session takes, with role labels fenced
+  so a message body cannot forge one.
+- The CLI's own tool calls stay internal. Devin executes them inside its session, so forwarding
+  them as client tools would either fail the turn — the bridge rejects a tool Codex never declared —
+  or ask Codex to run something the agent already ran.
+- **Permission requests are refused by default.** This provider runs an agent in the operator's own
+  tree, so `session/request_permission` is answered with `cancelled` unless
+  `OPENCODEX_DEVIN_CLI_ALLOW_TOOLS=1` is set. The child also gets a scoped environment rather than
+  the proxy's, and `OPENCODEX_DEVIN_CLI_CWD` chooses where it runs.
+- Binary discovery prefers `OPENCODEX_DEVIN_CLI_BIN`, then the paths the official installer and the
+  Homebrew cask use, then `PATH`. Install with `curl -fsSL https://cli.devin.ai/install.sh | bash`
+  or `brew install --cask devin-cli`.
+
 ## `azure-openai` (alias: `azure`)
 
 **Targets:** **Azure OpenAI**. Wraps `openai-responses` (so also `passthrough: true`).
diff --git a/docs-site/src/content/docs/reference/cli/agents.md b/docs-site/src/content/docs/reference/cli/agents.md
index ab96881d11..32399c59df 100644
--- a/docs-site/src/content/docs/reference/cli/agents.md
+++ b/docs-site/src/content/docs/reference/cli/agents.md
@@ -235,7 +235,7 @@ Manage and apply the Grok Build model fence.
 
 ## Client config export
 
-### `ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|prime|aside|raycast>`
+### `ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|prime|aside|raycast|omo>`
 
 Print a client config wired to the running proxy. The command serializes the
 `opencodex` provider block — base URL, model list, and the client's credential
@@ -246,7 +246,7 @@ models Codex can currently see.
 
 | Flag | Action |
 | --- | --- |
-| `--client <opencode\|pi\|omp\|hermes\|openclaw\|kimi\|gajae\|dsh\|mcode\|zcode\|prime\|aside\|raycast>` | Required. Selects the client config dialect. |
+| `--client <opencode\|pi\|omp\|hermes\|openclaw\|kimi\|gajae\|dsh\|mcode\|zcode\|prime\|aside\|raycast\|omo>` | Required. Selects the client config dialect. |
 | `--json` | Print the generated document as JSON on stdout for scripts. This is JSON even when the selected client's native format is YAML, TOML, or JSON5. |
 | `--out <path>` | Write the client's native config format to `<path>`. Refuses to replace an existing file. |
 | `--force` | Allow `--out` to replace an existing file. |
@@ -277,6 +277,7 @@ client applies its own defaults for those).
 | `prime` | `~/.prime/agent/models.json` (`PRIME_AGENT_CODING_AGENT_DIR` wins when set; a relative value is refused) | `prime-models.json` | none — loopback placeholder |
 | `aside` | `~/.aside/u/<account>/models.json` for the account Aside's own `accounts.json` names as current; an unreadable manifest is refused rather than defaulting to an account | `aside-models.json` | none — loopback placeholder |
 | `raycast` | `~/.config/raycast/ai/providers.yaml` on macOS and Windows alike (Raycast does not honor `XDG_CONFIG_HOME`) | `raycast-providers.yaml` | none — loopback only, no `api_keys` entry is written |
+| `omo` | `~/.omo/agent/models.json` (`OMO_CODING_AGENT_DIR`, then `SENPI_CODING_AGENT_DIR`, then `PI_CODING_AGENT_DIR` win in that order when set; a relative value is refused) | `omo-models.json` | none — loopback placeholder |
 
 The managed DSH export requires DSH 0.1.0-rc.6 or newer and owns only
 `llm-pi-ai.providers.opencodex`. DSH hot reloads that provider; the user's default model and
@@ -328,8 +329,8 @@ the proxy binds beyond loopback; see
 [Remote access](/reference/configuration/#remote-access) for how admission keys are issued. Keys for
 the upstream providers themselves are a separate thing entirely, configured per
 [Providers](/guides/providers/).
-Gajae is the exception: `OPENCODEX_GAJAE_API_KEY` fills its provider credential from the
-environment, but its schema cannot send the remote admission header, so the generated Gajae
+gjc is the exception: `OPENCODEX_GAJAE_API_KEY` fills its provider credential from the
+environment, but its schema cannot send the remote admission header, so the generated gjc
 integration remains loopback-only.
 
 The same payload is served by `GET /api/client-config` and rendered on the dashboard's API tab, so
diff --git a/docs-site/src/content/docs/reference/cli/providers-accounts.md b/docs-site/src/content/docs/reference/cli/providers-accounts.md
index bc5f56e02d..f7e94a1833 100644
--- a/docs-site/src/content/docs/reference/cli/providers-accounts.md
+++ b/docs-site/src/content/docs/reference/cli/providers-accounts.md
@@ -96,8 +96,10 @@ currently accepted OAuth and API-key provider ids when the name is missing or un
 
 Use the same command to **reauthenticate** after `ocx status` / `ocx doctor` reports
 reauthentication required or a terminal refresh failure (or use Reauthenticate in the dashboard).
-Codex pool accounts are not a public `ocx login` provider — reauthenticate via the dashboard Codex
-account pool (Reauthenticate) or the headless `ocx account reauth` flow instead.
+Codex pool accounts are not one of those OAuth or API-key providers, but `ocx login codex` reaches
+them anyway: it routes to the account-pool login, so `ocx login codex --reauth` is the same thing as
+`ocx account reauth codex`. The dashboard Codex account pool (Reauthenticate) does it too. That route
+runs inside the proxy, so it needs a running one.
 
 ```bash
 ocx login xai
@@ -205,7 +207,7 @@ List and switch provider accounts and API-key pools through the running proxy. T
 surface is:
 
 ```text
-Usage: ocx account <list|current|use|refresh|auto-switch|priority|login|reauth|code|cancel|remove|add-key|reset-credits> ...
+Usage: ocx account <list|current|use|refresh|auto-switch|priority|login|reauth|code|cancel|remove|add-key|reset-credits|grok-reset-coupons> ...
 
 list [provider]     Codex account pool, OAuth accounts and API keys (identifiers shown masked as the API returns them).
 current <provider>  Show the active account or key.
@@ -217,6 +219,7 @@ remove <provider> <id> --yes  Remove a stored account or key after an existence
 add-key <provider> [--label <label>]  Add a key read only from piped stdin.
 login/reauth/code/cancel  Run browser or manual-code auth from a headless shell.
 reset-credits <id|main> [--consume --yes]  Inspect or consume Codex reset credits.
+grok-reset-coupons [<id>] [--consume --yes] [--token-id <token-id>] [--operation-id <uuid>]  Inspect or redeem Grok reset coupons.
 Switching the active account takes effect immediately; running threads move on their next request, and in-flight requests keep the account they captured.
 A selection-order change applies from the next unbound request and never moves a bound thread.
 ```
@@ -346,11 +349,11 @@ instead (exit 0), matching the dashboard's quota bars.
 
 ### `ocx account auto-switch <provider> <on|off|status|threshold <0-100>> [--json]`
 
-Controls the `openai` Codex pool threshold, or stores a threshold for a generic OAuth pool. `on` stores 80%, `off` stores 0%, and `threshold <n>` accepts 0–100. Generic pool thresholds are currently inert: saving one does not enable threshold-based switching, change the provider enablement override, or disable reactive 429 rotation. `status` and mutation output for generic pools use the confirmed server response. For generic pools, `poolEnabled` is the stored provider override (`null` means unspecified), not inherited effective state; `inert: true` means the threshold is not applied, and unknown capability never reports `enabled: true`. API-key providers, Anthropic and invalid values are rejected.
+Controls the `openai` Codex pool threshold, or stores a threshold for a generic OAuth pool. `on` stores 80%, `off` stores 0%, and `threshold <n>` accepts 0–100. A generic pool threshold steers selection only while `pool.kernel` is on with `strategy: "fill-first"`; with the flag off, saving one does not enable threshold-based switching. It never changes the provider enablement override or disables reactive 429 rotation. `status` and mutation output for generic pools use the confirmed server response. For generic pools, `poolEnabled` is the stored provider override (`null` means unspecified), not inherited effective state; `inert: true` means the threshold is stored but not applied, `inert: false` means the pool is applying it, and an absent `inert` is an unknown capability, which never reports `enabled: true`. API-key providers, Anthropic and invalid values are rejected.
 
 ```text
 openai: { provider, autoSwitchThreshold: number, enabled: boolean }
-generic OAuth: { provider, autoSwitchThreshold: number | null, enabled: boolean, poolEnabled: boolean | null, inert: true | null }
+generic OAuth: { provider, autoSwitchThreshold: number | null, enabled: boolean, poolEnabled: boolean | null, inert: boolean | null }
 ```
 
 ### `ocx account priority <provider> <account-id|main> [<-100..100|first|earlier|normal|later|last|reset>] [--json]`
@@ -454,6 +457,26 @@ again instead of repeating `--consume`. Consume success does not guarantee routa
 see the [management API recovery contract](/reference/management-api/#codex-authentication-delegation)
 for reset/replay, freshness and scope limits.
 
+### `ocx account grok-reset-coupons [<account-id>] [--consume --yes [--token-id <id>] [--operation-id <uuid>]] [--json]`
+
+Inspects remaining reset coupons or redeems one for an xAI / Grok account.
+
+When invoked without `--consume`, returns the available coupon tokens and validity windows:
+
+```bash
+ocx account grok-reset-coupons
+ocx account grok-reset-coupons acc_xai_01 --json
+```
+
+Redeeming a reset coupon mutates billing state and permanently exhausts one coupon token. `--consume` strictly requires `--yes`:
+
+```bash
+ocx account grok-reset-coupons --consume --yes
+ocx account grok-reset-coupons --consume --yes --token-id <token-id>
+```
+
+Pass `--operation-id <uuid>` (must be a valid UUIDv4) to guarantee idempotent settlement. If the network drops or the command is retried, identical operation IDs replay the durably recorded outcome instead of consuming a second coupon.
+
 ### `ocx account main <subcommand>`
 
 Manage named native Codex main-login profiles without changing OpenCodex account-pool routing:
diff --git a/docs-site/src/content/docs/reference/configuration.md b/docs-site/src/content/docs/reference/configuration.md
index b1136ee86e..8ed7b97e69 100644
--- a/docs-site/src/content/docs/reference/configuration.md
+++ b/docs-site/src/content/docs/reference/configuration.md
@@ -61,7 +61,7 @@ a known configured model id. Cursor may require a model-list refresh or restart
 
 `fastRows` is an optional boolean and defaults to `true`. The raw OpenAI-style
 `/v1/models` list, Claude Code discovery, and client config exports (including pi, OpenCode,
-OMP, Hermes, OpenClaw, Kimi, Gajae, DSH, MCode, ZCode, Prime, and Aside) add a `<base-id>--fast` selector for every model whose
+OMP, Hermes, OpenClaw, Kimi, gjc, DSH, MCode, ZCode, Prime, Aside, Raycast, and omo) add a `<base-id>--fast` selector for every model whose
 resolved Fast policy is eligible. Selecting one routes the base model and requests the `priority`
 service tier — the same Fast the Codex app exposes through its picker toggle. The base row stays
 listed, so the row is an addition rather than a replacement.
diff --git a/docs-site/src/content/docs/reference/configuration/agents.md b/docs-site/src/content/docs/reference/configuration/agents.md
index 8fd5db5080..24dd9dec16 100644
--- a/docs-site/src/content/docs/reference/configuration/agents.md
+++ b/docs-site/src/content/docs/reference/configuration/agents.md
@@ -153,9 +153,9 @@ on a mid-thread model switch.
   "injectionModel": "gpt-5.5",
   "injectionEffort": "high",
   "syncCodexSubagentDefaults": true,
-  "subagentModelFallback": ["gpt-5.4-mini"],
+  "subagentModelFallback": ["gpt-5.6-luna"],
   "subagentModelFallbackByModel": {
-    "gpt-5.5": ["gpt-5.4-mini"]
+    "gpt-5.5": ["gpt-5.6-luna"]
   },
   "subagentModelFallbackPollMs": 60000,
   "subagentEffortCap": "high"
diff --git a/docs-site/src/content/docs/reference/configuration/providers.md b/docs-site/src/content/docs/reference/configuration/providers.md
index e2769ab807..23b7e5e92d 100644
--- a/docs-site/src/content/docs/reference/configuration/providers.md
+++ b/docs-site/src/content/docs/reference/configuration/providers.md
@@ -21,6 +21,18 @@ ocx models provider openrouter on
 
 After GUI registration or OAuth login, the confirmation dialog lets you open the Models page. CLI registration and login print model-management commands; JSON includes structured next steps. `--no-wait` reports pending login, not completion. Start the proxy with `ocx start` before using live model commands.
 
+## Z.ai Coding Plan quota endpoints
+
+The Z.ai quota probe recognizes the international coding Chat base
+`https://api.z.ai/api/coding/paas/v4`, the documented
+[Claude Code Anthropic base](https://docs.z.ai/devpack/tool/claude)
+`https://api.z.ai/api/anthropic`, and the documented
+[Codex Responses base](https://docs.z.ai/devpack/tool/codex)
+`https://api.z.ai/api/v1`. All three read quota from the international monitor with
+Bearer authentication; this does not change the inference URL or imply different
+quota consumption between adapters. Existing BigModel CN monitor selection remains
+separate. Full request URLs such as `/api/v1/responses` are not provider base URLs.
+
 ## Provider-related top-level fields
 
 | Field | Type | Default | Meaning |
@@ -39,8 +51,9 @@ After GUI registration or OAuth login, the confirmation dialog lets you open the
 | `activeCodexAccountId?` | `string` | — | Manually selected Pool account for the next request. Selection clears thread affinity; in-flight requests keep captured credentials. |
 | `codexAccountPriorities?` | `Record<string, number>` | — | Per-account selection order for the Codex pool: account id → integer from `-100` to `100`, **higher is used earlier**, absent means `0`. This is an ordering boundary, not an eligibility one: selection narrows the already-eligible accounts to the highest tier that still has quota headroom, and `accountPoolStrategy` then picks within that tier. A tier is skipped only when every member is over `autoSwitchThreshold`, cooling down, soft-avoided, paused, or needs reauthentication — unknown quota never drains a tier. Ordering never makes an ineligible account selectable and never re-binds a thread that already has an account. The main `__main__` account participates on equal terms, which is how the Codex Desktop login can be set to drain last. With no entries the pool behaves exactly as before. A malformed map is ignored with a console warning (ordering off, no config repair). Managed by `ocx account priority` and the Codex Auth page. |
 | `activeCodexAccountPinned?` | `string` | — | Account id the operator last selected by hand. While set, a higher `codexAccountPriorities` tier cannot preempt it until the pin is released by drain, exclusion, deletion, or an explicit failover/promotion away. Ordinary round-robin movement inside the capped tier does not release it. Writing any `codexAccountPriorities` entry also releases the pin, so a pin made before an order existed cannot outrank one set afterward. `GET /api/codex-auth/active` reports both whether the effective account is pinned (`pinned`) and the account carrying the ceiling (`pinnedAccountId`). |
-| `autoSwitchThreshold?` | `number` | `80` | Usage threshold for proactive switching. `quota` can re-evaluate both bound and unbound tasks on their next request; `fill-first` uses it only as the drain point for unbound assignment; normal `round-robin` selection does not use it. The score uses the hottest known 5h, weekly, or 30d quota window. `0` disables usage-based proactive switching only, not unbound assignment or failure recovery. |
-| `accountPoolStrategy?` | `"quota" \| "round-robin" \| "fill-first"` | `"quota"` | Assignment strategy for new/unbound Codex requests. A request is unbound when it has no live (parent thread id, quota scope) affinity; a visible existing task can become unbound after proxy restart or affinity reset. `quota` picks the lowest-usage eligible account when no active account exists, keeps an eligible active account below `autoSwitchThreshold`, and after the threshold may move an unbound request or proactively rebind a bound task to a lower-usage eligible account. `round-robin` distributes unbound requests evenly; `fill-first` keeps assigning unbound requests to the active account until cooldown, unavailability, or the configured drain threshold. |
+| `autoSwitchThreshold?` | `number` | `80` | Usage threshold for proactive switching. `quota` can re-evaluate unbound tasks on their next request, and by default also re-evaluates bound tasks once usage crosses this threshold. With `pool.cacheAffinity` on, a bound task keeps its account past the threshold until that account is exhausted or otherwise cannot serve. `fill-first` uses it only as the drain point for unbound assignment; normal `round-robin` selection does not use it. The score uses the hottest known 5h, weekly, or 30d quota window. `0` disables usage-based proactive switching only, not unbound assignment or failure recovery. |
+| `accountPoolStrategy?` | `"quota" \| "round-robin" \| "fill-first"` | `"quota"` | Assignment strategy for new/unbound Codex requests. A request is unbound when it has no live (parent thread id, quota scope) affinity; a visible existing task can become unbound after proxy restart or affinity reset. `quota` picks the lowest-usage eligible account when no active account exists, keeps an eligible active account below `autoSwitchThreshold`, and after the threshold may move an unbound request or — unless `pool.cacheAffinity` is on — proactively rebind a bound task to a lower-usage eligible account. With `pool.cacheAffinity` on, a bound task stays until its account is exhausted (known usage at 100%) or otherwise cannot serve. `round-robin` distributes unbound requests evenly; `fill-first` keeps assigning unbound requests to the active account until cooldown, unavailability, or the configured drain threshold. |
+| `pool.cacheAffinity?` | `boolean` | `false` | Opt-in cache-affinity ordering for bound Codex threads, independent of `pool.kernel`. Off by default; a malformed value reads as off. With it on, a live binding outranks quota headroom: `quota` does not move the thread merely because usage crossed `autoSwitchThreshold`. The thread still leaves if that account cannot serve — paused, unusable, or genuinely exhausted (known usage at 100%) — so affinity is a reordering, not a pin. |
 | `accountPoolStickyLimit?` | `number` | `1` | New/unbound task assignments retained on one round-robin selection before advancing; the counter advances when a task is bound, not after an upstream success. Range 1–100. |
 | `upstreamFailoverThreshold?` | `number` | `3` | Consecutive transient failures before future new sessions fail over. Set `0` to disable. For regular Responses and native compact sends, proven pre-connection DNS/TCP reachability failures are tracked at the provider-host level: they never affect account health, account cooldowns, thread/session affinity, active-account selection, or Pool routing, and never count toward this threshold. |
 | `upstreamHostCircuitThreshold?` | `number` | `0` | Opt-in circuit threshold for proven pre-connection DNS/TCP failures on native OpenAI forward Responses and compact sends. `0` disables it; `1`–`20` opens a 30-second provider-origin cooldown after that many terminal logical requests. While open, requests receive `503` with `Retry-After` before account selection or upstream send; after cooldown, one half-open request is admitted. Timeouts and HTTP responses never count, and any HTTP response closes the circuit. Applies only to Codex Pool routing with no pinned account; it is inert for `codexAccountMode: "direct"` and account-qualified selectors. |
@@ -130,6 +143,7 @@ Providers can expose a built-in shorthand, such as `agy` for `google-antigravity
 | `requestPacing?` | `{ enabled, requestsPerMinute?, minIntervalMs?, models? }` | Optional client-side outbound request-start pacing, separate from upstream usage, billing, and rate-limit indicators. RPM is converted to an even interval; `minIntervalMs` may impose a longer interval. Provider limits apply across all models, while `models` entries use exact upstream model IDs (for example `nvidia/llama-3.1-nemotron-ultra-253b-v1`) and can only add delay. Queue waits do not consume the upstream response-header timeout. HTTP, Responses WebSocket, and explicit adapter `fetchResponse`/`runTurn` dispatches are covered. |
 | `upstreamHttpVersion?` | `"auto" \| "http1.1" \| "h1" \| "http2" \| "h2"` | Pin the HTTP version used for upstream requests to this provider. Defaults to `auto`, which lets Bun negotiate. An explicit pin requires an HTTPS target and fails locally when it cannot be honored. Set `http1.1` when a provider's HTTP/2 SSE stream stalls instead of delivering events — the symptom is a long-running streaming request that produces nothing and eventually times out. For Cursor, `http1.1`/`h1` selects its `RunSSE` + `BidiAppend` compatibility transport for inference and also pins live model discovery. Management `POST`/`PATCH` accept `null` to clear it back to `auto`. |
 | `responsesPath?` | `string` | Relative resource path for key-auth `openai-responses` requests. It must start with `/` and contain no scheme, query, or fragment. |
+| `chatCompletionsPath?` | `string` | Relative resource path for `openai-chat` requests, the mirror of `responsesPath` and subject to the same shape rules. Needed when one upstream serves Chat Completions and Responses under different prefixes: a per-model wire override changes the adapter and leaves `baseUrl` alone, so without this an opted-in Chat request would be sent to the Responses base. Z.AI is the shipped example. |
 | `allowEncryptedV2AgentTasks?` | `boolean` | Disabled by default. Trust a direct key-auth `openai-responses` provider to consume or relay opaque encrypted V2 sub-agent tasks unchanged. Eligible routes skip `agentTaskRecovery`; all other routes keep the existing recovery or fail-closed behavior. OpenCodex does not decrypt, translate, or recover tasks sent through this opt-in. |
 | `upstreamWebsocket?` | `boolean` | Opt-in upstream Responses WebSocket transport for `openai-responses` requests (default false). When the upstream supports the Responses WebSocket protocol, streaming POST requests to the configured Responses path (default `/v1/responses`) are dialed as WSS over an HTTPS base URL and re-encoded to SSE for the usual pipeline. Forward providers use `{baseUrl}/responses`; key-auth providers use `responsesPath`, or the legacy `/v1/responses` fallback. This mirrors the canonical ChatGPT backend optimization for OpenAI-compatible gateways (for example sub2api) whose WebSocket ingress is measurably faster than its SSE queue. Plain HTTP remains on SSE; non-Responses paths and `openai-chat` requests stay on HTTP. |
 | `supportsServiceTier?` | `boolean` | Tri-state canonical Fast capability fallback. `true` publishes Fast in the catalog, satisfies service-tier routing requirements, contributes a supported fingerprint, and lets fast mode inject the provider's canonical wire value on a compatible final adapter. `false` strips the field and never injects, and exact model declarations cannot reopen it. Absent leaves the provider unclassified: fast mode does not inject or normalize a canonical caller value, and caller values obey the final wire's forwarding permission (`chatServiceTier` on Chat; passthrough on Responses). The registry classifies canonical OpenAI (`true`), DeepSeek, and Volcengine Ark (`false`); set it explicitly only for custom gateways that genuinely support tiers. |
@@ -141,6 +155,7 @@ Providers can expose a built-in shorthand, such as `agy` for `google-antigravity
 | `apiKey?` | `string` | API key, an `${ENV_VAR}` / `$ENV_VAR` reference, or a `keychain:<provider>` reference written by `ocx provider keychain <name> store`. References resolve at request time. See [Storing keys in the OS keychain](#storing-keys-in-the-os-keychain). |
 | `apiKeyTransport?` | `"x-api-key" \| "bearer"` | Anthropic key header style. Defaults to native `x-api-key`; valid only for key-auth `anthropic` providers. |
 | `apiKeyPool?` | `ApiKeyPoolEntry[]` | Multi-key pool. `apiKey` mirrors the active entry; each item has `id`, `key`, optional `label`, and optional numeric `addedAt`. |
+| `apiKeyPoolStrategy?` | `"round-robin" \| "fill-first" \| "quota"` | How a warm key is chosen **before** the first attempt when the committed key is already cooling. Omitted keeps rotation reactive-only: the pool moves after a 429 or 401 and not before. `round-robin` takes the next key in the pool, `fill-first` keeps the first eligible one, and `quota` prefers the key with the most remaining headroom, falling back to `fill-first` order for a provider whose per-key quota is unknown. A healthy committed key is never overridden, so a manual key selection stands. |
 | `defaultModel?` | `string` | Model used when this provider is selected without an explicit model. |
 | `models?` | `string[]` | Seed/fallback model list. With `liveModels: false`, a nonempty `models` list is followed by `retainModels`; an empty or omitted `models` list instead seeds `defaultModel` (if configured), then `retainModels`, removing duplicate ids in first-seen order. |
 | `liveModels?` | `boolean` | Fetch the live catalog on start/sync (default `true`). Custom providers use `${baseUrl}/models`; built-ins may use a registry URL and filter. |
@@ -180,6 +195,7 @@ Providers can expose a built-in shorthand, such as `agy` for `google-antigravity
 | `noTopPModels?` | `string[]` | Models that reject caller-specified `top_p`. |
 | `noPenaltyModels?` | `string[]` | Models that reject presence/frequency penalties. |
 | `noStructuredOutputModels?` | `string[]` | Exact model IDs whose `openai-chat` endpoint rejects `response_format`. Only an exact requested-model match omits the field; structured-output translation stays enabled for every other `openai-chat` model. |
+| `noJsonSchemaModels?` | `string[]` | Exact model IDs whose `openai-chat` endpoint rejects a `json_schema` `response_format` but still accepts `json_object`. Such a request is downgraded to `json_object` instead of being dropped, so a caller asking for JSON still gets JSON. `noStructuredOutputModels` wins when a model is on both lists. The `opencode go`, `opencode zen`, and `opencode free` presets ship this for their DeepSeek routes. |
 | `omitReasoningEffortWithToolsModels?` | `string[]` | Exact `openai-chat` model IDs that accept a reasoning-effort field on an ordinary turn but reject it once function tools are present. The model keeps its advertised effort ladder; OpenCodex omits the wire field for tool-bearing requests only and the upstream default applies. Narrower than `noReasoningModels`, which strips reasoning from every request and costs the model its picker entirely. |
 | `parallelToolCalls?` | `boolean` | Toggle parallel tool calls. OpenAI Chat defaults on; non-chat adapters advertise only on explicit `true`. |
 | `terminalContinuationGuard?` | `boolean` | Opt in an `openai-chat` provider to one bounded internal re-ask when an actionable turn announces work, then cleanly stops without a tool call. Defaults to `false`; explicit `false` behaves like omission. Combo attempts and routed compaction turns are excluded, and non-`openai-chat` adapters ignore this option. |
@@ -462,9 +478,10 @@ validation never applies the IPv6 accommodation.
 Use **Codex Auth** in the dashboard to add pool accounts and refresh quotas. `config.json` stores
 non-secret metadata; access and refresh tokens use the hardened credential store. Pool routing
 separates new/unbound assignment, usage-based proactive switching, and failure recovery. A bound task
-normally keeps affinity, but `quota` may rebind it on its next request after the usage threshold is
-crossed, while pause, cooldown, reauthentication, and failure handling can clear or move routing
-independently. An unbound request has no live account binding; this can include an existing visible
+normally keeps affinity. By default `quota` may rebind it on its next request after the usage
+threshold is crossed; with `pool.cacheAffinity` on, that rebind waits until the bound account is
+exhausted or otherwise cannot serve. Pause, cooldown, reauthentication, and failure handling can
+clear or move routing independently. An unbound request has no live account binding; this can include an existing visible
 task after proxy restart or affinity reset. A pre-stream 429 or 402, or a 5xx response whose bounded
 body explicitly reports quota exhaustion, retries once on an eligible alternate account in the same
 request, even when usage-based proactive switching is off. The ordinary transient-5xx policy runs
@@ -485,7 +502,7 @@ and pauses only accounts freshly confirmed at 100%; unknown or failed refreshes
 
 | Strategy | Behaviour |
 | --- | --- |
-| `quota` (default) | If no active account exists, choose the lowest-usage eligible account across 5-hour, weekly, and 30-day windows. Otherwise retain an eligible active account below `autoSwitchThreshold`; after it crosses the threshold, an unbound request or a bound task's next request can move to a lower-usage eligible account. `0` disables this usage-driven re-evaluation, not failure recovery. |
+| `quota` (default) | If no active account exists, choose the lowest-usage eligible account across 5-hour, weekly, and 30-day windows. Otherwise retain an eligible active account below `autoSwitchThreshold`; after it crosses the threshold, an unbound request can move to a lower-usage eligible account, and a bound task's next request can too unless `pool.cacheAffinity` is on. With that flag on, cache affinity outranks quota headroom and the bound task stays until the account is exhausted (known usage at 100%) or cannot serve (paused, unusable). `0` disables this usage-driven re-evaluation, not failure recovery. |
 | `round-robin` | Evenly assign unbound requests across eligible accounts. `autoSwitchThreshold` does not change normal round-robin selection. `accountPoolStickyLimit` (1–100) counts assignments on one pick, not successful upstream responses. |
 | `fill-first` | Assign unbound requests to the active account until cooldown, reauthentication, or the configured drain threshold; unknown usage does not force a switch. Healthy bound tasks keep affinity. |
 
@@ -552,8 +569,9 @@ second account.
 | --- | --- | --- | --- |
 | `oauthAccountFailover.enabled?` | `boolean` | presence-driven | Global override for the **pre-dispatch account preference** only. `false` stops a healthy request being steered toward the account with more known headroom. It does **not** disable 429 rotation. |
 | `providers.<name>.oauthAccountFailover.enabled?` | `boolean` | inherits | Per-provider override for the same preference; beats the global setting in either direction. `false` declines the preference for this provider even when the global setting is `true`, and `true` opts this provider in even when the global setting is `false`. Reactive 429 rotation is unaffected either way. |
-| `providers.<name>.oauthAccountFailover.strategy?` | `"quota" \| "round-robin" \| "fill-first"` | — | Declared pool strategy for a generic OAuth provider (#695). Persisted through `ocx account strategy <provider> <name>` or `PUT /api/oauth/accounts/pool`; the generic selector does not act on it yet, so omitted and set behave the same today. |
-| `providers.<name>.oauthAccountFailover.autoSwitchThreshold?` | `number` | — | Declared 0–100 usage percent for a proactive switch on a generic OAuth provider (#695). Set with `ocx account auto-switch <provider> threshold <n>`; inert until the selector consumes it. |
+| `providers.<name>.oauthAccountFailover.strategy?` | `"quota" \| "round-robin" \| "fill-first"` | — | Pool strategy for a generic OAuth provider (#695). Persisted through `ocx account strategy <provider> <name>` or `PUT /api/oauth/accounts/pool`. The selector acts on it only while `pool.kernel` is on; with the flag off, omitted and set behave the same. `quota` is the pre-kernel behaviour either way. |
+| `providers.<name>.oauthAccountFailover.autoSwitchThreshold?` | `number` | `80` | 0–100 usage percent at which `fill-first` advances off the active account (#695). Set with `ocx account auto-switch <provider> threshold <n>`. Read only under `pool.kernel` with `strategy: "fill-first"`; an account with no measured usage counts as under the threshold. |
+| `providers.<name>.oauthAccountFailover.stickyLimit?` | `number` | `1` | Successful dispatches retained on one `round-robin` selection, 1–100 (#695). Read only under `pool.kernel` with `strategy: "round-robin"`. |
 
 To decline proactive account steering for one provider whose terms you would rather not test,
 while still recovering from a rate limit:
@@ -573,10 +591,10 @@ That setting survives logging in, adding an account, and reauthenticating.
 Generic OAuth providers (Google Antigravity, xAI, Cursor, Kimi, GitHub Copilot, Nous, and any
 other OAuth provider outside the Codex and Anthropic pools) also accept `strategy` and
 `autoSwitchThreshold` on the same key, through `GET`/`PUT /api/oauth/accounts/pool?provider=<name>`
-and the `ocx account strategy` / `ocx account auto-switch` verbs. The response carries
-`"inert": true` for those two fields only — `enabled` is live and governs the pre-dispatch
-preference. `stickyLimit` and
-`quotaWindow` are not part of the generic contract. Codex (`/api/codex-auth`) and Anthropic
+and the `ocx account strategy` / `ocx account auto-switch` / `ocx account sticky` verbs. The response carries
+`"inert"` for those three fields only — `true` while they are stored but not consumed,
+`false` once `pool.kernel` is on and they actually select an account — `enabled` is live and governs the pre-dispatch
+preference. `quotaWindow` is not part of the generic contract. Codex (`/api/codex-auth`) and Anthropic
 (`anthropicAccountPool`) keep their own contracts unchanged.
 
 Deliberately narrower than `anthropicAccountPool`: no session affinity, no quota-ranked
@@ -625,7 +643,7 @@ provider in question.
 | `failureBackoffMaxSeconds?` | `number` | `3600` | Backoff ceiling and permanent-failure delay. |
 | `codexWarmupEnabled?` | `boolean` | `false` | Opt into synthetic Codex pool-account validation. |
 | `codexWarmupMaxAgeSeconds?` | `number` | `691200` | Revalidate an account after 8 days. |
-| `codexWarmupModel?` | `string` | `gpt-5.4-mini` | Native model used for optional warmup. |
+| `codexWarmupModel?` | `string` | `gpt-5.6-luna` | Native model used for optional warmup. |
 
 ## Fixed provider endpoints
 
@@ -908,7 +926,7 @@ ids with context `922000` and max input `922000`; OpenRouter seeds `openai/gpt-5
       "baseUrl": "https://ollama.com/v1",
       "apiKey": "${OLLAMA_API_KEY}",
       "defaultModel": "glm-5.2",
-      "noVisionModels": ["glm-5.2", "glm-5.3", "gpt-oss", "qwen3-coder", "deepseek-v4-pro"]
+      "noVisionModels": ["glm-5.2", "glm-5.3", "gpt-oss", "qwen3-coder", "deepseek-v4-flash"]
     }
   },
   "subagentModels": ["anthropic/claude-opus-5", "ollama-cloud/glm-5.2"],
@@ -940,7 +958,8 @@ representation returned to the client, including the visible content-to-summary
 echoing full history with `previous_response_id` does not duplicate that history. Hidden-summary
 requests and opaque reasoning blobs retain their existing representation. Cache hits can also
 supply earlier history for delta continuations;
-after a cache miss, resend the complete conversation without `previous_response_id`. Stateless
+after a cache miss, the proxy returns `previous_response_not_found` before upstream dispatch so the
+client can resend the complete conversation without `previous_response_id`. Stateless
 repair labels orphan results and missing tool results; it cannot reconstruct lost history or
 prove whether a missing tool execution succeeded.
 
diff --git a/docs-site/src/content/docs/reference/configuration/server.md b/docs-site/src/content/docs/reference/configuration/server.md
index d4cd1e5625..108d2e0925 100644
--- a/docs-site/src/content/docs/reference/configuration/server.md
+++ b/docs-site/src/content/docs/reference/configuration/server.md
@@ -35,16 +35,19 @@ runs helper features around provider requests.
 | `visionSidecar?` | `OcxVisionSidecarConfig` | on when usable | Image-description sidecar options. |
 | `images?` | `OcxImagesConfig` | automatic OpenAI selection | Standalone Images relay options for Codex `image_gen`. |
 
-The canonical ChatGPT upstream WebSocket has a fixed 90-second response-prelude deadline,
-measured after sending the create frame. Quota and response-metadata control frames do not
-reset it; the first non-control Responses event ends it. This is not a total generation
-deadline, and neither `connectTimeoutMs` nor `stallTimeoutSec` retunes the 90 seconds
-themselves. That constant is only the WebSocket-specific upper bound: the exchange runs under
-the signal `connectTimeoutMs` (default 200s) aborts, and that abort cancels an already-sent
-create before the prelude timer can fire. A `connectTimeoutMs` below 90 seconds therefore
-ends the wait earlier, so the deadline a request actually gets is the shorter of the two. If
-either expires after sending, the stream fails without an HTTP resend, avoiding duplicate
-inference.
+While the canonical ChatGPT upstream WebSocket waits for the first Responses event after
+sending the create frame, it watches for liveness rather than a fixed deadline. When the socket
+supports protocol pings, the proxy pings it every 15 seconds. Any inbound frame — quota,
+response metadata, or a pong — resets a 90-second silence clock, so a socket without ping
+support still stays alive on its own frames, and only 90 seconds with nothing at all settles the request as an
+HTTP 504 with an `upstream_no_response` error. A slow but alive origin therefore waits for the
+client's own deadline or for `connectTimeoutMs` (default 200s), whichever comes first; a
+connect timeout that fires after the create frame was sent settles as the same 504. A socket
+that closes or errors before the first Responses event settles as an HTTP 502 with
+`upstream_closed_before_response`. These statuses are never retried inside the proxy — the
+frame may already be executing upstream, so the client applies its own retry policy exactly as
+it would when connected to the backend directly. Once the response has started, a later drop
+surfaces inside the stream as before. `stallTimeoutSec` is unrelated to this window.
 
 `noProxy` accepts either a comma-separated string or an array. Both forms add entries without
 replacing an inherited `NO_PROXY`:
@@ -507,7 +510,7 @@ an inactivity guard, not a total generation deadline.
 | --- | --- | --- | --- |
 | `enabled?` | `boolean` | on when usable | Master image-description switch. |
 | `backend?` | `"openai" \| "anthropic"` | auto | Explicit wins; unset prefers a usable stored Anthropic OAuth credential, else `openai`. |
-| `model?` | `string` | backend-dependent | `gpt-5.4-mini` for OpenAI or `claude-sonnet-5` for Anthropic. |
+| `model?` | `string` | backend-dependent | `gpt-5.6-luna` for OpenAI or `claude-sonnet-5` for Anthropic. |
 | `maxDescriptionsPerTurn?` | `number` | `8` | New description cache misses admitted per main turn. `0` disables calls; invalid values use default. |
 | `timeoutMs?` | `number` | `45000` | Sidecar fetch timeout. Integer 1–2147483647. |
 
diff --git a/docs-site/src/content/docs/reference/management-api.md b/docs-site/src/content/docs/reference/management-api.md
index b7fdbf072f..cd8b2450c2 100644
--- a/docs-site/src/content/docs/reference/management-api.md
+++ b/docs-site/src/content/docs/reference/management-api.md
@@ -78,11 +78,20 @@ route-specific results rather than repeating this table.
 | `GET /api/grok` | Read Grok managed-config status and candidate models | 400 status read failure |
 | `PUT /api/grok/selection` | Persist the excluded Grok models | 400 invalid or oversized selection |
 | `POST /api/grok/apply` | Apply persisted Grok configuration through the managed sync | 409 `grok_apply_busy`; 400/500 apply failure |
+| `GET /api/grok/reset-coupons?accountId=...` | Read remaining Grok billing reset tokens and validity windows for the active or specified xAI account | 400 missing account; 401 unauthenticated; 502 upstream gRPC-Web error |
+| `POST /api/grok/reset-coupons/consume` | Redeem an eligible reset coupon. Body `{ accountId?, tokenId?, operationId? }`. Optional `operationId` (UUIDv4) makes redemption idempotent: repeating the same ID replays the durable result without double-redemption. | 400 invalid JSON/UUID; 401 unauthenticated; 409 `identity_mismatch`; 502 upstream error; 503 ledger capacity |
 | `GET, PUT /api/claude-desktop` | Read or persist the Claude Desktop routed/native profile | 400 invalid or unavailable assignment |
 | `POST /api/claude-desktop/apply` | Write the saved profile to Claude Desktop's managed config | 400/500 write failure |
 | `GET /api/claude-desktop/status` | Inspect saved-versus-applied profile and Desktop health | 400 status read failure |
 | `GET, PUT /api/claude-code` | Read or update Claude Code gateway, auth-mode, model-map, context, agent, and sidecar settings | 400 invalid field or shape |
 
+The dashboard drives both coupon paths from **Providers > xAI Grok > Accounts**: each
+signed-in account row carries a ticket badge with its remaining coupon count, and the
+badge opens a dialog that lists validity windows and redeems the coupon closest to
+expiry. The dialog sends a client-minted `operationId`, and it stops sending after a
+timeout instead of retrying, because a redemption whose journal record is still open
+would execute again. `ocx account grok-reset-coupons` remains the terminal equivalent.
+
 For the concepts behind the model roster and encrypted worker-task behavior, see
 [Sub-agent Surface](/guides/sub-agent-surface/).
 
@@ -329,7 +338,8 @@ outcome fields from an older server do not establish successful recovery.
 | `POST /api/oauth/logout` | Remove the selected provider credential | 400 unknown provider; `oauth_mutation_busy` |
 | `GET, DELETE /api/oauth/accounts` | List masked accounts or remove one account | 400 invalid provider/id; 404 account missing; `oauth_mutation_busy` |
 | `PUT /api/oauth/accounts/active` | Select the active OAuth account | 400 invalid provider/account; `oauth_mutation_busy` |
-| `GET, PUT, PATCH /api/oauth/accounts/pool` | Read or update Anthropic OAuth pool policy | 400 non-Anthropic provider or invalid policy |
+| `GET, PUT, PATCH /api/pool/settings` | Read or update pool policy for any kind (codex, anthropic, generic); answers with the same keys for all three and declares in `supported` which the kind honours | 400 unknown provider, a field the kind does not support, or an invalid value |
+| `GET, PUT, PATCH /api/oauth/accounts/pool` | Legacy per-pool policy for Anthropic and generic OAuth providers; superseded by `/api/pool/settings` and kept for existing clients | 400 codex or api-key provider, or invalid policy |
 | `POST /api/oauth/accounts/clear-cooldown` | Clear one OAuth account's runtime cooldown | 400 invalid provider/account |
 | `PUT /api/oauth/accounts/alias` | Set or clear an OAuth account alias | 400 invalid provider/account/alias |
 | `GET, POST, DELETE /api/providers/keys` | List masked provider keys, add/activate one, or remove one | 400 invalid input; 404 provider/key missing |
diff --git a/docs-site/src/content/docs/reference/proxy-formats.md b/docs-site/src/content/docs/reference/proxy-formats.md
index ed856803ad..7cec1af766 100644
--- a/docs-site/src/content/docs/reference/proxy-formats.md
+++ b/docs-site/src/content/docs/reference/proxy-formats.md
@@ -81,6 +81,11 @@ With `stream: true`, the response is `text/event-stream`. The bridge emits Respo
 With `stream: false` or no `stream`, the same adapter events are collected into one Responses JSON
 object. Both forms preserve the selected model, output items, terminal status, and usage.
 
+When a provider filters or truncates a response, an unfinished tool call remains `incomplete`
+in both JSON and SSE. Partial output is preserved, and the bridge does not emit an argument
+completion event for that open call. Calls already completed keep their status. This preserves
+the provider outcome; client retry behavior for incomplete responses is unchanged.
+
 On the pending `dev` implementation for #4112, a final upstream HTTP 413 on this surface
 is classified as `invalid_request_error` / `context_length_exceeded`. Non-streaming callers
 retain HTTP 413 with a JSON `error`; streaming callers retain the terminal SSE failure.
@@ -487,6 +492,8 @@ Responses-family and Chat requests accept a proxy key in the dedicated header or
 
 A keyless, non-OAuth Cursor route may use that separate caller bearer, but never a proxy secret or automatic ChatGPT-main enrichment. Combo/policy selection and actual shadow/thread-spawn rewrites do not transfer raw caller credentials to new targets. Canonical OpenAI routing can restore the caller’s single non-proxy bearer after an internal route change only when its JWT carries a ChatGPT account claim and any explicit account header matches that claim. Forwarding caller authentication to optional OpenAI sidecars requires a single JWT and a matching explicit `chatgpt-account-id`. Opaque bearers are not restored across route changes, even with an explicit account header. Otherwise, the final target needs its own configured, OAuth, or stored credential; otherwise it fails locally. A thread-spawn marker alone does not strip credentials.
 
+Chat's optional stored-main enrichment for a keyless Cursor request is deferred until an OpenAI helper is actually planned and a canonical Direct candidate is available. An unrelated Cursor request does not acquire a native-main claim through this enrichment, so it does not delay profile switching. Helper credentials still obey startup and switch fences and remain separate from the Cursor bearer. Pool and account-qualified helpers retain their existing account selection.
+
 Claude replay retains main auth only as a turn-claimed in-memory snapshot and reconstructs it only for a final canonical ChatGPT route.
 
 :::caution
diff --git a/docs-site/src/content/docs/ru/getting-started/quickstart.md b/docs-site/src/content/docs/ru/getting-started/quickstart.md
index c0f87f1986..20460589f9 100644
--- a/docs-site/src/content/docs/ru/getting-started/quickstart.md
+++ b/docs-site/src/content/docs/ru/getting-started/quickstart.md
@@ -79,7 +79,7 @@ codex -m "ollama-cloud/glm-5.2"      "Write a SQL migration"
 ## Выбор моделей подагентов (опционально)
 
 В свежей конфигурации в селекторе подагентов Codex представлены пять нативных моделей: `gpt-5.5`,
-`gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` и `gpt-5.4-mini`. Откройте `ocx gui`, чтобы
+`gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` и `gpt-6-astra`. Откройте `ocx gui`, чтобы
 заменить или переупорядочить до пяти нативных или маршрутизируемых моделей. В панели управления
 также можно задать одну предпочитаемую модель подагента и уровень рассуждений. Раздел
 [Поверхность подагентов](/guides/sub-agent-surface/) поможет выбрать v1/base/v2 и понять, когда
diff --git a/docs-site/src/content/docs/ru/guides/claude-code.md b/docs-site/src/content/docs/ru/guides/claude-code.md
index f5504c9dc2..41cefcc951 100644
--- a/docs-site/src/content/docs/ru/guides/claude-code.md
+++ b/docs-site/src/content/docs/ru/guides/claude-code.md
@@ -525,3 +525,5 @@ Responses `web_search_call` в парные блоки Anthropic `server_tool_us
 **Подагент отправляется не в ту модель** — агенты из ростера (`ocx-*`) используют директивы
 `<!-- ocx-route: ... -->`, а не аргумент `model` инструмента Agent. Убедитесь, что директива
 соответствует нужному маршруту. В качестве плейсхолдера модели передавайте `"haiku"`.
+
+Параметр `claudeCode.stabilizePromptCache: true` в `config.json` переносит поддерживаемые уведомления Claude в конце системных инструкций в последнее пользовательское сообщение на маршрутах с преобразованием. По умолчанию он выключен (`false`). Включайте его только когда такое изменение роли допустимо для ваших клиентов. Примеры в блоках кода и нераспознанный текст сохраняются; нативная передача Anthropic не меняется. Без метаданных ключ кэша рассчитывается по стабилизированным инструкциям. Идентификатор разговора не создаётся, попадания в кэш не гарантируются.
diff --git a/docs-site/src/content/docs/ru/guides/codex-app-models.md b/docs-site/src/content/docs/ru/guides/codex-app-models.md
index e208ab4b0b..5f8c458184 100644
--- a/docs-site/src/content/docs/ru/guides/codex-app-models.md
+++ b/docs-site/src/content/docs/ru/guides/codex-app-models.md
@@ -77,8 +77,8 @@ visibility = "list"
 
 ## Текущее покрытие стабильных моделей
 
-Нативный fallback-набор включает `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`,
-`gpt-5.3-codex-spark` и GPT-5.6 Sol/Terra/Luna. Для семейства GPT-5.5/5.4 opencodex сохраняет
+Нативный fallback-набор включает `gpt-5.5`,
+`gpt-5.3-codex-spark` и GPT-5.6 Sol/Terra/Luna. Для семейства GPT-5.5 opencodex сохраняет
 более богатые живые записи установленного каталога Codex и синтезирует только отсутствующую
 запись. Bundled upstream-snapshot используется только для GPT-5.6, где он даёт настоящую
 per-model identity и метаданные вместо приближения по старому шаблону.
diff --git a/docs-site/src/content/docs/ru/guides/codex-integration.md b/docs-site/src/content/docs/ru/guides/codex-integration.md
index e695830370..d2f135be2f 100644
--- a/docs-site/src/content/docs/ru/guides/codex-integration.md
+++ b/docs-site/src/content/docs/ru/guides/codex-integration.md
@@ -368,7 +368,7 @@ v1/base/v2 при делегировании и fallback — в
 
 ## Прогрев аккаунтов Codex
 
-При добавлении или повторной аутентификации аккаунт обычно проверяется до сохранения небольшим запросом, ожидающим `response.completed`. По умолчанию используется `gpt-5.4-mini`, при HTTP 400 или HTTP 404 — повтор с `gpt-5.5` и `gpt-5.6-luna`. Публичные ошибки содержат фиксированные категории без исходного тела ответа.
+При добавлении или повторной аутентификации аккаунт обычно проверяется до сохранения небольшим запросом, ожидающим `response.completed`. По умолчанию используется `gpt-5.6-luna`, при HTTP 400 или HTTP 404 — повтор с `gpt-5.5`. Публичные ошибки содержат фиксированные категории без исходного тела ответа.
 
 Если запрос квоты с новым OAuth-токеном подтверждает исчерпание пятичасовой, недельной или месячной квоты, аккаунт сохраняется без вызова модели со статусом **Ожидает проверки**. Перезапуск и обновление токена не включают маршрутизацию. После восстановления квоты обновите её: полные свежие данные с доступной ёмкостью разрешают небольшой проверочный запрос. Только успешное завершение включает аккаунт. Ошибки сохраняют ограничение. Пассивный опрос не отправляет такой запрос. Неизвестная квота при регистрации требует обычной проверки.
 
@@ -390,7 +390,7 @@ v1/base/v2 при делегировании и fallback — в
 ocx config set codexPool '{"excludedPlans":["free"]}'
 ```
 
-Это политика выбора, а не блокировка. Исключённый аккаунт сохраняет учётные данные, историю квот и привязку к треду, остаётся видимым в списке и по-прежнему доступен при явном выборе вроде `work/gpt-5.4`. Меняется только то, что автоматическая ротация перестаёт его выбирать — в том числе когда он уже активен или уже привязан к треду, а именно это состояние остаётся после истёкшей подписки.
+Это политика выбора, а не блокировка. Исключённый аккаунт сохраняет учётные данные, историю квот и привязку к треду, остаётся видимым в списке и по-прежнему доступен при явном выборе вроде `work/gpt-5.5`. Меняется только то, что автоматическая ротация перестаёт его выбирать — в том числе когда он уже активен или уже привязан к треду, а именно это состояние остаётся после истёкшей подписки.
 
 Два намеренных ограничения. Основной аккаунт Codex никогда не исключается по тарифу: маршрутизация в режиме «только выбор» скрывает его тариф, чтобы не читать защищённые нативные учётные данные, и правило для него противоречило бы само себе. А если не осталось ни одного неисключённого аккаунта, исключённый всё равно отвечает вместо отказа; чтобы остановить обслуживание полностью, по-прежнему нужно поставить на паузу все аккаунты. Аналога `minimumPlan` нет: чтобы ранжировать тарифы ChatGPT, нужен полный порядок, которого здесь не существует.
 
@@ -409,3 +409,9 @@ ocx restore back # point plain Codex at the running proxy again
 Когда opencodex работает как управляемая [фоновая служба](/reference/cli/#ocx-service), он
 устанавливает `OCX_SERVICE=1`, чтобы service-driven restart **не** дёргал конфигурацию Codex —
 только явный `ocx stop` / `ocx service stop` восстанавливает нативный Codex.
+
+## Защитный отказ для постраничной истории
+
+Если затронутое хранилище поддерживает постраничную историю, смена провайдера может вернуть `history_paginated_requires_native_writer`, в том числе для строк legacy. OpenCodex сохраняет конфигурацию, профиль, каталог, историю и данные восстановления, не назначая номера вне Codex. Пути без смены провайдера, например сохранение внешнего провайдера, остаются доступны.
+
+Не удаляйте используемое разговором определение провайдера, не повторяйте `ocx sync` или legacy-восстановление и не переписывайте активную историю. Сохраните файлы, закройте разговор перед восстановлением и сообщите точную ошибку и версии без публикации личной истории. Требуется проверенное исправление с согласованием с нативным процессом записи. Наличие резервной копии или успешный скрипт не доказывает восстановление отображения: проверьте разговор после повторного открытия Codex.
diff --git a/docs-site/src/content/docs/ru/guides/combos.md b/docs-site/src/content/docs/ru/guides/combos.md
index 3d4820e521..b873f4ed03 100644
--- a/docs-site/src/content/docs/ru/guides/combos.md
+++ b/docs-site/src/content/docs/ru/guides/combos.md
@@ -150,6 +150,8 @@ ocx combo set balanced \
 данных о квоте, а также цели с одинаковым временем сброса сохраняют порядок конфигурации. Значения
 `weight` и `stickyLimit` не влияют на эту стратегию.
 
+Для этого ранжирования и исключения провайдеров до отправки нужны свежие лимиты инференса моделей, применимые к единственному текущему API-ключу в целом. Сводки OAuth и текущего аккаунта, маршруты с передачей учётных данных вызывающей стороны, несколько ключей и снимки с изменившимися учётными данными или адресом назначения служат только для отображения при этом предварительном решении. То же относится к переопределению учётных данных заголовками `Authorization`, `x-api-key` или `x-goog-api-key`; окна только для поиска или MCP исключаются. Если ни у одной допустимой цели нет подходящего времени сброса, используется порядок конфигурации. При выборе аккаунта и повторных попытках по-прежнему действуют обычные ограничения.
+
 ## Что происходит, когда цель сбоит
 
 Сбои в combo делятся на **hop**-сбои и **terminal**-сбои.
@@ -232,9 +234,7 @@ effort вызывающей стороне и цели.
 переименовывать и удалять combo, а селектор целей исключает отключённые модели и вложенные combo.
 
 У каждой цели также отображается актуальный значок квоты: **Доступно**, **Квота исчерпана** или **Квота неизвестна**.
-Кнопки сохранения и создания отключаются только тогда, когда для всех включённых целей есть свежие и полные
-данные об исчерпании квоты. Отсутствующие, устаревшие, некорректные или неполные агрегированные данные остаются
-неизвестными и никогда не блокируют управление. Восстановление квоты автоматически снова включает действие. Редактор дашборда пока не предоставляет `cooldownMs` и `waitForCooldownMs`; до появления соответствующего UI используйте файл конфигурации или Management API.
+Редактор блокирует сохранение и создание из-за квоты только тогда, когда для каждой пригодной к использованию цели есть действующее подтверждение сервера об исчерпании лимита инференса для настроенных учётных данных. Квоты аккаунта, модели, поиска и MCP, предназначенные только для отображения, а также отсутствующие или просроченные данные для принятия решения о маршрутизации не вызывают эту блокировку. Блокировка истекает при соответствующем сбросе квоты или окончании срока актуальности данных и проверяется повторно, когда страница становится активной или видимой; «Обновить» повторно загружает и данные combo, и квоты. Редактор дашборда пока не предоставляет `cooldownMs` и `waitForCooldownMs`; до появления соответствующего UI используйте файл конфигурации или Management API.
 
 ### CLI
 
diff --git a/docs-site/src/content/docs/ru/guides/providers.md b/docs-site/src/content/docs/ru/guides/providers.md
index 39e0cb4dd3..a2c156865e 100644
--- a/docs-site/src/content/docs/ru/guides/providers.md
+++ b/docs-site/src/content/docs/ru/guides/providers.md
@@ -95,8 +95,10 @@ account id, OpenAI beta/originator/session — см. [Адаптеры](/ru/refe
 
 Восемь пресетов провайдеров используют вход через OAuth — плюс GitHub Copilot через
 экспериментальный неофициальный мост device flow. opencodex хранит их учётные данные в
-`~/.opencodex/auth.json` и обновляет их автоматически. CLI входа также принимает `chatgpt`: эта
-команда получает учётные данные ChatGPT и одновременно создаёт запись провайдера в режиме `forward`.
+`~/.opencodex/auth.json` и обновляет их автоматически. CLI входа принимает и `ocx login codex`, но это
+не один из провайдеров выше: команда направляется во вход пула аккаунтов Codex (тот же поток, что и
+`ocx account login codex`). У пула отдельный реестр аккаунтов, поэтому такому входу нужен запущенный
+прокси. `chatgpt` и `openai` — псевдонимы того же маршрута.
 
 ```bash
 ocx login xai          # xAI Grok
@@ -107,8 +109,9 @@ ocx login kiro         # импорт учётных данных kiro-cli (с 
 ocx login google-antigravity
 ocx login cursor       # отдельный PKCE-вход Cursor
 ocx login command-code # браузерный OAuth Command Code (или импорт ~/.commandcode/auth.json)
+ocx login devin       # Вход в Cognition/Devin через браузер (Auth0)
 ocx login github-copilot  # device flow GitHub → токен Copilot (Copilot Pro/Business)
-ocx login chatgpt      # отдельный OAuth-вход ChatGPT
+ocx login codex        # пул аккаунтов Codex (псевдонимы: chatgpt, openai; нужен запущенный прокси)
 ocx logout <provider>
 ```
 
@@ -121,6 +124,8 @@ ocx logout <provider>
 | `kiro` | `kiro` | `https://runtime.us-east-1.kiro.dev` | Первый вход импортирует существующую сессию после установки Kiro CLI (в Unix: `curl -fsSL https://cli.kiro.dev/install` &#124; `bash`; в Windows PowerShell: `irm 'https://cli.kiro.dev/install.ps1'` &#124; `iex`; затем выполните `kiro-cli login`). **Добавить аккаунт** выполняет выход из `kiro-cli`, запускает новый вход через браузер, переключает аккаунт самого `kiro-cli` и сохраняет метаданные профиля отдельно для каждого аккаунта. Существующие аккаунты OpenCodex сохраняются; при отмене или сбое восстанавливается предыдущая сессия `kiro-cli`. |
 | `google-antigravity` | `google` | `https://daily-cloudcode-pa.googleapis.com` | Google OAuth поверх протокола Cloud Code Assist. Живое обнаружение использует аутентифицированный CCA-эндпоинт `v1internal:fetchAvailableModels` и публикует только agent-модели, доступные текущему аккаунту; поддерживаемый каталог остаётся резервным вариантом. |
 | `cursor` | `cursor` | `https://api2.cursor.sh` | Экспериментальный PKCE-вход, живой транспорт HTTP/2 и обнаружение моделей с фильтрацией по аккаунту. |
+| `devin` | `devin` | `https://server.codeium.com` | Экспериментальный неофициальный мост к Cognition/Devin. Вход открывает страницу Auth0 в браузере, затем токен обменивается через `RegisterUser` на долгоживущий API-ключ. Список моделей запрашивается для каждой учётной записи через `GetCascadeModelConfigs`; потоковая передача идёт только по пути `runTurn` поверх Connect-RPC. В пресете панели по умолчанию отсутствует. |
+| `devin-cli` | `devin` | `https://server.codeium.com` | Импортирует учётные данные, которые установленный Devin CLI уже хранит (`devin auth login` записывает их в свой `credentials.toml`), а затем передаёт потоком через Connect-RPC api-server Cognition, как и провайдер `devin` — без входа в браузере и без ключа для вставки. Список моделей и контекстные окна берутся из каталога вашей учётной записи. Для собственного локального цикла агента CLI (ACP stdio) используйте строку с другим именем и `"adapter": "devin-cli"`. |
 | `github-copilot` | `openai-chat` | `https://api.githubcopilot.com` | Экспериментально. Device flow GitHub + обмен `copilot_internal` (OAuth-клиент VS Code). Требуется активная подписка Copilot; это не официальный сторонний API. |
 
 Проверки квот аккаунтов и провайдера Google Antigravity используют фиксированные адреса Google, включая резервный запрос списка моделей. Для этих адресов поддерживается прозрачный Fake-IP DNS с сохранением проверки TLS, запрета перенаправлений и проверки частных адресов. Пользовательский base URL меняет только запросы моделей; `NO_PROXY` сохраняет политику прямого подключения.
@@ -278,7 +283,7 @@ Volcengine Agent Plan использует нативную конечную т
 > каталог. У шлюза Agent Plan ресурса `/models` нет. Для pay-as-you-go модель по умолчанию —
 > `doubao-seed-2-1-pro-260628`; его статический каталог также включает актуальные текстовые модели
 > DeepSeek и GLM. Для Coding Plan модель по умолчанию — `ark-code-latest`, для Agent Plan —
-> `deepseek-v4-pro`.
+> `deepseek-v4-flash`.
 
 **Discovery для Chutes.** Пресет `chutes` использует фиксированный общий OpenAI-совместимый LLM
 gateway Chutes. Из публичного каталога `/v1/models` он оставляет только строки, где
@@ -472,7 +477,7 @@ Ollama Cloud — это размещённая в облаке (не локал
 получает список моделей от провайдера, поэтому новые модели Ollama Cloud появляются без
 изменения конфигурации. opencodex классифицирует её облачную
 линейку по поддержке изображений, чтобы [vision-сайдкар](/ru/guides/sidecars/) включался
-только для текстовых моделей. Текстовые модели (например, `glm-5.2`, `deepseek-v4-pro`, `gpt-oss`,
+только для текстовых моделей. Текстовые модели (например, `glm-5.2`, `deepseek-v4-flash`, `gpt-oss`,
 `qwen3-coder`, `minimax-m2.x`, `nemotron-3-*`) перечислены в `noVisionModels`; модели с нативной
 поддержкой изображений (например, `kimi-k2.6`, `minimax-m3`, `gemma4`, `qwen3.5`,
 `gemini-3-flash-preview`) — нет. Сопоставление терпимо к тегам Ollama вида `:size`, поэтому
diff --git a/docs-site/src/content/docs/ru/guides/sidecars.md b/docs-site/src/content/docs/ru/guides/sidecars.md
index cdb6dc7087..54cf37020e 100644
--- a/docs-site/src/content/docs/ru/guides/sidecars.md
+++ b/docs-site/src/content/docs/ru/guides/sidecars.md
@@ -88,7 +88,7 @@ opencodex описывает каждое изображение **до** осн
 объявляют вход изображений только если каждый участник принимает изображения нативно или через
 сайдкар и параметр комбо `imageInput` не отключён; поэтому такие клиенты, как приложение Codex,
 разрешают вложения вместо их блокировки до запуска сайдкара. Если `visionSidecar.model` отсутствует или пуст, путь выполнения OpenAI, дашборд и API управления
-используют фолбэк `gpt-5.4-mini`. При запуске явно сохранённое устаревшее значение
+используют фолбэк `gpt-5.6-luna`. При запуске явно сохранённое устаревшее значение
 `gpt-5.4-mini` по-прежнему мигрирует на `gpt-5.6-luna`; миграция применяется только к сохранённому
 значению, а не к отсутствующему полю модели.
 
@@ -139,7 +139,7 @@ opencodex описывает каждое изображение **до** осн
   "providers": {
     "ollama-cloud": {
       "baseUrl": "https://ollama.com/v1",
-      "noVisionModels": ["glm-5.2", "gpt-oss", "qwen3-coder", "deepseek-v4-pro"]
+      "noVisionModels": ["glm-5.2", "gpt-oss", "qwen3-coder", "deepseek-v4-flash"]
     }
   }
 }
diff --git a/docs-site/src/content/docs/ru/guides/sub-agent-surface.md b/docs-site/src/content/docs/ru/guides/sub-agent-surface.md
index 7dfd7ea94c..edfb1fe75c 100644
--- a/docs-site/src/content/docs/ru/guides/sub-agent-surface.md
+++ b/docs-site/src/content/docs/ru/guides/sub-agent-surface.md
@@ -169,7 +169,7 @@ ocx v2 threads 8
 ocx agent status
 ocx agent injection set --model anthropic/claude-sonnet-5 --effort xhigh
 ocx agent subagents set gpt-5.6-sol,anthropic/claude-sonnet-5
-ocx agent fallback set gpt-5.4-mini,xai/grok-4.5 --poll-ms 60000
+ocx agent fallback set gpt-5.6-luna,xai/grok-4.5 --poll-ms 60000
 ocx agent effort set --subagent max
 ```
 
diff --git a/docs-site/src/content/docs/ru/guides/web-dashboard.md b/docs-site/src/content/docs/ru/guides/web-dashboard.md
index 4600b51ace..05b11a8780 100644
--- a/docs-site/src/content/docs/ru/guides/web-dashboard.md
+++ b/docs-site/src/content/docs/ru/guides/web-dashboard.md
@@ -39,7 +39,7 @@ bun run dev:gui
 | **Трей Windows** | Устанавливает пользовательский значок входа для запуска, остановки, перезапуска, панели и состояния прокси одним щелчком. Трей не является службой перезапуска. |
 | **Автозапуск Codex** | Разрешает уже установленному launcher shim Codex выполнять `ocx ensure`. Переключатель не устанавливает shim или фоновую службу. |
 | **Providers** | Добавление, редактирование, назначение провайдера по умолчанию (только включённые), включение/отключение и удаление провайдеров; управление пулами OAuth-аккаунтов и пулами API-ключей там, где они поддерживаются. При удалении текущего провайдера по умолчанию выбирается первый оставшийся включённый провайдер, если он есть; иначе удаление отклоняется и текущий default сохраняется. Для пулов Claude (Anthropic) OAuth у каждого вошедшего аккаунта свои полосы 5-часового и недельного лимита (использование по учётным данным); при сбое опроса сохраняются последние известные значения с пометкой недоступности. Обзор Providers, который показывается, когда провайдер не выбран, содержит кнопку **Обновить все квоты**: она принудительно перечитывает на сервере все настроенные провайдеры за один раз. Провайдер с неудачным опросом сохраняет последнее известное значение, поэтому статус сообщает лишь о завершении проверки, а не о том, что все значения свежие; время проверки в каждой строке остаётся признаком актуальности для конкретного провайдера. |
-| **Add provider** | Поиск по пресетам из реестра: вход по аккаунту, сервисы с API-ключом, локальные серверы или пользовательская конечная точка. |
+| **Add provider** | Одно поле поиска над вкладками ищет сразу по всем четырём — Аккаунты, Бесплатные, Локальные, Платные. Во время поиска выбранная вкладка не переключается, а результаты группируются по вкладкам с количеством. У локальных сред выполнения (Ollama, vLLM, LM Studio, LiteLLM) своя вкладка, а длинное описание сворачивается до двух строк и открывается целиком по клику. |
 | **Codex Auth** | Добавление аккаунтов пула ChatGPT/Codex, выбор аккаунта для следующей сессии, обновление квот 5 ч / недельных / 30-дневных, включение или отключение автопереключения, настройка его порога 1–100% и failover при временных сбоях. |
 | **Subagents** | Выделение до пяти «голых» нативных или маршрутизируемых моделей с пространством имён в списке переопределений `spawn_agent`. |
 | **Models** | Включение и отключение нативных GPT и маршрутизируемых моделей, настройка списков разрешённых провайдеров и лимитов контекста, выбор v1/base/v2 и настройка лимита потоков v2. |
diff --git a/docs-site/src/content/docs/ru/reference/adapters.md b/docs-site/src/content/docs/ru/reference/adapters.md
index 0ec59367b7..f93dcc0b83 100644
--- a/docs-site/src/content/docs/ru/reference/adapters.md
+++ b/docs-site/src/content/docs/ru/reference/adapters.md
@@ -235,6 +235,16 @@ authorization.
   одобрений/песочницы Codex; устаревший `unsafeAllowNativeLocalExec: true` эквивалентен только
   если `nativeLocalExec` не задан.
 
+## `devin`
+
+**Назначение:** `exa.api_server_pb.ApiServerService/GetChatMessage` в Cognition, потоковая передача Connect на `server.codeium.com`.
+**Аутентификация:** ключ API Devin/Cognition из `provider.apiKey` или переданного заголовка authorization. Вход открывает страницу Auth0 в браузере, после чего токен обменивается через `SeatManagementService.RegisterUser` на долгоживущий ключ.
+
+- Используется `runTurn`, а не обычный путь fetch/parse. Запросы и серверные события кодируются вручную в `devin/cloud-direct/wire.ts`.
+- Модели запрашиваются для каждой учётной записи через `GetCascadeModelConfigs`; отсутствующие в тарифе отсеиваются в списке, а не падают в момент запроса.
+- Cognition ограничивает длину описаний инструментов и блокирует точные фразы. Адаптер переписывает известные формулировки и обрезает слишком длинные описания.
+- Ключи не обновляются. После истечения или отзыва выполните `ocx login devin` заново.
+
 ## `azure-openai` (алиас: `azure`)
 
 **Назначение:** **Azure OpenAI**. Обёртка над `openai-responses` (поэтому тоже
diff --git a/docs-site/src/content/docs/ru/reference/cli/agents.md b/docs-site/src/content/docs/ru/reference/cli/agents.md
index 8df8175173..eadeb03d61 100644
--- a/docs-site/src/content/docs/ru/reference/cli/agents.md
+++ b/docs-site/src/content/docs/ru/reference/cli/agents.md
@@ -152,7 +152,7 @@ override, но файлы на диске никогда не меняются.
 
 ## Экспорт client config
 
-### `ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|prime|aside|raycast>`
+### `ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|prime|aside|raycast|omo>`
 
 Печатает client config, направленный на работающий прокси. Команда сериализует блок
 провайдера `opencodex` в нативном формате выбранного клиента: base URL, список моделей и,
@@ -163,7 +163,7 @@ override, но файлы на диске никогда не меняются.
 
 | Флаг | Действие |
 | --- | --- |
-| `--client <opencode\|pi\|omp\|hermes\|openclaw\|kimi\|gajae\|dsh\|mcode\|zcode\|prime\|aside\|raycast>` | Обязателен. Выбирает формат конфигурации клиента. |
+| `--client <opencode\|pi\|omp\|hermes\|openclaw\|kimi\|gajae\|dsh\|mcode\|zcode\|prime\|aside\|raycast\|omo>` | Обязателен. Выбирает формат конфигурации клиента. |
 | `--json` | Печатать только JSON-конфиг в stdout, чтобы redirect сохранял побайтно точный вывод. Вся диагностика, включая заметку о записи через `--out`, идёт в stderr. |
 | `--out <path>` | Записать конфиг в `<path>`. Перезаписывать существующий файл не позволит. |
 | `--force` | Разрешить `--out` заменить существующий файл. |
@@ -193,7 +193,9 @@ ocx export --client opencode --out ~/opencodex-opencode.json
 | `mcode` | `~/.minimax/config.yaml` (`MINIMAX_DATA_DIR`, затем устаревшая `MAVIS_DATA_DIR`, имеют приоритет, если заданы; относительное значение отклоняется) | `mcode-config.yaml` | нет — loopback placeholder |
 | `zcode` | `~/.zcode/v2/config.json` (`ZCODE_DATA_DIR` имеет приоритет, если задана; относительное значение отклоняется) | `config.json` | нет — loopback placeholder |
 | `prime` | `~/.prime/agent/models.json` (`PRIME_AGENT_CODING_AGENT_DIR` имеет приоритет, если задана; относительное значение отклоняется) | `prime-models.json` | нет — loopback placeholder |
+| `aside` | `~/.aside/u/<account>/models.json` для аккаунта, который `accounts.json` самого Aside называет текущим; нечитаемый манифест отклоняется, а не подменяется произвольным аккаунтом | `aside-models.json` | нет — loopback placeholder |
 | `raycast` | `~/.config/raycast/ai/providers.yaml` одинаково на macOS и Windows (Raycast не учитывает `XDG_CONFIG_HOME`) | `raycast-providers.yaml` | нет — только loopback, запись `api_keys` не создаётся |
+| `omo` | `~/.omo/agent/models.json` (`OMO_CODING_AGENT_DIR`, затем `SENPI_CODING_AGENT_DIR`, затем `PI_CODING_AGENT_DIR` имеют приоритет в этом порядке, если заданы; относительное значение отклоняется) | `omo-models.json` | нет — loopback placeholder |
 
 Экспорт для Raycast — это отдельный документ `providers.yaml` с одним элементом `id: opencodex` в
 последовательности `providers`: `name: OpenCodex`, базовый URL прокси с `/v1` и каждая маршрутизируемая
@@ -222,8 +224,8 @@ MCP-записи.
 env-reference, либо несекретную loopback-заглушку. Loopback-прокси (`127.0.0.1`, по умолчанию) вообще не
 требует admission key. Если прокси слушает не на loopback, задайте соответствующую переменную
 `OPENCODEX_OPENCODE_API_KEY`, `OPENCODEX_HERMES_API_KEY` или `OPENCODEX_OPENCLAW_API_KEY`.
-`OPENCODEX_GAJAE_API_KEY` передаёт provider credential Gajae через окружение, но не позволяет
-отправить remote admission header, поэтому сгенерированная интеграция Gajae
+`OPENCODEX_GAJAE_API_KEY` передаёт provider credential gjc через окружение, но не позволяет
+отправить remote admission header, поэтому сгенерированная интеграция gjc
 работает только через loopback. Как выдаются admission key, описано в
 [Удалённом доступе](/reference/configuration/#remote-access). Ключи upstream-провайдеров — это совсем
 отдельная история и настраиваются в [Провайдерах](/guides/providers/).
diff --git a/docs-site/src/content/docs/ru/reference/cli/providers-accounts.md b/docs-site/src/content/docs/ru/reference/cli/providers-accounts.md
index 4ae2bc7b5f..76791eb148 100644
--- a/docs-site/src/content/docs/ru/reference/cli/providers-accounts.md
+++ b/docs-site/src/content/docs/ru/reference/cli/providers-accounts.md
@@ -71,9 +71,11 @@ API-key-провайдеров.
 
 Ту же команду используйте и для **reauthentication**, когда `ocx status` / `ocx doctor`
 сообщают, что нужна переавторизация или refresh завершился терминальной ошибкой (либо используйте
-Reauthenticate в дашборде). Аккаунты пула Codex не являются публичным провайдером для `ocx login`
-— переавторизовать их нужно либо через пул аккаунтов Codex в дашборде, либо через headless-flow
-`ocx account reauth`.
+Reauthenticate в дашборде). Аккаунты пула Codex не входят в список OAuth- и API-key-провайдеров выше,
+но `ocx login codex` до них доходит: команда направляется во вход пула аккаунтов, поэтому
+`ocx login codex --reauth` — это то же самое, что `ocx account reauth codex`. Пул аккаунтов Codex в
+дашборде (Reauthenticate) делает то же. Этот маршрут работает внутри прокси, поэтому ему нужен
+запущенный прокси.
 
 ```bash
 ocx login xai
@@ -92,7 +94,7 @@ ocx login anthropic
 Поставляемая help-surface выглядит так:
 
 ```text
-Usage: ocx account <list|current|use|refresh|auto-switch|priority|login|reauth|code|cancel|remove|add-key|reset-credits> ...
+Usage: ocx account <list|current|use|refresh|auto-switch|priority|login|reauth|code|cancel|remove|add-key|reset-credits|grok-reset-coupons> ...
 
 list [provider]     Codex account pool, OAuth accounts and API keys (identifiers shown masked as the API returns them).
 current <provider>  Show the active account or key.
@@ -104,6 +106,7 @@ remove <provider> <id> --yes  Remove a stored account or key after an existence
 add-key <provider> [--label <label>]  Add a key read only from piped stdin.
 login/reauth/code/cancel  Run browser or manual-code auth from a headless shell.
 reset-credits <id|main> [--consume --yes]  Inspect or consume Codex reset credits.
+grok-reset-coupons [<id>] [--consume --yes] [--token-id <token-id>] [--operation-id <uuid>]  Inspect or redeem Grok reset coupons.
 Codex pool selection applies to the next request after clearing existing affinity; in-flight requests keep their captured account.
 ```
 
@@ -190,11 +193,11 @@ quota-bar'ов дашборда.
 
 ### `ocx account auto-switch <provider> <on|off|status|threshold <0-100>> [--json]`
 
-Управляет порогом пула Codex `openai` или сохраняет порог общего пула OAuth. `on` сохраняет 80 %, `off` — 0 %, а `threshold <n>` принимает 0–100. Пороги общих пулов пока не применяются: сохранение не включает переключение по порогу, не меняет настройку включения провайдера и не отключает ротацию после ошибки 429. Для общего пула результат чтения и изменения берётся из подтверждённого ответа сервера. Для общего пула `poolEnabled` — сохранённая настройка провайдера (`null` означает отсутствие настройки), а не итоговое унаследованное состояние. `inert: true` означает, что порог не применяется; неизвестная возможность также не даёт `enabled: true`. Провайдеры с ключом API, Anthropic и неверные значения отклоняются.
+Управляет порогом пула Codex `openai` или сохраняет порог общего пула OAuth. `on` сохраняет 80 %, `off` — 0 %, а `threshold <n>` принимает 0–100. Порог общего пула влияет на выбор только при включённом `pool.kernel` и `strategy: "fill-first"`; при выключенном флаге сохранение не включает переключение по порогу. В обоих случаях оно не меняет настройку включения провайдера и не отключает ротацию после ошибки 429. Для общего пула результат чтения и изменения берётся из подтверждённого ответа сервера. Для общего пула `poolEnabled` — сохранённая настройка провайдера (`null` означает отсутствие настройки), а не итоговое унаследованное состояние. `inert: true` означает, что порог сохранён, но не применяется, а `inert: false` — что пул его применяет. Отсутствие `inert` означает неизвестную возможность, которая также не даёт `enabled: true`. Провайдеры с ключом API, Anthropic и неверные значения отклоняются.
 
 ```text
 openai: { provider, autoSwitchThreshold: number, enabled: boolean }
-generic OAuth: { provider, autoSwitchThreshold: number | null, enabled: boolean, poolEnabled: boolean | null, inert: true | null }
+generic OAuth: { provider, autoSwitchThreshold: number | null, enabled: boolean, poolEnabled: boolean | null, inert: boolean | null }
 ```
 
 ### `ocx account priority <provider> <account-id|main> [<-100..100|first|earlier|normal|later|last|reset>] [--json]`
@@ -270,6 +273,26 @@ security find-generic-password -w openrouter | ocx account add-key openrouter --
 Проверить reset-credit'ы Codex для аккаунта. Расходование кредита разрушительно и требует сразу
 оба флага: и `--consume`, и `--yes`.
 
+### `ocx account grok-reset-coupons [<account-id>] [--consume --yes [--token-id <id>] [--operation-id <uuid>]] [--json]`
+
+Показывает оставшиеся купоны сброса или обменивает один для аккаунта xAI / Grok.
+
+Без `--consume` команда возвращает доступные токены купонов и окна их действия:
+
+```bash
+ocx account grok-reset-coupons
+ocx account grok-reset-coupons acc_xai_01 --json
+```
+
+Обмен купона сброса изменяет платежное состояние и безвозвратно расходует один токен купона. Для `--consume` строго требуется `--yes`:
+
+```bash
+ocx account grok-reset-coupons --consume --yes
+ocx account grok-reset-coupons --consume --yes --token-id <token-id>
+```
+
+Передайте `--operation-id <uuid>` (должен быть корректным UUIDv4), чтобы гарантировать идемпотентное завершение. При обрыве сети или повторном запуске команды одинаковые идентификаторы операции воспроизводят сохраненный результат вместо расходования второго купона.
+
 ### `ocx account main <subcommand>`
 
 Управлять именованными профилями нативного основного логина Codex, не изменяя маршрутизацию пула аккаунтов OpenCodex.
diff --git a/docs-site/src/content/docs/ru/reference/configuration/agents.md b/docs-site/src/content/docs/ru/reference/configuration/agents.md
index 5f8c0eef35..831f49bcf9 100644
--- a/docs-site/src/content/docs/ru/reference/configuration/agents.md
+++ b/docs-site/src/content/docs/ru/reference/configuration/agents.md
@@ -114,9 +114,9 @@ native ChatGPT-target'ами и прямыми key-auth Responses-маршрут
   "injectionModel": "gpt-5.5",
   "injectionEffort": "high",
   "syncCodexSubagentDefaults": true,
-  "subagentModelFallback": ["gpt-5.4-mini"],
+  "subagentModelFallback": ["gpt-5.6-luna"],
   "subagentModelFallbackByModel": {
-    "gpt-5.5": ["gpt-5.4-mini"]
+    "gpt-5.5": ["gpt-5.6-luna"]
   },
   "subagentModelFallbackPollMs": 60000,
   "subagentEffortCap": "high"
diff --git a/docs-site/src/content/docs/ru/reference/configuration/providers.md b/docs-site/src/content/docs/ru/reference/configuration/providers.md
index 78bca4d40d..9d132b0e94 100644
--- a/docs-site/src/content/docs/ru/reference/configuration/providers.md
+++ b/docs-site/src/content/docs/ru/reference/configuration/providers.md
@@ -37,8 +37,9 @@ ocx models provider openrouter on
 | `codexAccountPickerEnabled?` | `boolean` | выкл. при пустой map | Управляет созданием account-qualified строк picker'а Codex из подходящих сопоставлений `codexAccountNamespaces`. `true` разрешает показывать сопоставленные строки. Если поле не задано при непустой map, функция считается включённой для обратной совместимости; при пустой map она выключена. `false` скрывает созданные строки и возвращает bare native-строки в picker, не удаляя сопоставления и не отключая точную маршрутизацию `<selector>/<native-openai-model>`. |
 | `activeCodexAccountId?` | `string` | — | Вручную выбранный аккаунт Pool для следующего запроса. Выбор очищает thread affinity; in-flight-запросы сохраняют уже захваченные credential'ы. |
 | `codexAccountPriorities?` | `Record<string,number>` | — | Порядок выбора для каждого аккаунта пула Codex: id аккаунта → целое число от `-100` до `100`, **больше — используется раньше**, отсутствие означает `0`. Это граница порядка, а не пригодности: выбор сужает уже подходящие аккаунты до самого высокого уровня, у которого ещё есть запас квоты, а внутри этого уровня аккаунт выбирает `accountPoolStrategy`. Уровень пропускается, только когда все его аккаунты превысили `autoSwitchThreshold`, находятся в cooldown, под soft-avoid, на паузе или требуют повторной аутентификации; неизвестный usage никогда не исчерпывает уровень. Порядок не делает выбираемым непригодный аккаунт и не перепривязывает поток, у которого аккаунт уже есть. Основной аккаунт `__main__` участвует на равных — именно так логин Codex Desktop можно оставить на самый конец. Без записей поведение остаётся прежним. Некорректная map игнорируется с предупреждением в консоли (порядок отключается, восстановление config не запускается). Управляется через `ocx account priority` и страницу Codex Auth. |
-| `autoSwitchThreshold?` | `number` | `80` | Порог проактивного переключения по использованию. `quota` может повторно оценить следующий запрос как привязанной, так и непривязанной задачи; `fill-first` использует его только как точку исчерпания для непривязанных назначений; обычный `round-robin` его не использует. Оценка берёт самое горячее из окон 5 часов, недели и 30 дней. `0` отключает только переключение по использованию, но не назначение непривязанных задач и не восстановление после сбоев. |
-| `accountPoolStrategy?` | `"quota" \| "round-robin" \| "fill-first"` | `"quota"` | Стратегия назначения для новых/непривязанных запросов Codex. Запрос непривязан, если у него нет live affinity `(parent thread id, quota scope)`; видимая существующая задача может стать непривязанной после перезапуска прокси или сброса affinity. `quota` выбирает подходящий аккаунт с наименьшим известным usage, когда активного аккаунта нет, сохраняет подходящий активный аккаунт ниже `autoSwitchThreshold`, а после порога может перевести непривязанный запрос или следующий запрос привязанной задачи на подходящий аккаунт с меньшим usage. `round-robin` равномерно распределяет непривязанные запросы; `fill-first` назначает их активному аккаунту до cooldown, недоступности или порога исчерпания. |
+| `autoSwitchThreshold?` | `number` | `80` | Порог проактивного переключения по использованию. `quota` может повторно оценить следующий непривязанный запрос, а по умолчанию — и привязанную задачу, когда usage пересекает этот порог. При включённом `pool.cacheAffinity` привязанная задача сохраняет аккаунт после порога, пока он не исчерпан и ещё может обслуживать запрос. `fill-first` использует его только как точку исчерпания для непривязанных назначений; обычный `round-robin` его не использует. Оценка берёт самое горячее из окон 5 часов, недели и 30 дней. `0` отключает только переключение по использованию, но не назначение непривязанных задач и не восстановление после сбоев. |
+| `accountPoolStrategy?` | `"quota" \| "round-robin" \| "fill-first"` | `"quota"` | Стратегия назначения для новых/непривязанных запросов Codex. Запрос непривязан, если у него нет live affinity `(parent thread id, quota scope)`; видимая существующая задача может стать непривязанной после перезапуска прокси или сброса affinity. `quota` выбирает подходящий аккаунт с наименьшим известным usage, когда активного аккаунта нет, сохраняет подходящий активный аккаунт ниже `autoSwitchThreshold`, а после порога может перевести непривязанный запрос. Если `pool.cacheAffinity` выключен, следующий запрос привязанной задачи тоже может перейти на подходящий аккаунт с меньшим usage. Если флаг включён, привязанная задача остаётся, пока аккаунт не исчерпан (известный usage 100%) или не может обслуживать запрос. `round-robin` равномерно распределяет непривязанные запросы; `fill-first` назначает их активному аккаунту до cooldown, недоступности или порога исчерпания. |
+| `pool.cacheAffinity?` | `boolean` | `false` | Опциональный порядок cache-affinity для привязанных потоков Codex, независимый от `pool.kernel`. По умолчанию выключен; некорректное значение читается как выключенное. Когда флаг включён, живая привязка важнее запаса квоты: `quota` не переносит поток только потому, что usage пересёк `autoSwitchThreshold`. Поток всё равно уходит, если аккаунт не может обслуживать запрос — на паузе, непригоден или реально исчерпан (известный usage 100%). Affinity меняет порядок, а не закрепляет учётные данные. |
 | `accountPoolStickyLimit?` | `number` | `1` | Число назначений новых/непривязанных задач на одном выборе round-robin перед переходом дальше. Счётчик растёт при привязке задачи, а не после успеха upstream. Диапазон 1–100; только при `accountPoolStrategy` = `round-robin`. |
 | `upstreamFailoverThreshold?` | `number` | `3` | Сколько подряд transient failure допустить, прежде чем новые сессии начнут делать failover. `0` отключает эту логику. Для обычных Responses-запросов и нативных compact-отправок доказанные ошибки доступности DNS/TCP до соединения учитываются на уровне пары «провайдер, хост» и не влияют на здоровье аккаунта, кулдауны аккаунта, привязку потока/сессии, выбор активного аккаунта или маршрутизацию пула, а также не учитываются в этом пороге. |
 | `upstreamHostCircuitThreshold?` | `number` | `0` | Опциональный порог circuit breaker для доказанных DNS/TCP-сбоев до соединения в нативных OpenAI forward Responses- и compact-отправках. `0` отключает его; `1`–`20` открывает 30-секундный cooldown для provider-origin после такого числа завершившихся логических запросов. Пока circuit открыт, до выбора аккаунта и upstream-отправки возвращается `503` с `Retry-After`; после cooldown допускается один half-open запрос. Таймауты и HTTP-ответы не учитываются, а любой HTTP-ответ закрывает circuit. Применяется только к маршрутизации Codex Pool без закреплённого аккаунта; при `codexAccountMode: "direct"` и для селекторов с указанием аккаунта схема не активна. |
@@ -135,6 +136,7 @@ cross-route credential fallback не существует. Строки API GPT-
 | `noTopPModels?` | `string[]` | Модели, отвергающие переданный вызывающей стороной `top_p`. |
 | `noPenaltyModels?` | `string[]` | Модели, отвергающие penalty presence/frequency. |
 | `noStructuredOutputModels?` | `string[]` | Точные идентификаторы моделей, чей endpoint `openai-chat` отклоняет `response_format`. Поле опускается только при точном совпадении запрошенной модели; для остальных моделей `openai-chat` преобразование structured output остаётся включённым. |
+| `noJsonSchemaModels?` | `string[]` | Точные идентификаторы моделей, чей endpoint `openai-chat` отклоняет `response_format` типа `json_schema`, но принимает `json_object`. Такой запрос понижается до `json_object`, а не отбрасывается, поэтому вызывающая сторона всё равно получает JSON. Если модель есть в обоих списках, побеждает `noStructuredOutputModels`. Пресеты `opencode go`, `opencode zen` и `opencode free` включают это для своих маршрутов DeepSeek. |
 | `parallelToolCalls?` | `boolean` | Переключатель parallel tool call'ов. Для OpenAI Chat по умолчанию включено; не-chat adapter'ы рекламируют это только при явном `true`. |
 | `responsesItemIdRepair?` | `{ message?: string[]; reasoning?: string[]; repairMissingTerminalIds?: boolean; repairInvalidIds?: boolean }` | По умолчанию выключенная downstream SSE-repair для exact placeholder-id, отсутствующих terminal-id и (с `repairInvalidIds`) message/reasoning id без канонического префикса `msg_`/`rs_`. Function-call id никогда не переписываются. Встроенный DeepSeek включает последние два по умолчанию. |
 | `responsesSnapshotRepair?` | `boolean` | По умолчанию выключенная клиентская repair для неполных lifecycle snapshot'ов Responses в SSE и JSON. Добавляет отсутствующие status, output и tool metadata, не меняя raw inspection и persistence. |
@@ -190,8 +192,9 @@ redirect'ов для обычных provider-request'ов реализована
 Конфигурация хранит только несекретные метаданные аккаунтов; access- и refresh-токены хранятся в
 защищённом хранилище учётных данных аккаунтов Codex. Pool routing разделяет назначение
 новых/непривязанных задач, проактивное переключение по использованию и восстановление после сбоев.
-Привязанная задача обычно сохраняет affinity, но `quota` может перепривязать её при следующем
-запросе после превышения порога; pause, cooldown, повторная аутентификация и обработка сбоев также
+Привязанная задача обычно сохраняет affinity. По умолчанию `quota` может перепривязать её при следующем
+запросе после превышения порога; при включённом `pool.cacheAffinity` эта перепривязка ждёт, пока
+привязанный аккаунт не будет исчерпан или не сможет обслуживать запрос. Pause, cooldown, повторная аутентификация и обработка сбоев также
 могут независимо очистить или изменить routing. Непривязанным может стать и существующая задача
 после перезапуска прокси или сброса affinity. Отказ **429/402** до вывода допускает одну попытку
 на подходящем альтернативном аккаунте даже при выключенном переключении по использованию.
@@ -208,7 +211,7 @@ redirect'ов для обычных provider-request'ов реализована
 после чего запрос может перейти на другой подходящий аккаунт Pool. Эти переходы восстановления
 остаются активными при `autoSwitchThreshold: 0`; значение `0` отключает только проактивное переключение по использованию.
 
-**Стратегии назначения и проактивного переключения:** `quota` выбирает подходящий аккаунт с наименьшим usage, когда активного аккаунта нет, сохраняет подходящий активный аккаунт ниже `autoSwitchThreshold`, а после порога может перевести непривязанный запрос или следующий запрос привязанной задачи на подходящий аккаунт с меньшим usage. `round-robin` равномерно распределяет непривязанные запросы, а порог не
+**Стратегии назначения и проактивного переключения:** `quota` выбирает подходящий аккаунт с наименьшим usage, когда активного аккаунта нет, сохраняет подходящий активный аккаунт ниже `autoSwitchThreshold`, а после порога может перевести непривязанный запрос. Если `pool.cacheAffinity` выключен, следующий запрос привязанной задачи тоже может перейти на подходящий аккаунт с меньшим usage. Если флаг включён, cache affinity важнее запаса квоты, и привязанная задача остаётся, пока аккаунт не исчерпан (известный usage 100%) или не может обслуживать запрос. `round-robin` равномерно распределяет непривязанные запросы, а порог не
 меняет обычную ротацию. `accountPoolStickyLimit` (по умолчанию `1`, 1–100) считает назначения/bind,
 а не успешные ответы. `fill-first` назначает непривязанные запросы активному аккаунту до cooldown,
 reauth или порога исчерпания; здоровые привязанные задачи сохраняют affinity. Эти стратегии не
@@ -259,7 +262,7 @@ backoff и может переключить аккаунт уже внутри
 | `failureBackoffMaxSeconds?` | `number` | `3600` | Верхний предел backoff'а и задержки после permanent-failure. |
 | `codexWarmupEnabled?` | `boolean` | `false` | Включить synthetic validation для аккаунтов пула Codex. |
 | `codexWarmupMaxAgeSeconds?` | `number` | `691200` | Повторно валидировать аккаунт через 8 дней. |
-| `codexWarmupModel?` | `string` | `gpt-5.4-mini` | Нативная модель, используемая для необязательного warmup'а. |
+| `codexWarmupModel?` | `string` | `gpt-5.6-luna` | Нативная модель, используемая для необязательного warmup'а. |
 
 ## Фиксированные endpoint'ы провайдеров
 
@@ -532,7 +535,7 @@ Pool/Direct рекламирует `922000`; синхронизированны
       "baseUrl": "https://ollama.com/v1",
       "apiKey": "${OLLAMA_API_KEY}",
       "defaultModel": "glm-5.2",
-      "noVisionModels": ["glm-5.2", "gpt-oss", "qwen3-coder", "deepseek-v4-pro"]
+      "noVisionModels": ["glm-5.2", "gpt-oss", "qwen3-coder", "deepseek-v4-flash"]
     }
   },
   "subagentModels": ["anthropic/claude-opus-5", "ollama-cloud/glm-5.2"],
diff --git a/docs-site/src/content/docs/ru/reference/configuration/server.md b/docs-site/src/content/docs/ru/reference/configuration/server.md
index f8bc9f2a25..84b3caf183 100644
--- a/docs-site/src/content/docs/ru/reference/configuration/server.md
+++ b/docs-site/src/content/docs/ru/reference/configuration/server.md
@@ -193,7 +193,7 @@ routed-model и hosted-search timeout. Эффективный watchdog мост
 | --- | --- | --- | --- |
 | `enabled?` | `boolean` | on when usable | Главный переключатель описания изображений. |
 | `backend?` | `"openai" \| "anthropic"` | auto | Явное значение имеет приоритет; если оно не задано, предпочтение отдаётся пригодным сохранённым учётным данным Anthropic OAuth, иначе используется `openai`. |
-| `model?` | `string` | backend-dependent | `gpt-5.4-mini` для OpenAI или `claude-sonnet-5` для Anthropic. |
+| `model?` | `string` | backend-dependent | `gpt-5.6-luna` для OpenAI или `claude-sonnet-5` для Anthropic. |
 | `reasoning?` | `"low" \| "medium" \| "high" \| "xhigh" \| "max"` | `"low"` | Уровень рассуждений OpenAI Responses. Anthropic его игнорирует. |
 | `maxDescriptionsPerTurn?` | `number` | `8` | Максимум новых промахов description-cache за один main turn. `0` отключает вызовы; некорректные значения возвращают дефолт. |
 | `timeoutMs?` | `number` | `45000` | Таймаут запроса sidecar'а. Целое число 1–2147483647. |
diff --git a/docs-site/src/content/docs/ru/reference/management-api.md b/docs-site/src/content/docs/ru/reference/management-api.md
index aefc4e09cf..e91a12222a 100644
--- a/docs-site/src/content/docs/ru/reference/management-api.md
+++ b/docs-site/src/content/docs/ru/reference/management-api.md
@@ -79,11 +79,21 @@ GUI-сессия в стиле loopback не выпускается.
 | `GET /api/grok` | Прочитать статус управляемой конфигурации Grok и кандидатные модели | 400 status read failure |
 | `PUT /api/grok/selection` | Сохранить список исключённых моделей Grok | 400 invalid or oversized selection |
 | `POST /api/grok/apply` | Применить сохранённую конфигурацию Grok через managed sync | 409 `grok_apply_busy`; 400/500 apply failure |
+| `GET /api/grok/reset-coupons?accountId=...` | Прочитать оставшиеся токены сброса биллинга Grok и окна их действия для активного или указанного аккаунта xAI | 400 отсутствует аккаунт; 401 без аутентификации; 502 ошибка upstream gRPC-Web |
+| `POST /api/grok/reset-coupons/consume` | Обменять подходящий купон сброса. Тело `{ accountId?, tokenId?, operationId? }`. Необязательный `operationId` (UUIDv4) делает обмен идемпотентным: повтор того же идентификатора воспроизводит сохраненный результат без повторного обмена. | 400 некорректные JSON/UUID; 401 без аутентификации; 409 `identity_mismatch`; 502 ошибка upstream; 503 емкость реестра |
 | `GET, PUT /api/claude-desktop` | Прочитать или сохранить routed/native-профиль Claude Desktop | 400 invalid or unavailable assignment |
 | `POST /api/claude-desktop/apply` | Записать сохранённый профиль в managed config Claude Desktop | 400/500 write failure |
 | `GET /api/claude-desktop/status` | Проверить согласованность saved-vs-applied profile и здоровье Desktop | 400 status read failure |
 | `GET, PUT /api/claude-code` | Прочитать или обновить настройки gateway, auth-mode, model-map, context, agent и sidecar для Claude Code | 400 invalid field or shape |
 
+Дашборд управляет обоими путями купонов из **Providers > xAI Grok > Accounts**: каждая
+строка вошедшего аккаунта несёт значок-билет с числом оставшихся купонов, а значок
+открывает диалог, который показывает окна действия и обменивает купон, ближайший
+к истечению срока. Диалог отправляет сгенерированный клиентом `operationId` и после
+таймаута прекращает отправку вместо повторной попытки, потому что обмен, запись
+журнала которого ещё открыта, выполнился бы снова. `ocx account grok-reset-coupons`
+остаётся эквивалентом в терминале.
+
 О принципах model roster и поведении encrypted worker-task см.
 [Поверхность подагентов](/guides/sub-agent-surface/).
 
@@ -190,7 +200,8 @@ Endpoint'ы storage cleanup могут перемещать или навсег
 | `POST /api/oauth/logout` | Удалить сохранённый credential выбранного провайдера | 400 unknown provider; `oauth_mutation_busy` |
 | `GET, DELETE /api/oauth/accounts` | Показать список masked-аккаунтов или удалить один аккаунт | 400 invalid provider/id; 404 account missing; `oauth_mutation_busy` |
 | `PUT /api/oauth/accounts/active` | Выбрать активный OAuth-аккаунт | 400 invalid provider/account; `oauth_mutation_busy` |
-| `GET, PUT, PATCH /api/oauth/accounts/pool` | Прочитать или обновить policy Anthropic OAuth pool | 400 non-Anthropic provider or invalid policy |
+| `GET, PUT, PATCH /api/pool/settings` | Прочитать или обновить policy пула любого вида (codex, anthropic, generic); все три отвечают одинаковыми ключами, а поля, которые вид действительно применяет, перечислены в `supported` | 400 неизвестный provider, поле, которое вид не поддерживает, или недопустимое значение |
+| `GET, PUT, PATCH /api/oauth/accounts/pool` | Прежняя policy пула для Anthropic и обычных OAuth-провайдеров; заменена на `/api/pool/settings` и сохранена для существующих клиентов | 400 codex или api-key provider, либо недопустимая policy |
 | `POST /api/oauth/accounts/clear-cooldown` | Очистить runtime cooldown одного OAuth-аккаунта | 400 invalid provider/account |
 | `PUT /api/oauth/accounts/alias` | Задать или очистить alias OAuth-аккаунта | 400 invalid provider/account/alias |
 | `GET, POST, DELETE /api/providers/keys` | Показать список masked provider-key'ов, добавить/активировать один или удалить один | 400 invalid input; 404 provider/key missing |
diff --git a/docs-site/src/content/docs/ru/reference/proxy-formats.md b/docs-site/src/content/docs/ru/reference/proxy-formats.md
index d87a28c08f..04934d0c50 100644
--- a/docs-site/src/content/docs/ru/reference/proxy-formats.md
+++ b/docs-site/src/content/docs/ru/reference/proxy-formats.md
@@ -316,6 +316,8 @@ conversation.
 
 Маршрут Cursor без ключа и без OAuth может использовать отдельный bearer вызывающей стороны, но не секрет прокси и не автоматически добавленную аутентификацию ChatGPT main. Выбор Combo/policy и фактические изменения маршрута shadow/thread-spawn не передают исходные учётные данные вызывающей стороны новым целям. Каноническая маршрутизация OpenAI может восстановить единственный bearer вызывающей стороны, не являющийся ключом прокси, после внутреннего изменения маршрута только если его JWT содержит claim учётной записи ChatGPT и любой явно указанный заголовок учётной записи соответствует этому claim. Для передачи аутентификации вызывающей стороны в необязательные sidecar OpenAI необходимы один JWT и явно указанный соответствующий `chatgpt-account-id`. Непрозрачные bearer не восстанавливаются после изменения маршрута даже при наличии явно указанного заголовка учётной записи. В остальных случаях конечной цели нужны собственные настроенные, OAuth или сохранённые учётные данные; иначе запрос завершается локальной ошибкой. Один маркер thread-spawn без изменения маршрута не удаляет учётные данные.
 
+Для Chat-запроса к Cursor без настроенного ключа необязательное дополнение сохранённой аутентификацией main откладывается до фактического планирования помощника OpenAI с доступным каноническим кандидатом Direct. Независимый запрос Cursor не удерживает native main через этот механизм и не задерживает смену профиля. Учётные данные помощника подчиняются ограничениям запуска и смены профиля и остаются отдельно от bearer Cursor. Помощники Pool и помощники с явно указанным аккаунтом сохраняют прежний выбор аккаунта.
+
 Claude replay сохраняет аутентификацию main только в снимке в памяти, владение которым обеспечено текущим turn, и восстанавливает её только для конечного канонического маршрута ChatGPT.
 
 :::caution
diff --git a/docs-site/src/content/docs/tr/getting-started/quickstart.md b/docs-site/src/content/docs/tr/getting-started/quickstart.md
index 0ae770231f..dfff3c6104 100644
--- a/docs-site/src/content/docs/tr/getting-started/quickstart.md
+++ b/docs-site/src/content/docs/tr/getting-started/quickstart.md
@@ -84,7 +84,7 @@ codex -m "ollama-cloud/glm-5.2"      "Bir SQL geçişi yaz"
 ## Alt ajan modellerini seçin (isteğe bağlı)
 
 Yeni bir yapılandırma, Codex'in alt ajan seçicisinde beş yerel model sunar:
-`gpt-5.5`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` ve `gpt-5.4-mini`. En
+`gpt-5.5`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` ve `gpt-6-astra`. En
 fazla beş yerel veya yönlendirilmiş modeli değiştirmek veya yeniden sıralamak
 için `ocx gui`'yi açın. Kontrol paneli ayrıca tercih edilen bir alt ajan
 modelini ve akıl yürütme çabasını ayarlayabilir. v1/base/v2 seçmek ve rehberlik,
diff --git a/docs-site/src/content/docs/tr/guides/claude-code.md b/docs-site/src/content/docs/tr/guides/claude-code.md
index 497f5e635b..f4846148f3 100644
--- a/docs-site/src/content/docs/tr/guides/claude-code.md
+++ b/docs-site/src/content/docs/tr/guides/claude-code.md
@@ -732,3 +732,5 @@ modellerde opencodex varsayılan olarak bunu taslakla değiştirir (`blockedSkil
 aracının `model` argümanını değil, `<!-- ocx-route: ... -->` yönergelerini
 kullanır. Yönergenin hedeflenen rotayla eşleştiğinden emin olun. Model yer
 tutucusu olarak `"haiku"` iletin.
+
+`config.json` içindeki `claudeCode.stabilizePromptCache: true`, dönüştürülen rotalarda sistem talimatlarının sonundaki desteklenen Claude bildirimlerini son kullanıcı mesajına taşır. Varsayılan değer `false` olur. Yalnızca bu rol değişikliği istemcileriniz için uygunsa etkinleştirin. Kod bloklarındaki örnekler ve eşleşmeyen metin korunur; yerel Anthropic aktarımı değişmez. Meta veri yoksa önbellek anahtarı kararlı talimatlardan hesaplanır. Bu seçenek konuşma kimliği oluşturmaz veya üst hizmette önbellek isabeti garanti etmez.
diff --git a/docs-site/src/content/docs/tr/guides/codex-app-models.md b/docs-site/src/content/docs/tr/guides/codex-app-models.md
index 2ddd5bd63a..d26343e9eb 100644
--- a/docs-site/src/content/docs/tr/guides/codex-app-models.md
+++ b/docs-site/src/content/docs/tr/guides/codex-app-models.md
@@ -144,8 +144,8 @@ yerel yetenekleri kaldırır.
 
 ## Mevcut kararlı model kapsamı
 
-Yerel geri dönüş kümesi `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`,
-`gpt-5.3-codex-spark` ve GPT-5.6 Sol/Terra/Luna modellerini içerir. GPT-5.5/5.4
+Yerel geri dönüş kümesi `gpt-5.5`,
+`gpt-5.3-codex-spark` ve GPT-5.6 Sol/Terra/Luna modellerini içerir. GPT-5.5
 ailesi için opencodex, kurulu Codex kataloğunun daha zengin canlı girdilerini
 korur ve yalnızca eksik bir girdiyi sentezler. Paketlenmiş yukarı akış anlık
 görüntüsü yalnızca eski şablon yaklaşımı yerine gerçek model başına kimliği ve
diff --git a/docs-site/src/content/docs/tr/guides/codex-integration.md b/docs-site/src/content/docs/tr/guides/codex-integration.md
index 23b9b87f2e..a601a524c6 100644
--- a/docs-site/src/content/docs/tr/guides/codex-integration.md
+++ b/docs-site/src/content/docs/tr/guides/codex-integration.md
@@ -425,7 +425,7 @@ Arayüzü](/tr/guides/sub-agent-surface/) sayfasına bakın.
 
 ## Codex hesap ısınması
 
-Hesap ekleme veya yeniden kimlik doğrulama, normalde kaydetmeden önce `response.completed` bekleyen küçük bir model isteğiyle doğrulanır. Varsayılan model `gpt-5.4-mini` olup HTTP 400 veya HTTP 404 durumunda `gpt-5.5` ve `gpt-5.6-luna` denenir. Genel hatalar ham yanıt gövdesi yerine sabit hata kategorilerini içerir.
+Hesap ekleme veya yeniden kimlik doğrulama, normalde kaydetmeden önce `response.completed` bekleyen küçük bir model isteğiyle doğrulanır. Varsayılan model `gpt-5.6-luna` olup HTTP 400 veya HTTP 404 durumunda `gpt-5.5` denenir. Genel hatalar ham yanıt gövdesi yerine sabit hata kategorilerini içerir.
 
 Yeni OAuth belirteciyle yapılan kota sorgusu 5 saatlik, haftalık veya aylık kotanın tükendiğini doğrularsa hesap model çağrısı olmadan kaydedilir ve **Doğrulama bekleniyor** gösterilir. Yeniden başlatma veya belirteç yenileme yönlendirmeyi açmaz. Kota geri geldiğinde kotaları yenileyin: kullanılabilir kapasite gösteren eksiksiz güncel veri küçük bir doğrulama isteğine izin verir. Yalnızca tamamlanan yanıt hesabı etkinleştirir. Hatalarda kısıtlama korunur. Pasif sorgulama bu isteği göndermez. İlk kayıtta bilinmeyen kota normal doğrulamayı gerektirir.
 
@@ -447,7 +447,7 @@ Tamamlanmayan bir ana hesap yenilemesi, yeniden denemede başarılı olabileceğ
 ocx config set codexPool '{"excludedPlans":["free"]}'
 ```
 
-Bu bir engelleme değil, seçim politikasıdır. Dışarıda bırakılan hesap kimlik bilgisini, kota geçmişini ve iş parçacığı bağını korur, hesap listesinde görünmeye devam eder ve `work/gpt-5.4` gibi açık bir seçimle hâlâ erişilebilir. Değişen tek şey, otomatik rotasyonun onu artık seçmemesidir; hesap zaten etkin olsa ya da bir iş parçacığına bağlı olsa bile. Süresi dolan bir abonelik tam olarak bu durumu bırakır.
+Bu bir engelleme değil, seçim politikasıdır. Dışarıda bırakılan hesap kimlik bilgisini, kota geçmişini ve iş parçacığı bağını korur, hesap listesinde görünmeye devam eder ve `work/gpt-5.5` gibi açık bir seçimle hâlâ erişilebilir. Değişen tek şey, otomatik rotasyonun onu artık seçmemesidir; hesap zaten etkin olsa ya da bir iş parçacığına bağlı olsa bile. Süresi dolan bir abonelik tam olarak bu durumu bırakır.
 
 İki kasıtlı sınır var. Ana Codex hesabı plana göre hiçbir zaman dışarıda bırakılmaz: yalnızca-seçim yönlendirmesi korunan yerel kimlik bilgisini okumamak için planını saklar, dolayısıyla ana hesabı kapsayan bir kural kendisiyle çelişirdi. Ayrıca dışarıda bırakılmamış hiçbir hesap kalmadığında, dışarıda bırakılan hesap başarısız olmak yerine yine yanıt verir; hizmeti tamamen durdurmak için hâlâ tüm hesapları duraklatmak gerekir. `minimumPlan` karşılığı yoktur, çünkü ChatGPT planlarını sıralamak burada bulunmayan bir tam sıralama gerektirir.
 
@@ -467,3 +467,9 @@ opencodex yönetilen bir [arka plan servisi](/tr/reference/cli/#ocx-service)
 olarak çalıştığında `OCX_SERVICE=1` ayarlar, böylece servis odaklı bir yeniden
 başlatma Codex yapılandırmasını **bozmaz** — yalnızca açık bir `ocx stop` / `ocx
 service stop` yerel Codex'i geri yükler.
+
+## Sayfalanmış geçmiş için güvenlik reddi
+
+Etkilenen geçmiş deposu sayfalamayı destekliyorsa sağlayıcı değişimi `history_paginated_requires_native_writer` döndürebilir; legacy satırlar da buna dahildir. OpenCodex, Codex dışında sıra numarası atamak yerine yapılandırmayı, profili, kataloğu, geçmişi ve geri yükleme kanıtlarını korur. Harici sağlayıcıyı korumak gibi değişim yapmayan yollar kullanılabilir.
+
+Konuşmanın kullandığı sağlayıcı tanımını silmeyin, `ocx sync` veya legacy kurtarmayı tekrarlamayın ve etkin geçmişi yeniden yazmayın. Dosyaları koruyun, kurtarmadan önce konuşmayı kapatın ve özel geçmişi yayımlamadan tam hatayı ve sürümleri bildirin. Yerel yazıcıyla koordineli, doğrulanmış bir düzeltme gerekir. Yedek veya başarılı betik görüntünün düzeldiğini kanıtlamaz; Codex’i yeniden açıp konuşmayı kontrol edin.
diff --git a/docs-site/src/content/docs/tr/guides/combos.md b/docs-site/src/content/docs/tr/guides/combos.md
index 8b67170068..b8cd5bad0d 100644
--- a/docs-site/src/content/docs/tr/guides/combos.md
+++ b/docs-site/src/content/docs/tr/guides/combos.md
@@ -218,6 +218,8 @@ kullanılır. Güncel kota verisi bulunmayan hedeflerde ve eşitliklerde
 yapılandırma sırası korunur. `weight` değerleri ve `stickyLimit` bu stratejiyi
 etkilemez.
 
+Bu sıralama ve gönderim öncesi sağlayıcı elemesi, mevcut tek API anahtarının model çıkarımı kullanımının tamamına uygulanan güncel sınırlara dayanır. OAuth veya geçerli hesap özetleri, çağıranın kimlik bilgilerini ileten rotalar, birden fazla anahtar ve kimlik bilgileri ya da hedefi değişmiş anlık görüntüler, bu ön kararda yalnızca görüntüleme amaçlıdır. `Authorization`, `x-api-key` veya `x-goog-api-key` başlıkları kimlik bilgilerini geçersiz kıldığında da aynı kural uygulanır; yalnızca arama veya MCP için olan pencereler hariç tutulur. Uygun hedeflerin hiçbirinde geçerli sıfırlama bilgisi yoksa yapılandırma sırası kullanılır. Hesap seçimi ve yeniden denemelerde normal sınırlar uygulanmaya devam eder.
+
 ## Bir hedef başarısız olduğunda ne olur?
 
 Kombo hataları **atlama (hop)** hataları ve **uç (terminal)** hatalar olarak
@@ -310,9 +312,7 @@ hedef seçicisi ise devre dışı bırakılmış modelleri ve iç içe geçmiş
 hariç tutar.
 
 Her hedef ayrıca canlı bir kota rozeti gösterir: **Kullanılabilir**, **Kota tükendi** veya **Kota bilinmiyor**.
-Kaydet ve Oluştur yalnızca etkin hedeflerin tamamı için kotanın tükendiğini gösteren güncel ve eksiksiz kanıt varsa
-devre dışı bırakılır. Eksik, eski, bozuk veya tamamlanmamış toplu kanıt bilinmiyor olarak kalır ve denetimleri asla
-kilitlemez. Kota yenilendiğinde işlem otomatik olarak yeniden etkinleşir.
+Düzenleyici, kota nedeniyle Kaydet ve Oluştur işlemlerini yalnızca kullanılabilir hedeflerin tümü için yapılandırılmış kimlik bilgisine ait çıkarım sınırının tükendiğini doğrulayan geçerli sunucu bilgisi varsa engeller. Yalnızca görüntüleme amaçlı hesap, model, arama ve MCP kotaları ya da eksik veya süresi dolmuş yönlendirme kanıtları bu engellemeye neden olmaz. Engelleme, ilgili sıfırlama zamanında veya verinin güncellik süresi dolduğunda sona erer ve sayfa etkin ya da görünür olduğunda yeniden kontrol edilir; Yenile, hem kombo verilerini hem de kotaları yeniden yükler.
 
 ### CLI
 
@@ -409,4 +409,3 @@ Hata hedefe özgü olmaktan ziyade uç (terminal) bir hataydı. Geçersiz girdiy
 düzeltin, aşırı büyük bir bağlamı azaltın, bir politika reddini işleyin veya
 reddedilen istek kaynağını düzeltin. Kombolar bu durumlar için atlama yapmaz.
 
-
diff --git a/docs-site/src/content/docs/tr/guides/integrations.md b/docs-site/src/content/docs/tr/guides/integrations.md
index f068b0233f..62ec067bb2 100644
--- a/docs-site/src/content/docs/tr/guides/integrations.md
+++ b/docs-site/src/content/docs/tr/guides/integrations.md
@@ -1,10 +1,10 @@
 ---
 title: Entegrasyonlar
-description: Kontrol panelinden OpenCode, Pi, OMP, Hermes, OpenClaw, Kimi Code, Gajae Code, DeepSeek Harness, MiniMax Code, ZCode, Prime Agent, Aside ve Raycast'i opencodex'e bağlayın — istemci başına tek bir anahtar ve her yazmadan önce alınan bir yedek.
+description: Kontrol panelinden OpenCode, Pi, OMP, Hermes, OpenClaw, Kimi Code, gjc, DeepSeek Harness, MiniMax Code, ZCode, Prime Agent, Aside, Raycast ve omo'yu opencodex'e bağlayın — istemci başına tek bir anahtar ve her yazmadan önce alınan bir yedek.
 ---
 
 **Entegrasyonlar** sekmesi, opencodex'in sağlayıcı bloğunu istemcinin kendi
-yapılandırma dosyasına yazar ve tekrar kaldırır. On üç istemci bu şekilde
+yapılandırma dosyasına yazar ve tekrar kaldırır. On beş istemci bu şekilde
 çalışır, her biri bir anahtarla:
 
 | İstemci | Yapılandırma dosyası | Format | Değişiklik ne zaman geçerli olur? | Kimlik bilgisi |
@@ -15,13 +15,15 @@ yapılandırma dosyasına yazar ve tekrar kaldırır. On üç istemci bu şekild
 | Hermes | `~/.hermes/config.yaml` | YAML | yeni oturumlarda | `OPENCODEX_HERMES_API_KEY` |
 | OpenClaw | `~/.openclaw/openclaw.json` | JSON5 | hemen, çalışan bir ağ geçidinde | `OPENCODEX_OPENCLAW_API_KEY` |
 | Kimi Code | `~/.kimi-code/config.toml` | TOML | yeniden başlatmada veya `/reload` ile | geri döngü (loopback) yer tutucusu |
-| Gajae Code | `~/.gjc/agent/models.yml` | YAML | yeni oturumlarda veya `/model` açtığınızda | `OPENCODEX_GAJAE_API_KEY` |
+| gjc | `~/.gjc/agent/models.yml` | YAML | yeni oturumlarda veya `/model` açtığınızda | `OPENCODEX_GAJAE_API_KEY` |
 | DeepSeek Harness (DSH) | `$DSH_HOME/settings.yaml` (varsayılan `~/.dsh/settings.yaml`) | YAML | çalışırken yeniden yükleme | gizli olmayan geri döngü bearer yer tutucusu |
 | MiniMax Code | `~/.minimax/config.yaml` | YAML | yeni oturumlarda veya model seçici açıldıktan sonra | geri döngü (loopback) yer tutucusu |
 | Prime Agent | `~/.prime/agent/models.json` | JSON | yeni oturumlarda | geri döngü yer tutucusu |
 | ZCode | `~/.zcode/v2/config.json` | JSON | yeniden başlatmada | geri döngü yer tutucusu |
 | Aside | `~/.aside/u/<account>/models.json` | JSON | Aside tamamen kapatılıp yeniden açıldıktan sonra | geri döngü yer tutucusu |
 | Raycast | `~/.config/raycast/ai/providers.yaml` | YAML | kaydedildiği anda — Raycast dosyayı izler | yok — yalnızca geri döngü |
+| omo | `~/.omo/agent/models.json` | JSON | yeni oturumlarda | geri döngü yer tutucusu |
+| Cline CLI | `~/.cline/data/settings/providers.json` + `models.json` | JSON | kapatıp yeniden başlattıktan sonra | yalnızca loopback |
 
 Yönetilen DSH desteğinin en düşük uyumlu sürümü **DSH 0.1.0-rc.6**'dır. OpenCodex yalnızca
 `llm-pi-ai.providers.opencodex` bölümünü yönetir: Uygula ve Yenile bu bölümü değiştirir, Devre Dışı
@@ -149,7 +151,7 @@ hiçbir şey sessizce değiştirilmez veya düşürülmez. **OMP** de yanındaki
 düzenlemelerden etkilenmez, ama başka bir nedenle: writer'ı yalnızca kendi
 `providers.opencodex` aralığını bayt bayt yamalar, dosyanın geri kalanı hiçbir
 zaman yeniden yazılmaz. Yorum taşıyabilen diğer biçimlerde (Hermes, OpenClaw,
-Kimi Code, Gajae Code, MiniMax Code, Raycast — bütün belge olarak yazılan YAML, JSON5 ve TOML) veya
+Kimi Code, gjc, MiniMax Code, Raycast — bütün belge olarak yazılan YAML, JSON5 ve TOML) veya
 kendi girdilerimiz düzenlenmişse, anahtar kilitlenir ve hangi düzenlemelerin
 size ait olduğunu tahmin etmek yerine devre dışı bırakmayı reddeder.
 
@@ -178,7 +180,7 @@ diziler ve satır içi tablolar dahil bu türlenmiş değerleri tırnaklı metne
 Zaten tırnak içinde yazılmış tarihler desteklenir. Tırnaksız tarih türünü korumak
 için yapılandırmayı elle düzenleyin.
 
-**Pi, Kimi Code, Gajae Code, MiniMax Code ve yönetilen DSH entegrasyonu yalnızca geri döngü (loopback) bağlantısına karşı
+**Pi, Kimi Code, gjc, MiniMax Code ve yönetilen DSH entegrasyonu yalnızca geri döngü (loopback) bağlantısına karşı
 çalışır.** İlk dördünün yapılandırmasında geri döngü olmayan bir bağlantının gerektirdiği
 `x-opencodex-api-key` başlığı için alan yoktur. DSH genel bir headers haritası sunar, ancak rc.6
 bu özel kabul başlığını desteklenen bir entegrasyon sözleşmesi olarak belgelememektedir; bu nedenle
@@ -229,10 +231,10 @@ ocx integration client enable --client mcode
 ocx mcode
 ```
 
-Bağlandıktan sonra `ocx sync` ve `POST /api/sync`, yönetilen MCode, Pi, Aside ve
-Raycast kataloglarını yeniler. Proxy başlangıcı da yönetilen Raycast kataloğunu
-yeniler. Model görünürlüğü, sağlayıcı veya ön ayar değişiklikleri Pi, Aside ve
-Raycast kataloglarını günceller. Eksik, dışarıdan düzenlenmiş, güvenli olmayan
+Bağlandıktan sonra `ocx sync` ve `POST /api/sync`, yönetilen MCode, Pi, Aside,
+Raycast ve omo kataloglarını yeniler. Proxy başlangıcı da yönetilen Raycast
+kataloğunu yeniler. Model görünürlüğü, sağlayıcı veya ön ayar değişiklikleri Pi,
+Aside, Raycast ve omo kataloglarını günceller. Eksik, dışarıdan düzenlenmiş, güvenli olmayan
 veya elle kaldırılmış bloklara dokunmaz; yeniden bağlamak istediğinizde
 entegrasyonu açıkça etkinleştirin.
 
@@ -260,3 +262,15 @@ değiştiyse, komut reddeder ve size bildirir; çünkü daha yeni düzenlemeleri
 doğrulanmıştır; neyin ne zaman denetlendiğine ilişkin
 `devlog/_fin/260802_client_toggle_api/002_client_toggle_matrix.md` içindeki
 araştırma notlarına bakın.
+
+## Cline CLI
+
+Cline CLI providers.json ve models.json kullanır. Değişiklik veya eşitleme öncesinde Cline’ı kapatın, sonra yeniden başlatın. Geri al iki özgün dosyayı geri yükler. Varsayılan sağlayıcı değişmez. Eski VS Code uzantısının depolaması taşınmaz.
+
+```bash
+ocx integration client enable --client cline
+ocx integration client history --client cline
+ocx integration client restore --op <operation-id>
+```
+
+[CLI / rollback / CLINE_PROVIDER_SETTINGS_PATH](/guides/integrations/#cline-cli).
diff --git a/docs-site/src/content/docs/tr/guides/providers.md b/docs-site/src/content/docs/tr/guides/providers.md
index fde08cd29e..36e0ccbc1d 100644
--- a/docs-site/src/content/docs/tr/guides/providers.md
+++ b/docs-site/src/content/docs/tr/guides/providers.md
@@ -110,8 +110,10 @@ GPT-5.6 Sol/Terra/Luna slug'larını (`gpt-5.6-sol`, `gpt-5.6-terra`,
 Sekiz sağlayıcı önayarı OAuth girişini kullanır — artı deneysel resmi olmayan
 bir cihaz akışı köprüsü aracılığıyla GitHub Copilot. opencodex bunların kimlik
 bilgilerini `~/.opencodex/auth.json` içinde saklar ve otomatik olarak yeniler.
-`chatgpt` ayrıca oturum açma CLI'sı tarafından kabul edilir; bir `forward` modu
-sağlayıcı girdisi oluştururken bir ChatGPT kimlik bilgisi alır.
+Oturum açma CLI'sı `ocx login codex` komutunu da kabul eder; bu yukarıdaki sağlayıcılardan biri
+değildir: komut Codex hesap havuzu girişine yönlendirilir (`ocx account login codex` ile aynı akış).
+Havuzun kendi hesap defteri vardır, bu nedenle bu yol çalışan bir proxy gerektirir. `chatgpt` ve
+`openai` aynı yolun takma adlarıdır.
 
 ```bash
 ocx login xai          # xAI Grok
@@ -122,8 +124,9 @@ ocx login kiro         # kiro-cli kimlik bilgilerini içe aktarın (veya belirte
 ocx login google-antigravity
 ocx login cursor       # bağımsız Cursor PKCE girişi
 ocx login command-code # Command Code tarayıcı OAuth (veya ~/.commandcode/auth.json içe aktarma)
+ocx login devin       # Cognition/Devin için Auth0 tarayıcı girişi
 ocx login github-copilot  # GitHub cihaz akışı → Copilot belirteci (Copilot Pro/Business)
-ocx login chatgpt      # bağımsız ChatGPT OAuth girişi
+ocx login codex        # Codex hesap havuzu (takma adlar: chatgpt, openai; çalışan bir proxy gerekir)
 ocx logout <saglayici>
 ```
 
@@ -136,6 +139,8 @@ ocx logout <saglayici>
 | `kiro` | `kiro` | `https://runtime.us-east-1.kiro.dev` | İlk oturum açma, kurulu ve oturum açılmış `kiro-cli` oturumunu içe aktarır (Unix'te `curl -fsSL https://cli.kiro.dev/install` &#124; `bash` ile kurun; Windows PowerShell'de `irm 'https://cli.kiro.dev/install.ps1'` &#124; `iex` kullanın; ardından `kiro-cli login` çalıştırın). **Hesap ekle**, `kiro-cli` oturumunu kapatır, `kiro-cli` tarafından kullanılan hesabı değiştiren yeni bir tarayıcı girişi başlatır ve hesap kapsamlı profil meta verilerini saklar. Mevcut OpenCodex hesapları korunur ve iptal veya başarısızlık önceki `kiro-cli` oturumunu geri yükler. |
 | `google-antigravity` | `google` | `https://daily-cloudcode-pa.googleapis.com` | Cloud Code Assist hattı üzerinden Google OAuth. Canlı keşif CCA'nın kimlik doğrulamalı `v1internal:fetchAvailableModels` uç noktasını kullanır ve oturum açmış hesap için kullanılabilir olan ajan modellerini yayınlar; sürdürülen katalog geri dönüş olarak kalır. |
 | `cursor` | `cursor` | `https://api2.cursor.sh` | Deneysel PKCE girişi, canlı HTTP/2 aktarımı ve hesap filtreli model keşfi. |
+| `devin` | `devin` | `https://server.codeium.com` | Deneysel, resmi olmayan Cognition/Devin köprüsü. Giriş tarayıcıda Auth0 oturumunu açar, ardından belirteci `RegisterUser` ile uzun ömürlü bir API anahtarına dönüştürür. Modeller hesaba göre `GetCascadeModelConfigs` ile keşfedilir; akış yalnızca Connect-RPC üzerindeki `runTurn` yolunu kullanır. Panel ön ayarında varsayılan olarak yer almaz. |
+| `devin-cli` | `devin` | `https://server.codeium.com` | Kurulu Devin CLI'nin zaten tuttuğu kimlik bilgisini içe aktarır (`devin auth login` bunu kendi `credentials.toml` dosyasına yazar), ardından `devin` sağlayıcısı gibi Cognition'ın Connect-RPC api-server'ı üzerinden akış yapar — tarayıcı girişi ve yapıştırılacak anahtar yok. Model listesi ve bağlam pencereleri hesabınızın kendi kataloğundan gelir. CLI'nin kendi yerel ajan döngüsü (ACP stdio) için farklı adlı bir satırda `"adapter": "devin-cli"` kullanın. |
 | `github-copilot` | `openai-chat` | `https://api.githubcopilot.com` | Deneysel. GitHub cihaz akışı + `copilot_internal` değişimi (VS Code OAuth istemcisi). Aktif bir Copilot aboneliği gerektirir; resmi bir üçüncü taraf API değildir. |
 
 Google Antigravity hesap ve sağlayıcı kota sorguları, model listesine geri dönüş dahil sabit Google uç noktalarını kullanır. Bu hedefler için şeffaf Fake-IP DNS desteklenirken TLS doğrulaması, yönlendirme reddi ve özel adres kontrolleri korunur. Özel base URL yalnızca model isteklerini değiştirir; `NO_PROXY` doğrudan bağlantı politikasını korur.
@@ -407,7 +412,7 @@ bitirir ancak son Responses olayını atlarsa opencodex beş saniyelik model
 kapsamlı bir yetkisiz kullanım onarımı uygular; hatalı biçimlendirilmiş veya
 kısmi akışlar başarılı olarak bildirilmek yerine tamamlanmamış olarak kapanır.
 
-> **Üç Volcengine faturalandırma rotası:** `volcengine` kullandıkça öde Ark API'sidir, `volcengine-coding-plan` Coding Plan kotasını tüketir ve `volcengine-agent-plan` Agent Plan kotasını tüketir. Aynı ürün için verilen anahtarı ve uç noktayı kullanın; sıradan `/api/v3` uç noktası bir Plan aboneliği mevcut olduğunda bile kullandıkça öde ücretlerine neden olabilir. Önayarlar özenle seçilmiş statik model katalogları kullanır çünkü Ark'ın `/models` yanıtı yerleştirme, görsel, video ve 3D kaynaklarını da içerir, Coding ağ geçidi aynı geniş kataloğu döndürür ve Agent Plan ağ geçidinin `/models` kaynağı yoktur. Kullandıkça öde varsayılan olarak `doubao-seed-2-1-pro-260628`'dir; seçilmiş kataloğu güncel DeepSeek ve GLM metin modellerini de içerir. Coding Plan varsayılan olarak `ark-code-latest`, Agent Plan ise varsayılan olarak `deepseek-v4-pro`'dur.
+> **Üç Volcengine faturalandırma rotası:** `volcengine` kullandıkça öde Ark API'sidir, `volcengine-coding-plan` Coding Plan kotasını tüketir ve `volcengine-agent-plan` Agent Plan kotasını tüketir. Aynı ürün için verilen anahtarı ve uç noktayı kullanın; sıradan `/api/v3` uç noktası bir Plan aboneliği mevcut olduğunda bile kullandıkça öde ücretlerine neden olabilir. Önayarlar özenle seçilmiş statik model katalogları kullanır çünkü Ark'ın `/models` yanıtı yerleştirme, görsel, video ve 3D kaynaklarını da içerir, Coding ağ geçidi aynı geniş kataloğu döndürür ve Agent Plan ağ geçidinin `/models` kaynağı yoktur. Kullandıkça öde varsayılan olarak `doubao-seed-2-1-pro-260628`'dir; seçilmiş kataloğu güncel DeepSeek ve GLM metin modellerini de içerir. Coding Plan varsayılan olarak `ark-code-latest`, Agent Plan ise varsayılan olarak `deepseek-v4-flash`'dur.
 
 > **Volcengine Plan kullanım kısıtlaması:** Volcengine, Coding Plan ve Agent Plan kotasını yalnızca desteklenen yapay zeka kodlama araçları içinde geçerli olarak belgeler ve genel API çağrıları için bir plan anahtarı kullanmanın aboneliği askıya alabileceği veya hesabı yasaklayabileceği konusunda uyarır. Codex veya Claude Code'u opencodex üzerinden yönlendirmek belgelenmiş kullanımdır; diğer otomasyonları bir plan anahtarına yönlendirmek değildir. Kullandıkça öde `volcengine` rotası böyle bir kısıtlama taşımaz.
 
@@ -650,7 +655,7 @@ listesini sağlayıcıdan keşfeder; böylece yeni Ollama Cloud modelleri yapıl
 değişikliği olmadan görünür. opencodex, bulut serisini vizyon
 yeteneğine göre sınıflandırır, böylece [vizyon sidecar'ı](/tr/guides/sidecars/)
 yalnızca salt metin modeller için devreye girer. Salt metin modeller (örneğin
-`glm-5.2`, `deepseek-v4-pro`, `gpt-oss`, `qwen3-coder`, `minimax-m2.x`,
+`glm-5.2`, `deepseek-v4-flash`, `gpt-oss`, `qwen3-coder`, `minimax-m2.x`,
 `nemotron-3-*`) `noVisionModels` içinde listelenir; vizyon yerel modeller
 (örneğin `kimi-k2.6`, `minimax-m3`, `gemma4`, `qwen3.5`,
 `gemini-3-flash-preview`) listelenmez. Eşleştirme Ollama'nın `:size`
diff --git a/docs-site/src/content/docs/tr/guides/sidecars.md b/docs-site/src/content/docs/tr/guides/sidecars.md
index 5205f0041f..19c7f16ee8 100644
--- a/docs-site/src/content/docs/tr/guides/sidecars.md
+++ b/docs-site/src/content/docs/tr/guides/sidecars.md
@@ -113,7 +113,7 @@ her üye görselleri yerel olarak veya bir sidecar üzerinden kabul ettiğinde v
 `imageInput` ayarı devre dışı olmadığında görsel girdisini bildirir; böylece Codex
 uygulaması gibi istemciler, sidecar çalışmadan önce ekleri engellemek yerine kabul eder.
 `visionSidecar.model` olmadığında veya boş
-olduğunda, OpenAI yürütme yolu, Kontrol Paneli ve yönetim API'si `gpt-5.4-mini`
+olduğunda, OpenAI yürütme yolu, Kontrol Paneli ve yönetim API'si `gpt-5.6-luna`
 geri dönüşünü kullanır. Başlangıç hala açıkça kalıcı hale getirilmiş eski bir
 `gpt-5.4-mini` değerini `gpt-5.6-luna`'ya geçirir; bu geçiş, bulunmayan bir
 model alanına değil, saklanan bir değere uygulanır.
@@ -178,7 +178,7 @@ Bir model, sağlayıcı başına salt metin olarak işaretlenir:
   "providers": {
     "ollama-cloud": {
       "baseUrl": "https://ollama.com/v1",
-      "noVisionModels": ["glm-5.2", "gpt-oss", "qwen3-coder", "deepseek-v4-pro"]
+      "noVisionModels": ["glm-5.2", "gpt-oss", "qwen3-coder", "deepseek-v4-flash"]
     }
   }
 }
diff --git a/docs-site/src/content/docs/tr/guides/sub-agent-surface.md b/docs-site/src/content/docs/tr/guides/sub-agent-surface.md
index c03f23ba44..1367d66c36 100644
--- a/docs-site/src/content/docs/tr/guides/sub-agent-surface.md
+++ b/docs-site/src/content/docs/tr/guides/sub-agent-surface.md
@@ -214,7 +214,7 @@ kullanın:
 ocx agent status
 ocx agent injection set --model anthropic/claude-sonnet-5 --effort xhigh
 ocx agent subagents set gpt-5.6-sol,anthropic/claude-sonnet-5
-ocx agent fallback set gpt-5.4-mini,xai/grok-4.5 --poll-ms 60000
+ocx agent fallback set gpt-5.6-luna,xai/grok-4.5 --poll-ms 60000
 ocx agent effort set --subagent max
 ```
 
diff --git a/docs-site/src/content/docs/tr/reference/adapters.md b/docs-site/src/content/docs/tr/reference/adapters.md
index 8d4e65e696..4040ce4157 100644
--- a/docs-site/src/content/docs/tr/reference/adapters.md
+++ b/docs-site/src/content/docs/tr/reference/adapters.md
@@ -308,6 +308,16 @@ başlığından Cursor OAuth/erişim belirteci.
   `unsafeAllowNativeLocalExec: true` yalnızca `nativeLocalExec` ayarlanmadığında
   eşdeğer kalır.
 
+## `devin`
+
+**Hedef:** Cognition'ın `exa.api_server_pb.ApiServerService/GetChatMessage` uç noktası; `server.codeium.com` üzerinde Connect akışı.
+**Kimlik doğrulama:** `provider.apiKey` veya iletilen authorization başlığındaki Devin/Cognition API anahtarı. Giriş tarayıcıda Auth0 oturumunu açar, ardından belirteci `SeatManagementService.RegisterUser` ile uzun ömürlü bir anahtara dönüştürür.
+
+- Olağan fetch/parse yolu yerine `runTurn` kullanır. İstekler ve sunucu olayları `devin/cloud-direct/wire.ts` içindeki elle yazılmış protobuf çerçevelemesiyle işlenir.
+- Modeller hesaba göre `GetCascadeModelConfigs` ile keşfedilir; pakette olmayanlar istek anında hata vermek yerine listeden düşer.
+- Cognition araç açıklamaları için uzunluk sınırı ve birebir ifade engeli uygular. Bağdaştırıcı bilinen ifadeleri yeniden yazar, uzun açıklamaları kırpar.
+- Anahtarlar yenilenmez. Süresi dolduğunda veya iptal edildiğinde `ocx login devin` komutunu yeniden çalıştırın.
+
 ## `azure-openai` (takma ad: `azure`)
 
 **Hedefler:** **Azure OpenAI**. `openai-responses`'ı sarar (bu nedenle
diff --git a/docs-site/src/content/docs/tr/reference/cli/agents.md b/docs-site/src/content/docs/tr/reference/cli/agents.md
index 04e72a766c..9f38ae6495 100644
--- a/docs-site/src/content/docs/tr/reference/cli/agents.md
+++ b/docs-site/src/content/docs/tr/reference/cli/agents.md
@@ -191,7 +191,7 @@ Grok Build model çitini yönetin ve uygulayın.
 
 ## İstemci yapılandırma dışa aktarma
 
-### `ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|prime|aside|raycast>`
+### `ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|prime|aside|raycast|omo>`
 
 Çalışan proxy'ye bağlı bir istemci yapılandırmasını yazdırın. Komut, `opencodex`
 sağlayıcı bloğunu — temel URL, model listesi ve istemcinin kimlik bilgisi
@@ -203,7 +203,7 @@ yalnızca Codex'in şu anda görebildiği modelleri yayınlar.
 
 | Bayrak | Eylem |
 | --- | --- |
-| `--client <opencode\|pi\|omp\|hermes\|openclaw\|kimi\|gajae\|dsh\|mcode\|zcode\|prime\|aside\|raycast>` | Gerekli. İstemci yapılandırma lehçesini seçer. |
+| `--client <opencode\|pi\|omp\|hermes\|openclaw\|kimi\|gajae\|dsh\|mcode\|zcode\|prime\|aside\|raycast\|omo>` | Gerekli. İstemci yapılandırma lehçesini seçer. |
 | `--json` | Betikler için stdout üzerinde oluşturulan belgeyi JSON olarak yazdırın. Bu, seçilen istemcinin yerel formatı YAML, TOML veya JSON5 olsa bile JSON'dur. |
 | `--out <path>` | İstemcinin yerel yapılandırma formatını `<path>` konumuna yazın. Mevcut bir dosyanın üzerine yazmayı reddeder. |
 | `--force` | `--out`'un mevcut bir dosyanın üzerine yazmasına izin verin. |
@@ -233,7 +233,9 @@ için kendi varsayılanlarını uygular) gelir.
 | `mcode` | `~/.minimax/config.yaml` (ayarlandığında `MINIMAX_DATA_DIR`, ardından eski `MAVIS_DATA_DIR` öncelikli; göreli değer reddedilir) | `mcode-config.yaml` | yok — geri döngü yer tutucusu |
 | `zcode` | `~/.zcode/v2/config.json` (ayarlandığında `ZCODE_DATA_DIR` öncelikli; göreli değer reddedilir) | `config.json` | yok — geri döngü yer tutucusu |
 | `prime` | `~/.prime/agent/models.json` (ayarlandığında `PRIME_AGENT_CODING_AGENT_DIR` öncelikli; göreli değer reddedilir) | `prime-models.json` | yok — geri döngü yer tutucusu |
+| `aside` | Aside'ın kendi `accounts.json` dosyasının güncel olarak gösterdiği hesap için `~/.aside/u/<account>/models.json`; okunamayan bir manifest, gelişigüzel bir hesaba düşmek yerine reddedilir | `aside-models.json` | yok — geri döngü yer tutucusu |
 | `raycast` | `~/.config/raycast/ai/providers.yaml`, macOS ve Windows'ta aynı (Raycast `XDG_CONFIG_HOME` değerini dikkate almaz) | `raycast-providers.yaml` | yok — yalnızca geri döngü, `api_keys` girdisi yazılmaz |
+| `omo` | `~/.omo/agent/models.json` (ayarlandığında sırasıyla `OMO_CODING_AGENT_DIR`, `SENPI_CODING_AGENT_DIR`, `PI_CODING_AGENT_DIR` öncelikli; göreli değer reddedilir) | `omo-models.json` | yok — geri döngü yer tutucusu |
 
 Raycast dışa aktarımı, `providers` dizisinde tek bir `id: opencodex` öğesi içeren bağımsız
 bir `providers.yaml` belgesidir: `name: OpenCodex`, proxy'nin `/v1` temel URL'si ve
@@ -270,8 +272,8 @@ döngünün ötesine bağlandığında ayarlayın; kabul anahtarlarının nasıl
 görmek için [Uzaktan erişim](/tr/reference/configuration/#remote-access)
 bölümüne bakın. Yukarı akış sağlayıcılarının kendi anahtarları tamamen ayrı bir
 şeydir ve [Sağlayıcılar](/tr/guides/providers/) bölümüne göre yapılandırılır.
-Gajae istisnadır: `OPENCODEX_GAJAE_API_KEY` provider kimlik bilgisini ortamdan
-sağlar, ancak şeması uzaktan kabul başlığını gönderemediği için üretilen Gajae
+gjc istisnadır: `OPENCODEX_GAJAE_API_KEY` provider kimlik bilgisini ortamdan
+sağlar, ancak şeması uzaktan kabul başlığını gönderemediği için üretilen gjc
 entegrasyonu yalnızca geri döngüde çalışır.
 
 Aynı yük `GET /api/client-config` tarafından sunulur ve kontrol panelinin API
diff --git a/docs-site/src/content/docs/tr/reference/cli/providers-accounts.md b/docs-site/src/content/docs/tr/reference/cli/providers-accounts.md
index 2d58adae3b..073156cf1a 100644
--- a/docs-site/src/content/docs/tr/reference/cli/providers-accounts.md
+++ b/docs-site/src/content/docs/tr/reference/cli/providers-accounts.md
@@ -75,10 +75,12 @@ kabul edilen OAuth ve API anahtarı sağlayıcı kimliklerini yazdırır.
 `ocx status` / `ocx doctor` yeniden kimlik doğrulama gerektiğini veya bir
 terminal yenileme hatasını bildirdikten sonra **yeniden kimlik doğrulaması
 yapmak** için aynı komutu kullanın (veya kontrol panelinde Yeniden Kimlik
-Doğrula'yı kullanın). Codex havuz hesapları genel bir `ocx login` sağlayıcısı
-değildir — bunun yerine kontrol paneli Codex hesap havuzu (Yeniden Kimlik
-Doğrula) veya başsız `ocx account reauth` akışı aracılığıyla yeniden kimlik
-doğrulaması yapın.
+Doğrula'yı kullanın). Codex havuz hesapları yukarıdaki OAuth veya API anahtarı
+sağlayıcılarından biri değildir, ancak `ocx login codex` onlara ulaşır: komut
+hesap havuzu girişine yönlendirilir, bu yüzden `ocx login codex --reauth` ile
+`ocx account reauth codex` aynı şeydir. Kontrol panelindeki Codex hesap havuzu
+(Yeniden Kimlik Doğrula) da aynısını yapar. Bu yol proxy içinde çalışır, bu
+nedenle çalışan bir proxy gerektirir.
 
 ```bash
 ocx login xai
@@ -111,7 +113,7 @@ Bir sağlayıcı için saklanan OAuth kimlik bilgisini kaldırın.
 listeleyin ve değiştirin. Sağlanan yardım arayüzü şöyledir:
 
 ```text
-Usage: ocx account <list|current|use|refresh|auto-switch|priority|login|reauth|code|cancel|remove|add-key|reset-credits> ...
+Usage: ocx account <list|current|use|refresh|auto-switch|priority|login|reauth|code|cancel|remove|add-key|reset-credits|grok-reset-coupons> ...
 
 list [provider]     Codex account pool, OAuth accounts and API keys (identifiers shown masked as the API returns them).
 current <provider>  Show the active account or key.
@@ -123,6 +125,7 @@ remove <provider> <id> --yes  Remove a stored account or key after an existence
 add-key <provider> [--label <label>]  Add a key read only from piped stdin.
 login/reauth/code/cancel  Run browser or manual-code auth from a headless shell.
 reset-credits <id|main> [--consume --yes]  Inspect or consume Codex reset credits.
+grok-reset-coupons [<id>] [--consume --yes] [--token-id <token-id>] [--operation-id <uuid>]  Inspect or redeem Grok reset coupons.
 Switching the active account takes effect immediately; running threads move on their next request, and in-flight requests keep the account they captured.
 A selection-order change applies from the next unbound request and never moves a bound thread.
 ```
@@ -232,11 +235,11 @@ eşleşen null veya eski bir rapora düşer (çıkış 0).
 
 ### `ocx account auto-switch <provider> <on|off|status|threshold <0-100>> [--json]`
 
-`openai` Codex havuzunun eşiğini yönetir veya genel OAuth havuzunun eşiğini kaydeder. `on` %80, `off` %0 kaydeder; `threshold <n>` 0–100 kabul eder. Genel havuz eşikleri şu anda uygulanmaz: kayıt işlemi eşik tabanlı geçişi, sağlayıcının etkinlik ayarını veya 429 hatasından sonraki otomatik hesap değişimini etkilemez. Genel havuz çıktısı sunucunun doğruladığı değerleri kullanır. Genel havuzlarda `poolEnabled`, kaydedilmiş sağlayıcı ayarıdır (`null` belirtilmemiş demektir); devralınmış etkin durumu göstermez. `inert: true`, eşiğin uygulanmadığını belirtir; yetenek bilinmiyorsa `enabled: true` bildirilmez. API anahtarlı sağlayıcılar, Anthropic ve geçersiz değerler reddedilir.
+`openai` Codex havuzunun eşiğini yönetir veya genel OAuth havuzunun eşiğini kaydeder. `on` %80, `off` %0 kaydeder; `threshold <n>` 0–100 kabul eder. Genel havuz eşiği yalnızca `pool.kernel` açıkken ve `strategy: "fill-first"` seçiliyken seçimi yönlendirir; bayrak kapalıyken kayıt işlemi eşik tabanlı geçişi etkinleştirmez. Her iki durumda da sağlayıcının etkinlik ayarını veya 429 hatasından sonraki otomatik hesap değişimini etkilemez. Genel havuz çıktısı sunucunun doğruladığı değerleri kullanır. Genel havuzlarda `poolEnabled`, kaydedilmiş sağlayıcı ayarıdır (`null` belirtilmemiş demektir); devralınmış etkin durumu göstermez. `inert: true` eşiğin kaydedildiğini ama uygulanmadığını, `inert: false` ise havuzun onu uyguladığını belirtir. `inert` yoksa yetenek bilinmiyordur ve bu durumda da `enabled: true` bildirilmez. API anahtarlı sağlayıcılar, Anthropic ve geçersiz değerler reddedilir.
 
 ```text
 openai: { provider, autoSwitchThreshold: number, enabled: boolean }
-generic OAuth: { provider, autoSwitchThreshold: number | null, enabled: boolean, poolEnabled: boolean | null, inert: true | null }
+generic OAuth: { provider, autoSwitchThreshold: number | null, enabled: boolean, poolEnabled: boolean | null, inert: boolean | null }
 ```
 
 ### `ocx account priority <provider> <account-id|main> [<-100..100|first|earlier|normal|later|last|reset>] [--json]`
@@ -327,6 +330,26 @@ anahtarı içermez.
 Bir hesap için Codex sıfırlama kredilerini inceleyin. Bir krediyi tüketmek
 yıkıcıdır ve hem `--consume` hem de `--yes` gerektirir.
 
+### `ocx account grok-reset-coupons [<account-id>] [--consume --yes [--token-id <id>] [--operation-id <uuid>]] [--json]`
+
+Bir xAI / Grok hesabı için kalan sıfırlama kuponlarını inceler veya bir tanesini kullanır.
+
+`--consume` olmadan çağrıldığında, kullanılabilir kupon jetonlarını ve geçerlilik pencerelerini döndürür:
+
+```bash
+ocx account grok-reset-coupons
+ocx account grok-reset-coupons acc_xai_01 --json
+```
+
+Bir sıfırlama kuponunu kullanmak faturalandırma durumunu değiştirir ve bir kupon jetonunu kalıcı olarak tüketir. `--consume` kesinlikle `--yes` gerektirir:
+
+```bash
+ocx account grok-reset-coupons --consume --yes
+ocx account grok-reset-coupons --consume --yes --token-id <token-id>
+```
+
+İdempotent sonuç garantisi için `--operation-id <uuid>` (geçerli bir UUIDv4 olmalıdır) iletin. Ağ kopması veya komutun yeniden denenmesi durumunda, özdeş işlem kimlikleri ikinci bir kupon tüketmek yerine kalıcı olarak kaydedilen sonucu yeniden oynatır.
+
 ### `ocx account main <alt-komut>`
 
 OpenCodex hesap havuzu yönlendirmesini değiştirmeden adlandırılmış yerel Codex
@@ -450,4 +473,3 @@ kapalı bir enum olarak ayrıştırır ve başka herhangi bir değer içeren tü
 kataloğu reddeder, bu nedenle `add`, `edit` ve yönetim API'si katalog
 yazıcısının daha sonra çıkarması gereken bir şeyi saklamak yerine hatalı değeri
 reddeder (#759).
-
diff --git a/docs-site/src/content/docs/tr/reference/configuration/agents.md b/docs-site/src/content/docs/tr/reference/configuration/agents.md
index fa181b1328..128ac3920a 100644
--- a/docs-site/src/content/docs/tr/reference/configuration/agents.md
+++ b/docs-site/src/content/docs/tr/reference/configuration/agents.md
@@ -136,9 +136,9 @@ kurtarır.
   "injectionModel": "gpt-5.5",
   "injectionEffort": "high",
   "syncCodexSubagentDefaults": true,
-  "subagentModelFallback": ["gpt-5.4-mini"],
+  "subagentModelFallback": ["gpt-5.6-luna"],
   "subagentModelFallbackByModel": {
-    "gpt-5.5": ["gpt-5.4-mini"]
+    "gpt-5.5": ["gpt-5.6-luna"]
   },
   "subagentModelFallbackPollMs": 60000,
   "subagentEffortCap": "high"
diff --git a/docs-site/src/content/docs/tr/reference/configuration/providers.md b/docs-site/src/content/docs/tr/reference/configuration/providers.md
index 36c183bf11..3d72f129a7 100644
--- a/docs-site/src/content/docs/tr/reference/configuration/providers.md
+++ b/docs-site/src/content/docs/tr/reference/configuration/providers.md
@@ -38,8 +38,9 @@ Arayüzde kayıt veya OAuth girişi tamamlanınca Models sayfasını açan bir b
 | `activeCodexAccountId?` | `string` | — | Sonraki istek için manuel olarak seçilen Havuz hesabı. Seçim iş parçacığı bağlılığını temizler; devam eden istekler yakalanan kimlik bilgilerini korur. |
 | `codexAccountPriorities?` | `Record<string, number>` | — | Codex havuzu için hesap başına seçim sırası: hesap kimliği → `-100` ile `100` arası tam sayı, **daha yüksek olan daha önce kullanılır**, yoksa `0` anlamına gelir. Bu bir öncelik sırası sınırıdır, bir uygunluk sınırı değildir: seçim, zaten uygun olan hesapları hala kota payı bulunan en yüksek katmana daraltır ve `accountPoolStrategy` daha sonra bu katman içinde seçim yapar. Bir katman, yalnızca her üye `autoSwitchThreshold` üzerinde olduğunda, soğumada olduğunda, yumuşak kaçınıldığında, duraklatıldığında veya yeniden kimlik doğrulama gerektiğinde atlanır — bilinmeyen kota asla bir katmanı boşaltmaz. Sıralama asla uygun olmayan bir hesabı seçilebilir yapmaz ve zaten bir hesabı olan bir iş parçacığını asla yeniden bağlamaz. Ana `__main__` hesap eşit şartlarda katılır, bu sayede Codex Desktop girişi en son tükenecek şekilde ayarlanabilir. Hiçbir girdi olmadığında havuz tam olarak eskisi gibi davranır. Hatalı biçimlendirilmiş bir harita bir konsol uyarısıyla yok sayılır (sıralama kapalı, yapılandırma onarımı yok). `ocx account priority` ve Codex Auth sayfası tarafından yönetilir. |
 | `activeCodexAccountPinned?` | `string` | — | Operatörün en son elle seçtiği hesap kimliği. Ayarlandığı sürece, pin tükenme, hariç tutma, silme veya açık bir yük devretme/yükseltme ile serbest bırakılana kadar daha yüksek bir `codexAccountPriorities` katmanı onu öncelikleyemez. Sınırlı katman içindeki sıradan round-robin hareketi onu serbest bırakmaz. Herhangi bir `codexAccountPriorities` girdisi yazmak da pini serbest bırakır, böylece bir sıra var olmadan önce yapılan bir pin daha sonra ayarlanan bir pinin önüne geçemez. `GET /api/codex-auth/active`, hem geçerli hesabın sabitlenip sabitlenmediğini (`pinned`) hem de tavanı taşıyan hesabı (`pinnedAccountId`) bildirir. |
-| `autoSwitchThreshold?` | `number` | `80` | Proaktif geçiş için kullanım eşiği. `quota`, bir sonraki isteklerinde hem bağlı hem de bağımsız görevleri yeniden değerlendirebilir; `fill-first` bunu yalnızca bağımsız atama için tükenme noktası olarak kullanır; normal `round-robin` seçimi bunu kullanmaz. Puan, bilinen en sıcak 5 saatlik, haftalık veya 30 günlük kota penceresini kullanır. `0`, yalnızca kullanıma dayalı proaktif geçişi devre dışı bırakır, bağımsız atamayı veya arıza kurtarmayı devre dışı bırakmaz. |
-| `accountPoolStrategy?` | `"quota" \| "round-robin" \| "fill-first"` | `"quota"` | Yeni/bağımsız Codex istekleri için atama stratejisi. Bir istek, canlı (üst iş parçacığı kimliği, kota kapsamı) bağlılığı olmadığında bağımsızdır; görünür mevcut bir görev, proxy yeniden başlatmasından veya bağlılık sıfırlamasından sonra bağımsız hale gelebilir. `quota`, aktif bir hesap olmadığında en düşük kullanımlı uygun hesabı seçer, `autoSwitchThreshold` altında uygun bir aktif hesabı tutar ve eşikten sonra bağımsız bir isteği taşıyabilir veya bağlı bir görevi proaktif olarak daha düşük kullanımlı uygun bir hesaba yeniden bağlayabilir. `round-robin`, bağımsız istekleri eşit olarak dağıtır; `fill-first`, soğuma, kullanılamama veya yapılandırılmış tükenme eşiğine kadar bağımsız istekleri aktif hesaba atamaya devam eder. |
+| `autoSwitchThreshold?` | `number` | `80` | Proaktif geçiş için kullanım eşiği. `quota`, bağımsız görevlerin bir sonraki isteğini yeniden değerlendirebilir ve varsayılan olarak kullanım bu eşiği geçince bağlı görevleri de yeniden değerlendirir. `pool.cacheAffinity` açıkken bağlı bir görev, hesap tükenene veya hizmet veremez hale gelene kadar eşiğin ötesinde hesabını korur. `fill-first` bunu yalnızca bağımsız atama için tükenme noktası olarak kullanır; normal `round-robin` seçimi bunu kullanmaz. Puan, bilinen en sıcak 5 saatlik, haftalık veya 30 günlük kota penceresini kullanır. `0`, yalnızca kullanıma dayalı proaktif geçişi devre dışı bırakır, bağımsız atamayı veya arıza kurtarmayı devre dışı bırakmaz. |
+| `accountPoolStrategy?` | `"quota" \| "round-robin" \| "fill-first"` | `"quota"` | Yeni/bağımsız Codex istekleri için atama stratejisi. Bir istek, canlı (üst iş parçacığı kimliği, kota kapsamı) bağlılığı olmadığında bağımsızdır; görünür mevcut bir görev, proxy yeniden başlatmasından veya bağlılık sıfırlamasından sonra bağımsız hale gelebilir. `quota`, aktif bir hesap olmadığında en düşük kullanımlı uygun hesabı seçer, `autoSwitchThreshold` altında uygun bir aktif hesabı tutar ve eşikten sonra bağımsız bir isteği taşıyabilir. `pool.cacheAffinity` kapalıysa bağlı bir görevi proaktif olarak daha düşük kullanımlı uygun bir hesaba yeniden bağlayabilir. Bayrak açıkken bağlı görev, hesabı tükenene (bilinen kullanım %100) veya hizmet veremez hale gelene kadar kalır. `round-robin`, bağımsız istekleri eşit olarak dağıtır; `fill-first`, soğuma, kullanılamama veya yapılandırılmış tükenme eşiğine kadar bağımsız istekleri aktif hesaba atamaya devam eder. |
+| `pool.cacheAffinity?` | `boolean` | `false` | Bağlı Codex iş parçacıkları için isteğe bağlı önbellek bağlılığı sıralaması; `pool.kernel`'dan bağımsızdır. Varsayılan olarak kapalıdır; hatalı bir değer kapalı okunur. Açıkken canlı bağlama kota payından öndedir: `quota`, kullanımın `autoSwitchThreshold`'u geçmesi nedeniyle iş parçacığını taşımaz. Hesap duraklatılmış, kullanılamaz veya gerçekten tükenmişse (bilinen kullanım %100) iş parçacığı yine ayrılır; bağlılık bir sabitleme değil yeniden sıralamadır. |
 | `accountPoolStickyLimit?` | `number` | `1` | İlerlemeden önce bir round-robin seçiminde tutulan yeni/bağımsız görev atamaları; sayaç yukarı akış başarısından sonra değil, bir görev bağlandığında ilerler. Aralık 1–100. |
 | `upstreamFailoverThreshold?` | `number` | `3` | Gelecekteki yeni oturumların yük devretmesinden önceki ardışık geçici arızalar. Devre dışı bırakmak için `0` ayarlayın. Düzenli Responses ve yerel sıkıştırma gönderimleri için kanıtlanmış bağlantı öncesi DNS/TCP erişilebilirlik arızaları sağlayıcı-ana bilgisayar düzeyinde izlenir: hesap sağlığını, hesap soğuma sürelerini, iş parçacığı/oturum bağlılığını, aktif hesap seçimini veya Havuz yönlendirmesini asla etkilemez ve bu eşiğe asla sayılmaz. |
 | `upstreamHostCircuitThreshold?` | `number` | `0` | Yerel OpenAI iletme Responses ve sıkıştırma gönderimlerinde kanıtlanmış bağlantı öncesi DNS/TCP arızaları için isteğe bağlı devre eşiği. `0` devre dışı bırakır; `1`–`20`, bu kadar terminal mantıksal istekten sonra 30 saniyelik bir sağlayıcı-kaynak soğuma süresi açar. Açıkken istekler, hesap seçiminden veya yukarı akış gönderiminden önce `Retry-After` ile `503` alır; soğuma süresinden sonra bir yarı açık isteğe izin verilir. Zaman aşımları ve HTTP yanıtları asla sayılmaz ve herhangi bir HTTP yanıtı devreyi kapatır. Yalnızca sabitlenmiş hesabı olmayan Codex Havuz yönlendirmesi için geçerlidir; `codexAccountMode: "direct"` ve hesap nitelikli seçiciler için etkisizdir. |
@@ -136,6 +137,7 @@ alanlı seçilmiş kimlikleri yalın kimliklere yeniden yazar.
 | `noTopPModels?` | `string[]` | Arayan tarafından belirtilen `top_p` değerini reddeden modeller. |
 | `noPenaltyModels?` | `string[]` | Varlık/frekans cezalarını reddeden modeller. |
 | `noStructuredOutputModels?` | `string[]` | `openai-chat` uç noktası `response_format`'ı reddeden tam model kimlikleri. Yalnızca tam bir istenen model eşleşmesi alanı atlar; yapılandırılmış çıktı çevirisi diğer her `openai-chat` modeli için etkin kalır. |
+| `noJsonSchemaModels?` | `string[]` | `openai-chat` uç noktası `json_schema` biçimini reddeden ama `json_object` kabul eden tam model kimlikleri. Böyle bir istek atılmak yerine `json_object` seviyesine düşürülür, böylece JSON isteyen çağıran yine JSON alır. Bir model her iki listede de varsa `noStructuredOutputModels` kazanır. `opencode go`, `opencode zen` ve `opencode free` hazır ayarları bunu DeepSeek rotaları için getirir. |
 | `parallelToolCalls?` | `boolean` | Paralel araç çağrılarını açıp kapatın. OpenAI Chat varsayılan olarak açıktır; sohbet harici adaptörler yalnızca açık `true` durumunda bildirir. |
 | `responsesItemIdRepair?` | `{ message?: string[]; reasoning?: string[]; repairMissingTerminalIds?: boolean; repairInvalidIds?: boolean }` | Tam yer tutucu kimlikleri, eksik terminal kimlikleri ve (`repairInvalidIds` ile) kurallı `msg_`/`rs_` öneki eksik olan mesaj/akıl yürütme kimlikleri için varsayılan olarak devre dışı bırakılmış aşağı akış SSE onarımı. Fonksiyon çağrısı kimlikleri asla yeniden yazılmaz. Yerleşik DeepSeek son ikisini varsayılan olarak etkinleştirir. |
 | `responsesSnapshotRepair?` | `boolean` | SSE ve JSON'daki seyrek Responses yaşam döngüsü anlık görüntüleri için varsayılan olarak devre dışı bırakılmış istemciye yönelik onarım. Ham inceleme ve kalıcılık değişmeden kalırken eksik kurallı durumu, çıktıyı ve araç meta verilerini doldurur. |
@@ -195,10 +197,12 @@ Havuz hesapları eklemek ve kotaları yenilemek için kontrol panelinde **Codex
 Auth** kullanın. `config.json` gizli olmayan meta verileri saklar; erişim ve
 yenileme belirteçleri güçlendirilmiş kimlik bilgisi deposunu kullanır. Havuz
 yönlendirmesi yeni/bağımsız atamayı, kullanıma dayalı proaktif geçişi ve arıza
-kurtarmayı ayırır. Bağlı bir görev normalde bağlılığı korur, ancak `quota`,
-kullanım eşiği aşıldıktan sonraki bir sonraki isteğinde onu yeniden
-bağlayabilir; duraklatma, soğuma, yeniden kimlik doğrulama ve arıza işleme ise
-yönlendirmeyi bağımsız olarak temizleyebilir veya taşıyabilir. Bağımsız bir
+kurtarmayı ayırır. Bağlı bir görev normalde bağlılığı korur. Varsayılan olarak
+`quota`, kullanım eşiği aşıldıktan sonraki isteğinde onu yeniden bağlayabilir;
+`pool.cacheAffinity` açıkken bu yeniden bağlama, bağlı hesap tükenene veya
+hizmet veremez hale gelene kadar bekler. Duraklatma, soğuma, yeniden kimlik
+doğrulama ve arıza işleme ise yönlendirmeyi bağımsız olarak temizleyebilir veya
+taşıyabilir. Bağımsız bir
 isteğin canlı hesap bağlaması yoktur; bu, proxy yeniden başlatmasından veya
 bağlılık sıfırlamasından sonra mevcut görünür bir görevi içerebilir. Akış öncesi
 bir 429 veya 402, kullanıma dayalı proaktif geçiş kapalı olsa bile aynı istekte
@@ -226,7 +230,7 @@ kalır.
 
 | Strateji | Davranış |
 | --- | --- |
-| `quota` (varsayılan) | Aktif bir hesap yoksa 5 saatlik, haftalık ve 30 günlük pencerelerde en düşük kullanımlı uygun hesabı seçin. Aksi takdirde `autoSwitchThreshold` altında uygun bir aktif hesabı tutun; eşiği aştıktan sonra bağımsız bir istek veya bağlı bir görevin bir sonraki isteği daha düşük kullanımlı uygun bir hesaba geçebilir. `0`, bu kullanım odaklı yeniden değerlendirmeyi devre dışı bırakır, arıza kurtarmayı devre dışı bırakmaz. |
+| `quota` (varsayılan) | Aktif bir hesap yoksa 5 saatlik, haftalık ve 30 günlük pencerelerde en düşük kullanımlı uygun hesabı seçin. Aksi takdirde `autoSwitchThreshold` altında uygun bir aktif hesabı tutun; eşiği aştıktan sonra bağımsız bir istek daha düşük kullanımlı uygun bir hesaba geçebilir ve `pool.cacheAffinity` kapalıysa bağlı bir görevin bir sonraki isteği de geçebilir. Bayrak açıkken önbellek bağlılığı kota payından öndedir ve bağlı görev, hesap tükenene (bilinen kullanım %100) veya hizmet veremez hale gelene (duraklatılmış, kullanılamaz) kadar kalır. `0`, bu kullanım odaklı yeniden değerlendirmeyi devre dışı bırakır, arıza kurtarmayı devre dışı bırakmaz. |
 | `round-robin` | Bağımsız istekleri uygun hesaplar arasında eşit olarak atayın. `autoSwitchThreshold` normal round-robin seçimini değiştirmez. `accountPoolStickyLimit` (1–100), başarılı yukarı akış yanıtlarını değil, bir seçimdeki atamaları sayar. |
 | `fill-first` | Bağımsız istekleri soğuma, yeniden kimlik doğrulama veya yapılandırılmış tükenme eşiğine kadar aktif hesaba atayın; bilinmeyen kullanım geçişe zorlamaz. Sağlıklı bağlı görevler bağlılığı korur. |
 
@@ -280,7 +284,7 @@ yönetilir.
 | `failureBackoffMaxSeconds?` | `number` | `3600` | Geri çekilme tavanı ve kalıcı arıza gecikmesi. |
 | `codexWarmupEnabled?` | `boolean` | `false` | Sentetik Codex havuz hesabı doğrulamasına dahil olun. |
 | `codexWarmupMaxAgeSeconds?` | `number` | `691200` | 8 gün sonra bir hesabı yeniden doğrulayın. |
-| `codexWarmupModel?` | `string` | `gpt-5.4-mini` | İsteğe bağlı ısınma için kullanılan yerel model. |
+| `codexWarmupModel?` | `string` | `gpt-5.6-luna` | İsteğe bağlı ısınma için kullanılan yerel model. |
 
 ## Sabit sağlayıcı uç noktaları
 
@@ -557,7 +561,7 @@ geçerli adı kontrol edin.
       "baseUrl": "https://ollama.com/v1",
       "apiKey": "${OLLAMA_API_KEY}",
       "defaultModel": "glm-5.2",
-      "noVisionModels": ["glm-5.2", "gpt-oss", "qwen3-coder", "deepseek-v4-pro"]
+      "noVisionModels": ["glm-5.2", "gpt-oss", "qwen3-coder", "deepseek-v4-flash"]
     }
   },
   "subagentModels": ["anthropic/claude-opus-5", "ollama-cloud/glm-5.2"],
diff --git a/docs-site/src/content/docs/tr/reference/configuration/server.md b/docs-site/src/content/docs/tr/reference/configuration/server.md
index 3b6ee8a9f3..439cd70606 100644
--- a/docs-site/src/content/docs/tr/reference/configuration/server.md
+++ b/docs-site/src/content/docs/tr/reference/configuration/server.md
@@ -267,7 +267,7 @@ hareketsizlik korumasıdır, toplam bir üretim süresi sınırı değildir.
 | --- | --- | --- | --- |
 | `enabled?` | `boolean` | kullanılabilir olduğunda açık | Ana görsel açıklama anahtarı. |
 | `backend?` | `"openai" \| "anthropic"` | auto | Açık değer önceliklidir; ayarlanmadığında kullanılabilir kayıtlı bir Anthropic OAuth kimlik bilgisi tercih edilir, aksi halde `openai` kullanılır. |
-| `model?` | `string` | arka uca bağlı | OpenAI için `gpt-5.4-mini` veya Anthropic için `claude-sonnet-5`. |
+| `model?` | `string` | arka uca bağlı | OpenAI için `gpt-5.6-luna` veya Anthropic için `claude-sonnet-5`. |
 | `maxDescriptionsPerTurn?` | `number` | `8` | Ana tur başına kabul edilen yeni açıklama önbellek ıskalamaları. `0` çağrıları devre dışı bırakır; geçersiz değerler varsayılanı kullanır. |
 | `timeoutMs?` | `number` | `45000` | Sidecar getirme zaman aşımı. Tamsayı 1–2147483647. |
 
diff --git a/docs-site/src/content/docs/tr/reference/management-api.md b/docs-site/src/content/docs/tr/reference/management-api.md
index afdb835e9c..bfdd83dcd9 100644
--- a/docs-site/src/content/docs/tr/reference/management-api.md
+++ b/docs-site/src/content/docs/tr/reference/management-api.md
@@ -83,11 +83,22 @@ hatalar" sütunu bu tabloyu tekrarlamak yerine rotaya özgü ek sonuçları list
 | `GET /api/grok` | Grok yönetilen yapılandırma durumunu ve aday modelleri okuyun | 400 durum okuma hatası |
 | `PUT /api/grok/selection` | Hariç tutulan Grok modellerini kalıcı hale getirin | 400 geçersiz veya aşırı büyük seçim |
 | `POST /api/grok/apply` | Kalıcı hale getirilen Grok yapılandırmasını yönetilen senkronizasyon aracılığıyla uygulayın | 409 `grok_apply_busy`; 400/500 uygulama hatası |
+| `GET /api/grok/reset-coupons?accountId=...` | Aktif veya belirtilen xAI hesabı için kalan Grok faturalandırma sıfırlama jetonlarını ve geçerlilik pencerelerini okuyun | 400 eksik hesap; 401 kimlik doğrulaması yok; 502 yukarı akış gRPC-Web hatası |
+| `POST /api/grok/reset-coupons/consume` | Uygun bir sıfırlama kuponunu kullanın. Gövde `{ accountId?, tokenId?, operationId? }`. İsteğe bağlı `operationId` (UUIDv4) kullanımı idempotent yapar: aynı kimliği yinelemek, çift kullanım olmadan kalıcı sonucu yeniden oynatır. | 400 geçersiz JSON/UUID; 401 kimlik doğrulaması yok; 409 `identity_mismatch`; 502 yukarı akış hatası; 503 kayıt defteri kapasitesi |
 | `GET, PUT /api/claude-desktop` | Claude Desktop yönlendirilen/yerel profilini okuyun veya kalıcı hale getirin | 400 geçersiz veya kullanılamaz atama |
 | `POST /api/claude-desktop/apply` | Kaydedilen profili Claude Desktop'ın yönetilen yapılandırmasına yazın | 400/500 yazma hatası |
 | `GET /api/claude-desktop/status` | Kaydedilen ve uygulanan profili ve Desktop sağlığını inceleyin | 400 durum okuma hatası |
 | `GET, PUT /api/claude-code` | Claude Code ağ geçidi, kimlik doğrulama modu, model haritası, bağlam, ajan ve sidecar ayarlarını okuyun veya güncelleyin | 400 geçersiz alan veya şekil |
 
+Kontrol paneli her iki kupon yolunu da **Providers > xAI Grok > Accounts**
+üzerinden yürütür: oturum açmış her hesap satırı, kalan kupon sayısını gösteren
+bir bilet rozeti taşır ve rozet, geçerlilik pencerelerini listeleyen ve süresi
+dolmaya en yakın kuponu kullanan bir iletişim kutusu açar. İletişim kutusu
+istemci tarafından üretilen bir `operationId` gönderir ve yeniden denemek yerine
+zaman aşımından sonra göndermeyi durdurur; çünkü günlük kaydı hâlâ açık olan
+bir kullanım yeniden yürütülür. `ocx account grok-reset-coupons` uçbirim
+eşdeğeri olarak kalır.
+
 Model kadrosunun ve şifrelenmiş çalışan görevi davranışının arkasındaki
 kavramlar için [Alt Ajan Arayüzü](/tr/guides/sub-agent-surface/) sayfasına
 bakın.
diff --git a/docs-site/src/content/docs/tr/reference/proxy-formats.md b/docs-site/src/content/docs/tr/reference/proxy-formats.md
index fed53c1afb..84ad0cf5e1 100644
--- a/docs-site/src/content/docs/tr/reference/proxy-formats.md
+++ b/docs-site/src/content/docs/tr/reference/proxy-formats.md
@@ -341,6 +341,8 @@ Responses ailesi ve Chat istekleri, özel başlıkta veya Bearer alanında bir p
 
 Anahtarı olmayan ve OAuth kullanmayan bir Cursor rotası, çağıranın ayrı bearer’ını kullanabilir; proxy sırrını veya otomatik eklenen ChatGPT main kimlik bilgisini kullanamaz. Combo/policy seçimi ve gerçekleşen shadow/thread-spawn rota değişiklikleri, çağıranın ham kimlik bilgilerini yeni hedeflere aktarmaz. Kanonik OpenAI yönlendirmesi, dahili rota değişikliğinden sonra çağıranın proxy anahtarı olmayan tek bearer’ını yalnızca JWT’si bir ChatGPT hesap claim’i içeriyorsa ve açıkça belirtilmiş herhangi bir hesap başlığı bu claim ile eşleşiyorsa geri yükleyebilir. Çağıranın kimlik doğrulamasını isteğe bağlı OpenAI sidecar’larına iletmek için tek bir JWT ve onunla eşleşen, açıkça belirtilmiş bir `chatgpt-account-id` gerekir. Opaque bearer’lar, açıkça belirtilmiş bir hesap başlığı olsa bile rota değişikliklerinden sonra geri yüklenmez. Diğer durumlarda son hedefin kendi yapılandırılmış, OAuth veya kayıtlı kimlik bilgisi bulunmalıdır; aksi hâlde istek yerel olarak başarısız olur. Rota değişmeden yalnızca thread-spawn işaretinin bulunması kimlik bilgilerini kaldırmaz.
 
+Yapılandırılmış anahtarı olmayan Cursor'a gönderilen Chat isteğinde, kayıtlı main kimliğiyle isteğe bağlı tamamlama ancak bir OpenAI yardımcısı gerçekten planlandığında ve kanonik Direct adayı bulunduğunda yapılır. İlgisiz bir Cursor isteği bu yoldan native main üzerinde sahiplik almaz ve profil geçişini geciktirmez. Yardımcı kimlik bilgileri başlangıç ve profil geçişi korumalarına uyar ve Cursor bearer'ından ayrı tutulur. Pool ve belirli hesaba yönelen yardımcılar mevcut hesap seçimini korur.
+
 Claude replay, main kimlik bilgisini yalnızca ilgili turn tarafından sahipliği alınmış bir bellek snapshot’ında tutar ve yalnızca son hedef kanonik bir ChatGPT rotasıysa geri yükler.
 
 :::caution
diff --git a/docs-site/src/content/docs/zh-cn/getting-started/quickstart.md b/docs-site/src/content/docs/zh-cn/getting-started/quickstart.md
index d3495a3ce4..f4aeabc2d7 100644
--- a/docs-site/src/content/docs/zh-cn/getting-started/quickstart.md
+++ b/docs-site/src/content/docs/zh-cn/getting-started/quickstart.md
@@ -65,7 +65,7 @@ codex -m "ollama-cloud/glm-5.2"      "Write a SQL migration"
 
 ## 选择 sub-agent 模型（可选）
 
-全新配置会在 Codex 的 sub-agent 选择器中提供五个原生模型：`gpt-5.5`、`gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna` 和 `gpt-5.4-mini`。打开 `ocx gui`，可以替换或重新排序最多五个原生或已路由模型。仪表盘还可以设置一个首选 sub-agent 模型和 reasoning effort。参见 [Sub-agent Surface](/guides/sub-agent-surface/) 以选择 v1/base/v2，并了解何时适用 guidance、原生默认值和 fallback。
+全新配置会在 Codex 的 sub-agent 选择器中提供五个原生模型：`gpt-5.5`、`gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna` 和 `gpt-6-astra`。打开 `ocx gui`，可以替换或重新排序最多五个原生或已路由模型。仪表盘还可以设置一个首选 sub-agent 模型和 reasoning effort。参见 [Sub-agent Surface](/guides/sub-agent-surface/) 以选择 v1/base/v2，并了解何时适用 guidance、原生默认值和 fallback。
 
 ## 登录而非粘贴 key
 
diff --git a/docs-site/src/content/docs/zh-cn/guides/claude-code.md b/docs-site/src/content/docs/zh-cn/guides/claude-code.md
index 216766f70c..4c4982908f 100644
--- a/docs-site/src/content/docs/zh-cn/guides/claude-code.md
+++ b/docs-site/src/content/docs/zh-cn/guides/claude-code.md
@@ -463,3 +463,5 @@ Claude 模型时自动加载。对于原生透传，这是正常现象；对于
 
 **子代理派发到错误模型**——名册代理（`ocx-*`）使用 `<!-- ocx-route: ... -->` 指令，
 而不是 Agent 工具的 `model` 参数。请确保指令与预期路由一致。传入 `"haiku"` 作为模型占位符。
+
+在 `config.json` 中设置 `claudeCode.stabilizePromptCache: true`，可在转换路由上将系统指令末尾受支持的 Claude 提示移到最后一条用户消息。默认值为 `false`。仅在客户端允许这种角色变化时启用。代码围栏内的示例和不匹配的文本会保留，Anthropic 原生透传不变。没有元数据时，缓存键按稳定后的指令计算。该选项不会生成会话标识，也不保证上游缓存命中。
diff --git a/docs-site/src/content/docs/zh-cn/guides/codex-app-models.md b/docs-site/src/content/docs/zh-cn/guides/codex-app-models.md
index 241b812252..d47a080ac5 100644
--- a/docs-site/src/content/docs/zh-cn/guides/codex-app-models.md
+++ b/docs-site/src/content/docs/zh-cn/guides/codex-app-models.md
@@ -61,7 +61,7 @@ visibility = "list"
 
 ## 当前稳定模型覆盖
 
-原生回退集合包含 `gpt-5.5`、`gpt-5.4`、`gpt-5.4-mini`、`gpt-5.3-codex-spark` 以及 GPT-5.6 Sol/Terra/Luna。对于 GPT-5.5/5.4 家族，opencodex 会保留已安装 Codex 目录中更丰富的实时条目，只在缺失时才合成条目。内置的上游快照只用于 GPT-5.6，因为它提供的是每个模型真实的身份和元数据，而不是较旧模板的近似版本。
+原生回退集合包含 `gpt-5.5`、`gpt-5.3-codex-spark` 以及 GPT-5.6 Sol/Terra/Luna。对于 GPT-5.5 家族，opencodex 会保留已安装 Codex 目录中更丰富的实时条目，只在缺失时才合成条目。内置的上游快照只用于 GPT-5.6，因为它提供的是每个模型真实的身份和元数据，而不是较旧模板的近似版本。
 
 | 路由 | 选择器 id 与目录元数据 |
 | --- | --- |
diff --git a/docs-site/src/content/docs/zh-cn/guides/codex-integration.md b/docs-site/src/content/docs/zh-cn/guides/codex-integration.md
index 71d2b81473..52c32ba2da 100644
--- a/docs-site/src/content/docs/zh-cn/guides/codex-integration.md
+++ b/docs-site/src/content/docs/zh-cn/guides/codex-integration.md
@@ -312,7 +312,7 @@ fallback 行为，参见 [Sub-agent Surface](/guides/sub-agent-surface/)。
 
 ## Codex 账号预热
 
-添加或重新认证账号时，通常会在保存前发送一个小型模型请求并等待 `response.completed`。默认使用 `gpt-5.4-mini`，HTTP 400 或 HTTP 404 时改用 `gpt-5.5` 与 `gpt-5.6-luna` 重试。公开错误仅包含固定分类，不包含原始响应正文。
+添加或重新认证账号时，通常会在保存前发送一个小型模型请求并等待 `response.completed`。默认使用 `gpt-5.6-luna`，HTTP 400 或 HTTP 404 时改用 `gpt-5.5` 重试。公开错误仅包含固定分类，不包含原始响应正文。
 
 如果新 OAuth 凭据的已认证用量查询确认5小时、每周或每月额度耗尽，则不调用模型而直接保存账号，显示**等待验证**。重启或刷新令牌也不会使其可用。额度恢复后刷新额度：只有完整的最新用量显示有余额，才会发送一个小型验证请求；请求完成后账号才可用于路由。查询或验证失败将保留等待状态。普通状态轮询不会发送该请求。初次注册时用量未知仍需常规预热验证。
 
@@ -334,7 +334,7 @@ fallback 行为，参见 [Sub-agent Surface](/guides/sub-agent-surface/)。
 ocx config set codexPool '{"excludedPlans":["free"]}'
 ```
 
-这是选择策略，不是封禁。被排除的账号保留凭据、用量历史和线程亲和性，仍显示在账号列表中，也仍可通过 `work/gpt-5.4` 这类显式选择使用。改变的只是自动轮换不再选它，包括它已经是活跃账号或已绑定线程的情况——订阅到期后留下的正是这种状态。
+这是选择策略，不是封禁。被排除的账号保留凭据、用量历史和线程亲和性，仍显示在账号列表中，也仍可通过 `work/gpt-5.5` 这类显式选择使用。改变的只是自动轮换不再选它，包括它已经是活跃账号或已绑定线程的情况——订阅到期后留下的正是这种状态。
 
 有两处刻意的限制。主 Codex 账号不会因套餐被排除：仅选择模式的路由不读取受保护的原生凭据而隐去其套餐，覆盖主账号的规则会自相矛盾。另外，当没有未被排除的账号时，被排除的账号仍会应答而不是失败；要彻底停止服务，仍然是暂停全部账号。没有对应的 `minimumPlan`，因为给 ChatGPT 套餐排序需要一个这里并不存在的全序。
 
@@ -353,3 +353,9 @@ ocx restore back # point plain Codex at the running proxy again
 当 opencodex 作为受管的 [background service](/reference/cli/#ocx-service) 运行时，它会设置
 `OCX_SERVICE=1`，这样由服务驱动的重启**不会**反复改写 Codex config——只有显式的
 `ocx stop` / `ocx service stop` 才会恢复原生 Codex。
+
+## 分页历史记录安全拒绝
+
+如果受影响的历史存储支持分页，提供商切换可能返回 `history_paginated_requires_native_writer`。OpenCodex 会保留当前配置、配置档、模型目录、历史文件及恢复依据，而不是在 Codex 之外分配序号；可迁移存储中的 legacy 记录也受保护。仅保留外部提供商而不执行切换的路径仍然可用。
+
+不要删除会话仍在引用的提供商定义、反复运行 `ocx sync` 或旧版恢复，也不要改写正在使用的历史文件来绕过拒绝。保留文件，在恢复前关闭相关会话，并只报告准确的错误和版本，不要公开私人历史。需要与原生写入器协调的已验证修复。备份或脚本成功并不能证明显示已恢复；重新打开 Codex 后检查会话。
diff --git a/docs-site/src/content/docs/zh-cn/guides/combos.md b/docs-site/src/content/docs/zh-cn/guides/combos.md
index fea189deb3..abe32ae786 100644
--- a/docs-site/src/content/docs/zh-cn/guides/combos.md
+++ b/docs-site/src/content/docs/zh-cn/guides/combos.md
@@ -139,6 +139,8 @@ ocx combo set balanced \
 
 `reset-window` 会将每个请求路由到合格目标中，其缓存的提供商额度快照显示下一个窗口最早重置者（五小时、每周、每月或自定义窗口）。这样会优先消耗最先刷新额度的提供商。没有最新额度数据的目标以及并列目标会保持配置顺序。`weight` 和 `stickyLimit` 不影响此策略。
 
+此排序和发送前的提供商排除，需要适用于当前单个 API 密钥全部模型推理的最新限额信息。OAuth／当前账户摘要、转发调用方凭据的路由、多密钥以及凭据或目标地址已改变的快照，在这项提前判断中仅供显示。通过 `Authorization`、`x-api-key` 或 `x-goog-api-key` 请求头覆盖凭据时也适用相同规则；仅用于搜索或 MCP 的窗口不参与判断。如果所有符合条件的目标都没有适用的重置时间，则按配置顺序选择。实际账户选择和重试仍执行正常限制。
+
 ## 目标失败时会发生什么
 
 combo 失败分为 **跳转** 失败和 **终止** 失败。
@@ -209,9 +211,7 @@ combo 失败分为 **跳转** 失败和 **终止** 失败。
 
 打开本地 dashboard 并选择 **Models → Combos**。该工作区可以创建、编辑、重命名和删除 combo，其目标选择器会排除已禁用的模型和嵌套 combo。
 
-每个目标还会显示实时额度徽章：**可用**、**额度已用尽**或**额度未知**。只有当所有已启用目标都有最新、
-完整的额度耗尽证据时，保存和创建操作才会被禁用。缺失、过期、格式错误或聚合不完整的证据会保持为未知，
-绝不会锁定控件。额度恢复后，操作会自动重新启用。dashboard 编辑器目前还不能设置 `cooldownMs` 或 `waitForCooldownMs`；在后续 UI 完成前，请使用配置文件或管理 API。
+每个目标还会显示实时额度徽章：**可用**、**额度已用尽**或**额度未知**。只有当每个可用目标均有当前有效的服务器确认，表明其所配置凭据的推理限额已耗尽时，编辑器才会因额度而禁止保存和创建。仅供显示的账户、模型、搜索和 MCP 额度，以及缺失或已过期的路由依据，都不会触发此限制。此限制会在适用的重置时间或数据有效期结束时解除，并在页面变为活动或可见状态时重新检查；刷新会同时重新加载 Combo 数据和额度。dashboard 编辑器目前还不能设置 `cooldownMs` 或 `waitForCooldownMs`；在后续 UI 完成前，请使用配置文件或管理 API。
 
 ### CLI
 
diff --git a/docs-site/src/content/docs/zh-cn/guides/providers.md b/docs-site/src/content/docs/zh-cn/guides/providers.md
index 7f1e9f1205..94e8f4f99f 100644
--- a/docs-site/src/content/docs/zh-cn/guides/providers.md
+++ b/docs-site/src/content/docs/zh-cn/guides/providers.md
@@ -77,8 +77,9 @@ ChatGPT 透传目录也会加入 GPT-5.6 Sol/Terra/Luna 的裸 slug（`gpt-5.6-s
 
 有九个提供商预设使用 OAuth 登录，另加通过实验性非官方设备流桥接的 GitHub Copilot。
 opencodex 会把凭据存入 `~/.opencodex/auth.json`：可刷新的令牌会自动轮换；OrcaRouter
-这类持久密钥会复用到提供商撤销为止。登录 CLI 也接受 `chatgpt`：
-它会获取一份 ChatGPT 凭据，并创建一个 `forward` 模式的提供商条目。
+这类持久密钥会复用到提供商撤销为止。登录 CLI 也接受 `ocx login codex`，但它并不是上面这些提供商：
+它会转到 Codex 账号池登录（与 `ocx account login codex` 相同的流程）。该账号池有独立的账号台账，
+这条路径需要代理正在运行。`chatgpt` 和 `openai` 是同一条路径的别名。
 
 ```bash
 ocx login xai          # xAI Grok
@@ -90,8 +91,9 @@ ocx login google-antigravity
 ocx login cursor       # 独立的 Cursor PKCE 登录
 ocx login command-code # Command Code 浏览器 OAuth（或导入 ~/.commandcode/auth.json）
 ocx login orcarouter-oauth # OrcaRouter 浏览器授权 + PKCE
+ocx login devin       # Cognition/Devin 的 Auth0 浏览器登录
 ocx login github-copilot  # GitHub 设备流 → Copilot 令牌（Copilot Pro/Business）
-ocx login chatgpt      # 独立的 ChatGPT OAuth 登录
+ocx login codex        # Codex 账号池（别名：chatgpt、openai；需要代理正在运行）
 ocx logout <provider>
 ```
 
@@ -105,6 +107,8 @@ ocx logout <provider>
 | `google-antigravity` | `google` | `https://daily-cloudcode-pa.googleapis.com` | 通过 Cloud Code Assist 协议使用 Google OAuth。实时发现调用已认证的 CCA `v1internal:fetchAvailableModels` 端点，并仅发布当前登录账户可用的 agent 模型；维护中的目录仍作为回退。 |
 | `cursor` | `cursor` | `https://api2.cursor.sh` | 实验性 PKCE 登录、带可选 HTTP/1.1 兼容路径的 HTTP/2 传输，以及按账号筛选的模型发现。 |
 | `orcarouter-oauth` | `openai-chat` | `https://api.orcarouter.ai/v1` | 浏览器授权与密钥交换走 `https://www.orcarouter.ai` + S256 PKCE。交换结果是用户自己的普通 `sk-orca-…` API key，保存在现有凭据库中并持续复用，直到被撤销。 |
+| `devin` | `devin` | `https://server.codeium.com` | 实验性的非官方 Cognition/Devin 桥接。登录会打开 Auth0 浏览器页面，再用 `RegisterUser` 把令牌换成长期 API 密钥。模型列表按账号通过 `GetCascadeModelConfigs` 实时获取，流式仅走 Connect-RPC 上的 `runTurn` 路径。默认不在仪表盘预设中，需要手动启用。 |
+| `devin-cli` | `devin` | `https://server.codeium.com` | 导入本地已安装 Devin CLI 已持有的凭据（`devin auth login` 会写入它自己的 `credentials.toml`），随后与 `devin` 提供方一样通过 Cognition 的 Connect-RPC api-server 流式传输。无需浏览器登录，也无需粘贴密钥。模型列表与上下文窗口来自账号自身的目录。若要改用 CLI 自带的本地 agent 循环（ACP stdio），请用另取名称的条目并设置 `"adapter": "devin-cli"`。|
 | `github-copilot` | `openai-chat` | `https://api.githubcopilot.com` | 实验性。GitHub 设备流 + `copilot_internal` 交换（VS Code OAuth 客户端）。需要有效的 Copilot 订阅；不是官方第三方 API。 |
 
 Google Antigravity 账户和提供方的配额查询（包括模型列表回退）使用固定的 Google 计量端点。这些目标支持透明 Fake-IP DNS，同时保留 TLS 验证、重定向拒绝和私有地址检查。自定义 base URL 仅改变模型请求，不改变配额目标；`NO_PROXY` 仍使用直连策略。
@@ -240,7 +244,7 @@ Cline IDE/CLI 中提供，不能通过 API 使用；`minimax/minimax-m2.5` 是
 > 视频和 3D 资源，Coding 网关也会返回这份宽泛目录，Agent Plan 网关没有 `/models` 资源。
 > 按量付费默认使用 `doubao-seed-2-1-pro-260628`，静态目录还包含当前 DeepSeek 和 GLM
 > 文本模型。Coding Plan 默认使用 `ark-code-latest`，Agent Plan 默认使用
-> `deepseek-v4-pro`。
+> `deepseek-v4-flash`。
 
 **Chutes 发现：**`chutes` 预设使用 Chutes 固定的共享 OpenAI 兼容 LLM gateway。它读取公开的
 `/v1/models` 目录，仅保留 `supported_features` 包含 `tools` 的记录，保留含 `/` 的原生 model id 与
@@ -437,7 +441,7 @@ Cursor OAuth 和 live model discovery 已在这个实验性 adapter 中启用；
 
 ### Ollama Cloud
 
-Ollama Cloud 是托管（而非本地）的 Ollama，配置地址为 `https://ollama.com/v1`，密钥来自 [ollama.com/settings/keys](https://ollama.com/settings/keys)。opencodex 通过 Ollama 自身的 REST API（`POST /api/chat`）连接，而不是 OpenAI 兼容接口，并从提供方动态发现模型列表，因此新的 Ollama Cloud 模型无需改动配置即可出现。opencodex 按视觉能力对其云端阵容进行分类，使 [vision sidecar](/zh-cn/guides/sidecars/) 仅对纯文本模型生效。纯文本模型（例如 `glm-5.2`、`deepseek-v4-pro`、`gpt-oss`、`qwen3-coder`、`minimax-m2.x`、`nemotron-3-*`）列在 `noVisionModels` 中；原生支持视觉的模型（例如 `kimi-k2.6`、`minimax-m3`、`gemma4`、`qwen3.5`、`gemini-3-flash-preview`）则不在其中。匹配能容忍 Ollama 的 `:size` 标签，因此 `gpt-oss` 涵盖 `gpt-oss:120b` 和 `gpt-oss:20b`。
+Ollama Cloud 是托管（而非本地）的 Ollama，配置地址为 `https://ollama.com/v1`，密钥来自 [ollama.com/settings/keys](https://ollama.com/settings/keys)。opencodex 通过 Ollama 自身的 REST API（`POST /api/chat`）连接，而不是 OpenAI 兼容接口，并从提供方动态发现模型列表，因此新的 Ollama Cloud 模型无需改动配置即可出现。opencodex 按视觉能力对其云端阵容进行分类，使 [vision sidecar](/zh-cn/guides/sidecars/) 仅对纯文本模型生效。纯文本模型（例如 `glm-5.2`、`deepseek-v4-flash`、`gpt-oss`、`qwen3-coder`、`minimax-m2.x`、`nemotron-3-*`）列在 `noVisionModels` 中；原生支持视觉的模型（例如 `kimi-k2.6`、`minimax-m3`、`gemma4`、`qwen3.5`、`gemini-3-flash-preview`）则不在其中。匹配能容忍 Ollama 的 `:size` 标签，因此 `gpt-oss` 涵盖 `gpt-oss:120b` 和 `gpt-oss:20b`。
 
 Ollama 目前在文档中说明结构化输出在 Ollama Cloud 上不受支持。因此对正典 `ollama-cloud`，
 opencodex 会以明确的错误拒绝结构化输出请求（`text.format`），而不是悄悄返回不受约束的自由
diff --git a/docs-site/src/content/docs/zh-cn/guides/sidecars.md b/docs-site/src/content/docs/zh-cn/guides/sidecars.md
index f2dfec5c95..2ffeb8ff1e 100644
--- a/docs-site/src/content/docs/zh-cn/guides/sidecars.md
+++ b/docs-site/src/content/docs/zh-cn/guides/sidecars.md
@@ -69,7 +69,7 @@ OAuth 账户时使用 `anthropic`，否则使用 `openai`。显式选择 `anthro
 如果没有可用 plan，原始图像会被移除，而不会继续转发给纯文本后端。模型目录会为每个由 sidecar 覆盖的模型声明图像输入。
 只有当每个 combo 成员都能原生或通过 sidecar 接受图像、且 combo 的 `imageInput` 设置未禁用时，combo 才会声明图像输入；
 这样 Codex 应用等客户端会允许附件，而不会在 sidecar 运行前阻止它们。当 `visionSidecar.model` 缺失或为空时，OpenAI 执行路径、
-Dashboard 和管理 API 都使用 `gpt-5.4-mini` 作为回退。启动时仍会把明确保存的旧
+Dashboard 和管理 API 都使用 `gpt-5.6-luna` 作为回退。启动时仍会把明确保存的旧
 `gpt-5.4-mini` 值迁移到 `gpt-5.6-luna`；该迁移只作用于已保存值，不适用于缺失的 model 字段。
 
 - 图像可以来自 user、developer 和 tool-result message，也包括 Codex 的 `view_image` 结果。
@@ -113,7 +113,7 @@ Dashboard 和管理 API 都使用 `gpt-5.4-mini` 作为回退。启动时仍会
   "providers": {
     "ollama-cloud": {
       "baseUrl": "https://ollama.com/v1",
-      "noVisionModels": ["glm-5.2", "gpt-oss", "qwen3-coder", "deepseek-v4-pro"]
+      "noVisionModels": ["glm-5.2", "gpt-oss", "qwen3-coder", "deepseek-v4-flash"]
     }
   }
 }
diff --git a/docs-site/src/content/docs/zh-cn/guides/sub-agent-surface.md b/docs-site/src/content/docs/zh-cn/guides/sub-agent-surface.md
index c8c6bcba3d..b0d1dc6536 100644
--- a/docs-site/src/content/docs/zh-cn/guides/sub-agent-surface.md
+++ b/docs-site/src/content/docs/zh-cn/guides/sub-agent-surface.md
@@ -117,7 +117,7 @@ ocx v2 threads 8
 ocx agent status
 ocx agent injection set --model anthropic/claude-sonnet-5 --effort xhigh
 ocx agent subagents set gpt-5.6-sol,anthropic/claude-sonnet-5
-ocx agent fallback set gpt-5.4-mini,xai/grok-4.5 --poll-ms 60000
+ocx agent fallback set gpt-5.6-luna,xai/grok-4.5 --poll-ms 60000
 ocx agent effort set --subagent max
 ```
 
diff --git a/docs-site/src/content/docs/zh-cn/guides/web-dashboard.md b/docs-site/src/content/docs/zh-cn/guides/web-dashboard.md
index dbb6383120..62eaad0bc2 100644
--- a/docs-site/src/content/docs/zh-cn/guides/web-dashboard.md
+++ b/docs-site/src/content/docs/zh-cn/guides/web-dashboard.md
@@ -38,7 +38,7 @@ bun run dev:gui
 | **Windows 托盘** | 安装用户登录托盘，一键控制代理启动、停止、重启、面板和状态。托盘不是代理重启服务。 |
 | **Codex 自动启动** | 允许已安装的 Codex launcher shim 运行 `ocx ensure`。此开关不会安装 shim 或后台服务。 |
 | **Providers** | 添加、编辑、设为默认（仅已启用）、启用/禁用、删除 provider，并在支持时管理 OAuth 账号池和 API key 池。删除当前默认时，会切换到剩余的第一个已启用 provider（若存在）；否则拒绝删除并保留当前默认。Claude（Anthropic）OAuth 池中，每个已登录账号显示各自的 5 小时与周限额条（用量按凭证计）；探测失败时保留上次已知数值并标记为暂时不可用。 未选中任何 provider 时显示的 Providers 概览带有**刷新全部额度**按钮，会在服务端一次性重新读取所有已配置的 provider；上游探测失败的 provider 会保留上次已知数值，因此状态文案只表示检查已完成，而不声称每个数值都是最新的，各行自身的检查时间仍是该 provider 的新鲜度信号。 |
-| **Add provider** | 搜索 registry preset，选择账号登录、API key 服务、本地服务器或自定义 endpoint。 |
+| **Add provider** | 标签页上方的单个搜索框可同时搜索账号、免费、本地、付费四个标签页。搜索时选中的标签页不会跳转，结果按标签页分组并显示数量。本地运行时（Ollama、vLLM、LM Studio、LiteLLM）拥有独立标签页，过长的说明会截断为两行，点击即可查看全文。 |
 | **Codex Auth** | 添加 ChatGPT/Codex 池账号，选择下一 session 的账号，刷新 5h / 每周 / 30d 配额，启用或停用配额自动切换，设置其 1–100% 阈值和临时故障 failover。 |
 | **Subagents** | 在 `spawn_agent` override 列表中置顶最多五个原生或路由模型。 |
 | **Models** | 开关原生 GPT 与路由模型，配置 provider allowlist、上下文上限、v1/base/v2 以及 v2 thread 数量。 |
diff --git a/docs-site/src/content/docs/zh-cn/reference/adapters.md b/docs-site/src/content/docs/zh-cn/reference/adapters.md
index 61fab20c1f..730bf04aa6 100644
--- a/docs-site/src/content/docs/zh-cn/reference/adapters.md
+++ b/docs-site/src/content/docs/zh-cn/reference/adapters.md
@@ -194,6 +194,16 @@ Cursor 的 HTTP/1.1 兼容传输：通过 `agent.v1.AgentService/RunSSE` 接收
   executor，并绕过 Codex 审批和 sandbox 语义；旧的 `unsafeAllowNativeLocalExec: true` 仅在
   `nativeLocalExec` 未设置时等同。
 
+## `devin`
+
+**目标：** Cognition 的 `exa.api_server_pb.ApiServerService/GetChatMessage`（`server.codeium.com`，Connect 流式）。
+**认证：** 来自 `provider.apiKey` 或转发的 authorization 头的 Devin/Cognition API 密钥。登录会打开 Auth0 浏览器页面，再通过 `SeatManagementService.RegisterUser` 换取长期密钥。
+
+- 使用 `runTurn` 而非常规的 fetch/parse 路径。请求与服务端事件由 `devin/cloud-direct/wire.ts` 手写的 protobuf 分帧处理。
+- 通过 `GetCascadeModelConfigs` 按账号获取模型；不在套餐内的模型在列表阶段就被过滤，而不是到请求时才失败。
+- Cognition 对工具说明有长度上限和精确短语黑名单。适配器会改写已知短语并截断过长的说明。
+- 密钥不会刷新。失效后请重新执行 `ocx login devin`。
+
 ## `azure-openai`（别名：`azure`）
 
 **目标：** **Azure OpenAI**。封装 `openai-responses`，因此同样是 `passthrough: true`。
diff --git a/docs-site/src/content/docs/zh-cn/reference/cli/agents.md b/docs-site/src/content/docs/zh-cn/reference/cli/agents.md
index 89203420e9..f141dee649 100644
--- a/docs-site/src/content/docs/zh-cn/reference/cli/agents.md
+++ b/docs-site/src/content/docs/zh-cn/reference/cli/agents.md
@@ -132,7 +132,7 @@ ocx claude desktop import <path> [--apply]         Validate and import JSON
 
 ## Client config export
 
-### `ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|prime|aside|raycast>`
+### `ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|prime|aside|raycast|omo>`
 
 输出连接到正在运行代理的客户端配置。此命令会以所选客户端的原生格式序列化 `opencodex` provider 块，其中包含基础 URL、模型列表，以及该客户端适用的凭据引用或 `opencodex-loopback` 占位值。
 
@@ -140,7 +140,7 @@ ocx claude desktop import <path> [--apply]         Validate and import JSON
 
 | 标志 | 动作 |
 | --- | --- |
-| `--client <opencode\|pi\|omp\|hermes\|openclaw\|kimi\|gajae\|dsh\|mcode\|zcode\|prime\|aside\|raycast>` | 必需。选择客户端配置格式。 |
+| `--client <opencode\|pi\|omp\|hermes\|openclaw\|kimi\|gajae\|dsh\|mcode\|zcode\|prime\|aside\|raycast\|omo>` | 必需。选择客户端配置格式。 |
 | `--json` | 仅在 stdout 打印配置 JSON，这样重定向即可捕获字节级精确输出。包括 `--out` 写入提示在内的所有诊断信息都会输出到 stderr。 |
 | `--out <path>` | 将配置写入 `<path>`。拒绝替换已存在的文件。 |
 | `--force` | 允许 `--out` 替换已存在的文件。 |
@@ -167,7 +167,9 @@ ocx export --client opencode --out ~/opencodex-opencode.json
 | `mcode` | `~/.minimax/config.yaml` (设置后 `MINIMAX_DATA_DIR` 优先，其次是旧的 `MAVIS_DATA_DIR`；相对路径会被拒绝) | `mcode-config.yaml` | 无 — loopback placeholder |
 | `zcode` | `~/.zcode/v2/config.json` (设置后 `ZCODE_DATA_DIR` 优先；相对路径会被拒绝) | `config.json` | 无 — loopback placeholder |
 | `prime` | `~/.prime/agent/models.json` (设置后 `PRIME_AGENT_CODING_AGENT_DIR` 优先；相对路径会被拒绝) | `prime-models.json` | 无 — loopback placeholder |
+| `aside` | `~/.aside/u/<account>/models.json`，对应 Aside 自己的 `accounts.json` 指明的当前账户；清单不可读时会被拒绝，而不是退回到某个账户 | `aside-models.json` | 无 — loopback placeholder |
 | `raycast` | `~/.config/raycast/ai/providers.yaml`（macOS 与 Windows 相同；Raycast 不遵循 `XDG_CONFIG_HOME`） | `raycast-providers.yaml` | 无 — 仅限回环，不会写入 `api_keys` 条目 |
+| `omo` | `~/.omo/agent/models.json`（设置后依次由 `OMO_CODING_AGENT_DIR`、`SENPI_CODING_AGENT_DIR`、`PI_CODING_AGENT_DIR` 优先；相对路径会被拒绝） | `omo-models.json` | 无 — loopback placeholder |
 
 Raycast 导出是一份独立的 `providers.yaml` 文档，在 `providers` 序列中只有一个 `id: opencodex` 元素：`name: OpenCodex`、代理的 `/v1` 基础 URL，以及每个已路由模型及其 `abilities`（`tools` 与 `system_message` 始终支持，`vision` 取自目录的输入模态，`reasoning_effort` 在模型有 effort 阶梯时设置，`temperature` 对推理模型关闭）。Custom Providers 是 Raycast Pro 功能，且 Raycast 会监视该文件，因此保存后的更改无需重启即可生效。格式见 [manual.raycast.com/ai/custom-providers](https://manual.raycast.com/ai/custom-providers)。不会写入任何 `api_keys` 条目，所以该导出仅限回环，非回环绑定会被拒绝。
 
@@ -177,7 +179,7 @@ opencode 会插值 `{env:OPENCODEX_OPENCODE_API_KEY}`。opencodex 生成的 Pi 
 `ocx export` 从不写入你的真实客户端配置。该命令只会打印目标路径供你手动合并，而 `--out` 在没有 `--force` 的情况下拒绝覆盖已有文件，因为替换配置会破坏其中已有的其他 providers、agents 和 MCP 条目。
 :::
 
-任何密钥都不会被序列化。生成的配置里携带的要么是有文档记录的环境引用，要么是非机密的环回占位值。环回代理（`127.0.0.1`，默认值）根本不需要准入密钥。当代理绑定到环回地址之外时，请设置对应的 `OPENCODEX_OPENCODE_API_KEY`、`OPENCODEX_HERMES_API_KEY` 或 `OPENCODEX_OPENCLAW_API_KEY`。`OPENCODEX_GAJAE_API_KEY` 只会从环境中提供 Gajae provider 凭据，不能发送远程准入 header，因此生成的 Gajae 集成仍仅支持环回。关于准入密钥如何签发，请参见 [远程访问](/reference/configuration/#remote-access)。上游 providers 自身的密钥则完全是另一回事，需要按 [Providers](/guides/providers/) 单独配置。
+任何密钥都不会被序列化。生成的配置里携带的要么是有文档记录的环境引用，要么是非机密的环回占位值。环回代理（`127.0.0.1`，默认值）根本不需要准入密钥。当代理绑定到环回地址之外时，请设置对应的 `OPENCODEX_OPENCODE_API_KEY`、`OPENCODEX_HERMES_API_KEY` 或 `OPENCODEX_OPENCLAW_API_KEY`。`OPENCODEX_GAJAE_API_KEY` 只会从环境中提供 gjc provider 凭据，不能发送远程准入 header，因此生成的 gjc 集成仍仅支持环回。关于准入密钥如何签发，请参见 [远程访问](/reference/configuration/#remote-access)。上游 providers 自身的密钥则完全是另一回事，需要按 [Providers](/guides/providers/) 单独配置。
 
 同一份负载会通过 `GET /api/client-config` 提供，并在仪表盘的 API 选项卡中渲染，因此 CLI、API 和 GUI 使用的是同一字节内容。
 
diff --git a/docs-site/src/content/docs/zh-cn/reference/cli/providers-accounts.md b/docs-site/src/content/docs/zh-cn/reference/cli/providers-accounts.md
index a6fe332390..9d099c8c1b 100644
--- a/docs-site/src/content/docs/zh-cn/reference/cli/providers-accounts.md
+++ b/docs-site/src/content/docs/zh-cn/reference/cli/providers-accounts.md
@@ -63,9 +63,10 @@ ocx models live --provider ark --json
 打印当前可接受的 OAuth 和 API 密钥提供方 id。
 
 在 `ocx status` / `ocx doctor` 报告需要重新认证或终端刷新失败后，也可用同一条
-命令执行**重新认证**（或者在仪表盘中使用 Reauthenticate）。Codex 池账号不是一个
-公开的 `ocx login` 提供方 - 请通过仪表盘里的 Codex 账号池（Reauthenticate）或
-无头模式的 `ocx account reauth` 流程重新认证。
+命令执行**重新认证**（或者在仪表盘中使用 Reauthenticate）。Codex 池账号不是上面
+那些 OAuth / API key 提供方，但 `ocx login codex` 可以到达：它会转到账号池登录，
+因此 `ocx login codex --reauth` 与 `ocx account reauth codex` 等价。仪表盘里的
+Codex 账号池（Reauthenticate）同样可以。这条路径跑在代理内部，需要代理正在运行。
 
 ```bash
 ocx login xai
@@ -83,7 +84,7 @@ ocx login anthropic
 通过正在运行的代理列出并切换提供方账号和 API 密钥池。随附的帮助输出如下：
 
 ```text
-Usage: ocx account <list|current|use|refresh|auto-switch|priority|login|reauth|code|cancel|remove|add-key|reset-credits> ...
+Usage: ocx account <list|current|use|refresh|auto-switch|priority|login|reauth|code|cancel|remove|add-key|reset-credits|grok-reset-coupons> ...
 
 list [provider]     Codex account pool, OAuth accounts and API keys (identifiers shown masked as the API returns them).
 current <provider>  Show the active account or key.
@@ -95,6 +96,7 @@ remove <provider> <id> --yes  Remove a stored account or key after an existence
 add-key <provider> [--label <label>]  Add a key read only from piped stdin.
 login/reauth/code/cancel  Run browser or manual-code auth from a headless shell.
 reset-credits <id|main> [--consume --yes]  Inspect or consume Codex reset credits.
+grok-reset-coupons [<id>] [--consume --yes] [--token-id <token-id>] [--operation-id <uuid>]  Inspect or redeem Grok reset coupons.
 Codex pool selection applies to the next request after clearing existing affinity; in-flight requests keep their captured account.
 ```
 
@@ -172,11 +174,11 @@ token，也不是简单重读账号列表。`--json` 返回
 
 ### `ocx account auto-switch <provider> <on|off|status|threshold <0-100>> [--json]`
 
-控制 `openai` Codex 账户池阈值，或保存通用 OAuth 账户池阈值。`on` 保存 80%，`off` 保存 0%，`threshold <n>` 接受 0–100。通用池的阈值目前不参与运行；保存阈值不会启用阈值切换、改变提供方启用设置或禁用 429 错误后的轮换。通用池的查询和修改结果使用服务器确认值。通用池的 `poolEnabled` 是已保存的提供方设置，`null` 表示未指定，并不代表继承后的实际状态。`inert: true` 表示阈值未应用；能力未知时也不会报告 `enabled: true`。API 密钥提供方、Anthropic 和无效值会被拒绝。
+控制 `openai` Codex 账户池阈值，或保存通用 OAuth 账户池阈值。`on` 保存 80%，`off` 保存 0%，`threshold <n>` 接受 0–100。通用池的阈值只有在 `pool.kernel` 打开且 `strategy: "fill-first"` 时才参与选择；标志关闭时，保存阈值不会启用阈值切换。两种情况下都不会改变提供方启用设置或禁用 429 错误后的轮换。通用池的查询和修改结果使用服务器确认值。通用池的 `poolEnabled` 是已保存的提供方设置，`null` 表示未指定，并不代表继承后的实际状态。`inert: true` 表示阈值已保存但未应用，`inert: false` 表示账户池正在应用它。没有 `inert` 字段表示能力未知，此时同样不会报告 `enabled: true`。API 密钥提供方、Anthropic 和无效值会被拒绝。
 
 ```text
 openai: { provider, autoSwitchThreshold: number, enabled: boolean }
-generic OAuth: { provider, autoSwitchThreshold: number | null, enabled: boolean, poolEnabled: boolean | null, inert: true | null }
+generic OAuth: { provider, autoSwitchThreshold: number | null, enabled: boolean, poolEnabled: boolean | null, inert: boolean | null }
 ```
 
 ### `ocx account priority <provider> <account-id|main> [<-100..100|first|earlier|normal|later|last|reset>] [--json]`
@@ -242,6 +244,26 @@ security find-generic-password -w openrouter | ocx account add-key openrouter --
 查看某个账号的 Codex 重置额度。消耗额度会造成破坏性影响，因此同时需要 `--consume`
 和 `--yes`。
 
+### `ocx account grok-reset-coupons [<account-id>] [--consume --yes [--token-id <id>] [--operation-id <uuid>]] [--json]`
+
+检查或兑换 xAI / Grok 账号剩余的重置优惠券。
+
+不带 `--consume` 调用时，返回可用的优惠券 token 及其有效期窗口：
+
+```bash
+ocx account grok-reset-coupons
+ocx account grok-reset-coupons acc_xai_01 --json
+```
+
+兑换重置优惠券会改变计费状态，并永久消耗一个优惠券 token。`--consume` 严格要求同时提供 `--yes`：
+
+```bash
+ocx account grok-reset-coupons --consume --yes
+ocx account grok-reset-coupons --consume --yes --token-id <token-id>
+```
+
+传入 `--operation-id <uuid>`（必须是有效的 UUIDv4）可保证结算具备幂等性。当网络中断或命令重试时，相同的 operation id 会重放已持久化的结果，而不会再次消耗一个优惠券。
+
 ### `ocx account main <subcommand>`
 
 管理命名的原生 Codex 主登录配置文件，而不更改 OpenCodex 账号池路由。
diff --git a/docs-site/src/content/docs/zh-cn/reference/configuration/agents.md b/docs-site/src/content/docs/zh-cn/reference/configuration/agents.md
index 51558e2e11..094e6df720 100644
--- a/docs-site/src/content/docs/zh-cn/reference/configuration/agents.md
+++ b/docs-site/src/content/docs/zh-cn/reference/configuration/agents.md
@@ -71,9 +71,9 @@ opencodex 会跳过已禁用、不可路由、不健康、处于冷却中，或
   "injectionModel": "gpt-5.5",
   "injectionEffort": "high",
   "syncCodexSubagentDefaults": true,
-  "subagentModelFallback": ["gpt-5.4-mini"],
+  "subagentModelFallback": ["gpt-5.6-luna"],
   "subagentModelFallbackByModel": {
-    "gpt-5.5": ["gpt-5.4-mini"]
+    "gpt-5.5": ["gpt-5.6-luna"]
   },
   "subagentModelFallbackPollMs": 60000,
   "subagentEffortCap": "high"
diff --git a/docs-site/src/content/docs/zh-cn/reference/configuration/providers.md b/docs-site/src/content/docs/zh-cn/reference/configuration/providers.md
index 99fba1fbb4..9d0ed2dd76 100644
--- a/docs-site/src/content/docs/zh-cn/reference/configuration/providers.md
+++ b/docs-site/src/content/docs/zh-cn/reference/configuration/providers.md
@@ -36,8 +36,9 @@ ocx models provider openrouter on
 | `codexAccountPickerEnabled?` | `boolean` | 映射为空时关闭 | 控制是否根据有效的 `codexAccountNamespaces` 映射生成账户限定的 Codex 选择器行。`true` 允许显示映射行。在非空映射中省略此字段时，为保持向后兼容会视为已启用；映射为空时则关闭。`false` 会隐藏生成行并恢复选择器中的裸原生行，但不会删除映射，也不会禁用精确的 `<selector>/<native-openai-model>` 路由。 |
 | `activeCodexAccountId?` | `string` | — | 为下一次请求手动选定的 Pool 账户。选择会清除线程亲和性；进行中的请求会保留捕获到的凭据。 |
 | `codexAccountPriorities?` | `Record<string,number>` | — | Codex pool 各账号的选择顺序：账号 ID → `-100` 到 `100` 的整数，**数值越大越先使用**，未设置即为 `0`。这是顺序边界而非资格边界：选择会把已经合格的账号收窄到仍有 quota 余量的最高 tier，再由 `accountPoolStrategy` 在该 tier 内挑选。只有当某个 tier 的所有成员都超过 `autoSwitchThreshold`、处于 cooldown、被 soft-avoid、已暂停或需要重新认证时，该 tier 才会被跳过；usage 未知不会让 tier 耗尽。顺序不会让不合格的账号变得可选，也不会重新绑定已经绑定账号的 thread。主账号 `__main__` 同样参与排序，因此可以让 Codex Desktop 登录账号最后才被用到。没有任何条目时，行为与以往完全一致。映射格式非法时会打印警告并关闭排序（不会触发 config 修复）。可通过 `ocx account priority` 和 Codex Auth 页面管理。 |
-| `autoSwitchThreshold?` | `number` | `80` | 基于用量的主动切换阈值。`quota` 可在下一次请求中重新评估已绑定和未绑定任务；`fill-first` 仅把它用作未绑定分配的耗尽点；正常 `round-robin` 不使用它。分数取已知 5 小时、周或 30 天 quota window 的最高值。`0` 只关闭基于用量的主动切换，不关闭未绑定任务分配或故障恢复。 |
-| `accountPoolStrategy?` | `"quota" \| "round-robin" \| "fill-first"` | `"quota"` | 新建/未绑定 Codex 请求的分配策略。没有 live `(parent thread id, quota scope)` affinity 的请求属于未绑定；代理重启或 affinity 重置后，已有可见任务也可能未绑定。`quota` 在没有活跃账号时选择已知 usage 最低的合格账号；活跃账号合格且低于 `autoSwitchThreshold` 时继续使用；达到阈值后，可把未绑定请求或已绑定任务的下一次请求切换到 usage 更低的合格账号。`round-robin` 均匀分配未绑定请求；`fill-first` 在 cooldown、不可用或耗尽阈值前持续分配给活跃账号。 |
+| `autoSwitchThreshold?` | `number` | `80` | 基于用量的主动切换阈值。`quota` 可在下一次请求中重新评估未绑定任务；默认在用量越过该阈值时也会重新评估已绑定任务。开启 `pool.cacheAffinity` 后，已绑定任务在越过阈值后仍会保留账号，直到该账号耗尽或无法继续服务。`fill-first` 仅把它用作未绑定分配的耗尽点；正常 `round-robin` 不使用它。分数取已知 5 小时、周或 30 天 quota window 的最高值。`0` 只关闭基于用量的主动切换，不关闭未绑定任务分配或故障恢复。 |
+| `accountPoolStrategy?` | `"quota" \| "round-robin" \| "fill-first"` | `"quota"` | 新建/未绑定 Codex 请求的分配策略。没有 live `(parent thread id, quota scope)` affinity 的请求属于未绑定；代理重启或 affinity 重置后，已有可见任务也可能未绑定。`quota` 在没有活跃账号时选择已知 usage 最低的合格账号；活跃账号合格且低于 `autoSwitchThreshold` 时继续使用；达到阈值后，可把未绑定请求切换到 usage 更低的合格账号；未开启 `pool.cacheAffinity` 时，也可把已绑定任务的下一次请求切走。开启后，已绑定任务会保留到账号耗尽（已知 usage 为 100%）或无法继续服务。`round-robin` 均匀分配未绑定请求；`fill-first` 在 cooldown、不可用或耗尽阈值前持续分配给活跃账号。 |
+| `pool.cacheAffinity?` | `boolean` | `false` | 已绑定 Codex 线程的可选 cache-affinity 排序，独立于 `pool.kernel`。默认关闭；非法值视为关闭。开启后，live 绑定优先于 quota 余量：`quota` 不会仅因用量越过 `autoSwitchThreshold` 就移动线程。账号暂停、不可用或真正耗尽（已知 usage 为 100%）时仍会离开，因此 affinity 是重排而非钉死。 |
 | `accountPoolStickyLimit?` | `number` | `1` | 一次 round-robin 选择在推进前保留的新建/未绑定任务分配数。计数在任务绑定时增加，而不是在上游成功后增加。范围 1–100；仅当 `accountPoolStrategy` 为 `round-robin` 时生效。 |
 | `upstreamFailoverThreshold?` | `number` | `3` | 连续发生多少次瞬态故障后，后续新会话会切换到备用上游。设为 `0` 可禁用。对于常规 Responses 和原生 compact 发送，已证明的连接前 DNS/TCP 不可达故障按 provider-host 粒度记录，不影响账户健康、账户冷却、线程/会话亲和性、活动账户选择或 Pool 路由，也不会计入此阈值。 |
 | `upstreamHostCircuitThreshold?` | `number` | `0` | 原生 OpenAI forward Responses 与 compact 发送的可选断路器阈值，仅统计已证明的连接前 DNS/TCP 故障。`0` 表示禁用；`1`–`20` 表示在这么多个终止逻辑请求失败后，对 provider-origin 冷却 30 秒。断路期间会在账户选择和上游发送之前返回带 `Retry-After` 的 `503`；冷却结束后只允许一个半开请求。超时和 HTTP 响应不计数，任意 HTTP 响应都会关闭断路器。 仅适用于未固定账户的 Codex Pool 路由；在 `codexAccountMode: "direct"` 或使用账户限定选择器时不会启用。 |
@@ -122,6 +123,7 @@ selector，而不是分配一个新名称。
 | `noTopPModels?` | `string[]` | 会拒绝调用方指定 `top_p` 的模型。 |
 | `noPenaltyModels?` | `string[]` | 会拒绝 presence/frequency penalty 的模型。 |
 | `noStructuredOutputModels?` | `string[]` | `openai-chat` 端点拒绝 `response_format` 的精确模型 ID。仅当请求模型与条目完全匹配时才省略该字段；其他 `openai-chat` 模型仍启用 structured-output 转换。 |
+| `noJsonSchemaModels?` | `string[]` | `openai-chat` 端点拒绝 `json_schema` 形式但仍接受 `json_object` 的精确模型 ID。这类请求会降级为 `json_object` 而不是被丢弃，因此请求 JSON 的调用方仍能拿到 JSON。同一模型同时出现在两个列表时，以 `noStructuredOutputModels` 为准。`opencode go`、`opencode zen`、`opencode free` 预设已为其 DeepSeek 路由内置该项。 |
 | `parallelToolCalls?` | `boolean` | 切换并行工具调用。OpenAI Chat 默认开启；非 chat 适配器只有显式 `true` 时才会声明支持。 |
 | `responsesItemIdRepair?` | `{ message?: string[]; reasoning?: string[]; repairMissingTerminalIds?: boolean; repairInvalidIds?: boolean }` | 默认关闭的下游 SSE 修复，用于精确占位 id、缺失的终止 id，以及（`repairInvalidIds`）缺少规范 `msg_`/`rs_` 前缀的 message/reasoning id。function-call id 永远不会被重写。内置 DeepSeek 默认启用后两项。 |
 | `responsesSnapshotRepair?` | `boolean` | 默认关闭的客户端修复，用于补全 SSE 与 JSON 中稀疏 Responses 生命周期快照缺失的 status、output 和工具元数据；原始检查与持久化保持不变。 |
@@ -160,8 +162,9 @@ API key 提供者可以持有字面量 key，或环境引用。OAuth 提供者
 
 请在仪表盘 **Codex Auth** 页面添加 pool account 并刷新 quota。配置只保存非 secret account
 metadata；access/refresh token 存放在加固的 Codex account credential store 中。Pool routing
-分为新建/未绑定任务分配、基于用量的主动切换和故障恢复。已绑定任务通常保持 affinity，但 `quota`
-可在超过阈值后的下一次请求中重新绑定；暂停、cooldown、重新认证和故障处理也能独立清除或改变
+分为新建/未绑定任务分配、基于用量的主动切换和故障恢复。已绑定任务通常保持 affinity。默认情况下
+`quota` 可在超过阈值后的下一次请求中重新绑定；开启 `pool.cacheAffinity` 后，该重新绑定会等到
+绑定账号耗尽或无法继续服务。暂停、cooldown、重新认证和故障处理也能独立清除或改变
 routing。未绑定请求没有 live 账号绑定，也可能是代理重启或 affinity 重置后的已有任务。输出前的
 **429/402** 即使在关闭基于用量的主动切换时，也可在同一请求中对合格替代账号重试一次。
 账号变化后会保留并重放对话上下文，但账号间的 provider prompt cache 不保证复用，可能需要重新预热。
@@ -174,7 +177,7 @@ routing。未绑定请求没有 live 账号绑定，也可能是代理重启或
 并可将请求切换到另一个符合条件的 Pool 账户。即使 `autoSwitchThreshold: 0`，
 这些故障恢复流程仍然有效；`0` 只会禁用基于用量的主动切换。
 
-**分配与主动切换策略：** `quota`（默认）在没有活跃账号时选择 usage 最低的合格账号；活跃账号合格且低于 `autoSwitchThreshold` 时继续使用；达到阈值后，可把未绑定请求或已绑定任务的下一次请求切换到 usage 更低的合格账号。`round-robin` 均匀分配未绑定请求，用量
+**分配与主动切换策略：** `quota`（默认）在没有活跃账号时选择 usage 最低的合格账号；活跃账号合格且低于 `autoSwitchThreshold` 时继续使用；达到阈值后，可把未绑定请求切换到 usage 更低的合格账号；未开启 `pool.cacheAffinity` 时，也可把已绑定任务的下一次请求切走。开启后，cache affinity 优先于 quota 余量，已绑定任务会保留到账号耗尽（已知 usage 为 100%）或无法继续服务。`round-robin` 均匀分配未绑定请求，用量
 阈值不会改变正常轮换。`accountPoolStickyLimit`（默认 `1`，1–100）统计分配/绑定，而不是成功响应。
 `fill-first` 在 cooldown、重新认证或耗尽阈值前把未绑定请求分配给活跃账号；健康的已绑定任务保持
 affinity。这些策略不能规避 provider enforcement。
@@ -214,7 +217,7 @@ affinity。这些策略不能规避 provider enforcement。
 | `failureBackoffMaxSeconds?` | `number` | `3600` | 退避上限和永久故障延迟。 |
 | `codexWarmupEnabled?` | `boolean` | `false` | 启用合成的 Codex 池账户验证。 |
 | `codexWarmupMaxAgeSeconds?` | `number` | `691200` | 8 天后重新验证账户。 |
-| `codexWarmupModel?` | `string` | `gpt-5.4-mini` | 用于可选预热的原生模型。 |
+| `codexWarmupModel?` | `string` | `gpt-5.6-luna` | 用于可选预热的原生模型。 |
 
 ## 固定提供者端点
 
@@ -433,7 +436,7 @@ Vercel AI Gateway 可以在多个底层推理提供者之间路由一个模型
       "baseUrl": "https://ollama.com/v1",
       "apiKey": "${OLLAMA_API_KEY}",
       "defaultModel": "glm-5.2",
-      "noVisionModels": ["glm-5.2", "gpt-oss", "qwen3-coder", "deepseek-v4-pro"]
+      "noVisionModels": ["glm-5.2", "gpt-oss", "qwen3-coder", "deepseek-v4-flash"]
     }
   },
   "subagentModels": ["anthropic/claude-opus-5", "ollama-cloud/glm-5.2"],
diff --git a/docs-site/src/content/docs/zh-cn/reference/configuration/server.md b/docs-site/src/content/docs/zh-cn/reference/configuration/server.md
index 211e141650..4031f9ff19 100644
--- a/docs-site/src/content/docs/zh-cn/reference/configuration/server.md
+++ b/docs-site/src/content/docs/zh-cn/reference/configuration/server.md
@@ -167,7 +167,7 @@ routed 重放会把主 ChatGPT 认证注入内部请求。Anthropic 后端使用
 | --- | --- | --- | --- |
 | `enabled?` | `boolean` | 在可用时启用 | 图像描述总开关。 |
 | `backend?` | `"openai" \| "anthropic"` | auto | 显式值优先；未设置时优先使用可用的已保存 Anthropic OAuth 凭据，否则使用 `openai`。 |
-| `model?` | `string` | 依后端而定 | OpenAI 使用 `gpt-5.4-mini`，Anthropic 使用 `claude-sonnet-5`。 |
+| `model?` | `string` | 依后端而定 | OpenAI 使用 `gpt-5.6-luna`，Anthropic 使用 `claude-sonnet-5`。 |
 | `reasoning?` | `"low" \| "medium" \| "high" \| "xhigh" \| "max"` | `"low"` | OpenAI Responses 推理强度；Anthropic 会忽略该项。 |
 | `maxDescriptionsPerTurn?` | `number` | `8` | 每个主轮次允许的新增描述缓存未命中次数。`0` 会禁用调用；无效值会使用默认值。 |
 | `timeoutMs?` | `number` | `45000` | 侧车获取超时。整数 1–2147483647。 |
diff --git a/docs-site/src/content/docs/zh-cn/reference/management-api.md b/docs-site/src/content/docs/zh-cn/reference/management-api.md
index 9391afb5fd..84afe751a3 100644
--- a/docs-site/src/content/docs/zh-cn/reference/management-api.md
+++ b/docs-site/src/content/docs/zh-cn/reference/management-api.md
@@ -64,11 +64,19 @@ Authorization: Bearer <admin-token>
 | `GET /api/grok` | 读取 Grok 托管配置状态和候选模型 | 400 状态读取失败 |
 | `PUT /api/grok/selection` | 持久化被排除的 Grok 模型 | 400 选择无效或超出大小限制 |
 | `POST /api/grok/apply` | 通过托管同步应用已持久化的 Grok 配置 | 409 `grok_apply_busy`；400/500 应用失败 |
+| `GET /api/grok/reset-coupons?accountId=...` | 读取活跃或指定 xAI 账号剩余的 Grok 计费重置 token 及有效期窗口 | 400 缺少账号；401 未认证；502 上游 gRPC-Web 错误 |
+| `POST /api/grok/reset-coupons/consume` | 兑换一个符合条件的重置优惠券。请求体为 `{ accountId?, tokenId?, operationId? }`。可选的 `operationId`（UUIDv4）让兑换具备幂等性：重复相同 id 会重放持久化结果，而不会重复兑换。 | 400 无效的 JSON/UUID；401 未认证；409 `identity_mismatch`；502 上游错误；503 ledger 容量 |
 | `GET, PUT /api/claude-desktop` | 读取或持久化 Claude Desktop 的路由/原生配置文件 | 400 分配无效或不可用 |
 | `POST /api/claude-desktop/apply` | 将已保存的配置文件写入 Claude Desktop 的托管配置 | 400/500 写入失败 |
 | `GET /api/claude-desktop/status` | 检查已保存与已应用的配置文件以及 Desktop 健康状态 | 400 状态读取失败 |
 | `GET, PUT /api/claude-code` | 读取或更新 Claude Code 的网关、认证模式、模型映射、上下文、代理和 sidecar 设置 | 400 字段或结构无效 |
 
+仪表板从 **Providers > xAI Grok > Accounts** 驱动这两条优惠券路径：每个已登录账号行
+都带有显示剩余优惠券数量的票据徽章，该徽章会打开一个对话框，列出有效期窗口并兑换
+最接近到期的优惠券。该对话框会发送客户端生成的 `operationId`，并在超时后停止发送而不是
+重试，因为 journal 记录仍处于打开状态的兑换会再次执行。`ocx account grok-reset-coupons`
+仍然是对应的终端命令。
+
 关于模型名录和加密工作任务行为的概念，请参见 [子代理界面](/guides/sub-agent-surface/)。
 
 ### 客户端集成回滚日志
diff --git a/docs-site/src/content/docs/zh-cn/reference/proxy-formats.md b/docs-site/src/content/docs/zh-cn/reference/proxy-formats.md
index 8e3d4d8714..9f83638d3c 100644
--- a/docs-site/src/content/docs/zh-cn/reference/proxy-formats.md
+++ b/docs-site/src/content/docs/zh-cn/reference/proxy-formats.md
@@ -262,6 +262,8 @@ Responses 系列和 Chat 请求接受专用标头或 Bearer 字段中的代理
 
 没有密钥且不使用 OAuth 的 Cursor 路由可以使用调用方单独提供的 bearer，但不能使用代理 secret 或自动补充的 ChatGPT main 凭据。Combo/policy 选择以及实际发生的 shadow/thread-spawn 路由改写不会将调用方的原始凭据传递给新目标。规范 OpenAI 路由仅在 JWT 包含 ChatGPT 账户声明，且任何显式账户标头都与该声明匹配时，才可在内部路由变更后恢复调用方的单个非代理密钥 bearer。 向可选的 OpenAI sidecar 转发调用方认证时，需要单个 JWT 以及显式提供且匹配的 `chatgpt-account-id`。即使提供了显式账户标头，opaque bearer 也不会跨路由变更恢复。 除此之外，最终目标必须拥有自己的配置、OAuth 或已保存凭据，否则请求会在本地失败。只有 thread-spawn 标记而没有路由变化时，不会移除凭据。
 
+对于未配置密钥的 Cursor Chat 请求，只有实际计划了 OpenAI 辅助调用且存在规范的 Direct 候选时，才会补充已存储的 main 身份验证。无关的 Cursor 请求不会通过此流程占用 native main，因此不会延迟配置文件切换。辅助调用凭据仍受启动和切换保护限制，并与 Cursor bearer 分离。Pool 及明确指定账号的辅助调用保留现有账号选择。
+
 Claude replay 只会以当前 turn 已取得所有权的内存 snapshot 保留 main 凭据，并且仅在最终目标为规范 ChatGPT 路由时恢复它。
 
 :::caution
diff --git a/docs-site/src/content/docs/zh-tw/getting-started/quickstart.md b/docs-site/src/content/docs/zh-tw/getting-started/quickstart.md
index a7d0ca4e87..8236a6f511 100644
--- a/docs-site/src/content/docs/zh-tw/getting-started/quickstart.md
+++ b/docs-site/src/content/docs/zh-tw/getting-started/quickstart.md
@@ -73,7 +73,7 @@ codex -m "ollama-cloud/glm-5.2"      "Write a SQL migration"
 ## 選擇 sub-agent 模型（可選）
 
 新設定會讓 Codex 的 sub-agent 選擇器包含五個原生模型：`gpt-5.5`、`gpt-5.6-sol`、
-`gpt-5.6-terra`、`gpt-5.6-luna` 和 `gpt-5.4-mini`。開啟 `ocx gui` 即可替換或重新排序最多五個
+`gpt-5.6-terra`、`gpt-5.6-luna` 和 `gpt-6-astra`。開啟 `ocx gui` 即可替換或重新排序最多五個
 原生或已路由模型。儀表板也可以設定一個首選 sub-agent 模型及 reasoning effort。參見
 [子代理介面](/zh-tw/guides/sub-agent-surface/) 選擇 v1/base/v2，並了解指引、原生預設與回退
 何時生效。
diff --git a/docs-site/src/content/docs/zh-tw/guides/claude-code.md b/docs-site/src/content/docs/zh-tw/guides/claude-code.md
index 86a3ea0782..6df147ab6a 100644
--- a/docs-site/src/content/docs/zh-tw/guides/claude-code.md
+++ b/docs-site/src/content/docs/zh-tw/guides/claude-code.md
@@ -533,3 +533,5 @@ Claude 模型時自動載入。對於原生透傳，這是正常現象；對於
 
 **子代理派發到錯誤模型**——名冊代理（`ocx-*`）使用 `<!-- ocx-route: ... -->` 指令，
 而不是 Agent 工具的 `model` 引數。請確保指令與預期路由一致。傳入 `"haiku"` 作為模型佔位符。
+
+在 `config.json` 中設定 `claudeCode.stabilizePromptCache: true`，可在轉換路由上將系統指令末尾支援的 Claude 提示移到最後一則使用者訊息。預設值為 `false`。僅在用戶端允許這種角色變更時啟用。程式碼圍欄中的範例和不符合的文字會保留，Anthropic 原生轉送不變。沒有中繼資料時，快取鍵依穩定後的指令計算。此選項不會產生對話識別碼，也不保證上游快取命中。
diff --git a/docs-site/src/content/docs/zh-tw/guides/codex-app-models.md b/docs-site/src/content/docs/zh-tw/guides/codex-app-models.md
index 260ab7ad36..efe0dfb6ee 100644
--- a/docs-site/src/content/docs/zh-tw/guides/codex-app-models.md
+++ b/docs-site/src/content/docs/zh-tw/guides/codex-app-models.md
@@ -80,8 +80,8 @@ visibility = "list"
 
 ## 目前穩定模型涵蓋範圍
 
-原生回退列表包含 `gpt-5.5`、`gpt-5.4`、`gpt-5.4-mini`、
-`gpt-5.3-codex-spark` 以及 GPT-5.6 Sol/Terra/Luna。對於 GPT-5.5/5.4 系列，opencodex 會
+原生回退列表包含 `gpt-5.5`、
+`gpt-5.3-codex-spark` 以及 GPT-5.6 Sol/Terra/Luna。對於 GPT-5.5 系列，opencodex 會
 保留已安裝 Codex 目錄中資訊更完整的即時條目，僅在條目缺失時才合成。內建的上游快照只用於
 GPT-5.6，以便提供每個模型真實的身份和後設資料，而不是套用舊模板近似生成。
 
diff --git a/docs-site/src/content/docs/zh-tw/guides/codex-integration.md b/docs-site/src/content/docs/zh-tw/guides/codex-integration.md
index c9f8090987..0bf6a37426 100644
--- a/docs-site/src/content/docs/zh-tw/guides/codex-integration.md
+++ b/docs-site/src/content/docs/zh-tw/guides/codex-integration.md
@@ -319,7 +319,7 @@ ocx service install    # 常駐：登入時自動啟動，崩潰後自動重新
 
 ## Codex 帳號預熱
 
-新增或重新驗證帳號時，通常會在儲存前傳送小型模型請求並等待 `response.completed`。預設使用 `gpt-5.4-mini`，HTTP 400 或 HTTP 404 時改用 `gpt-5.5` 與 `gpt-5.6-luna` 重試。公開錯誤僅包含固定分類，不包含原始回應本文。
+新增或重新驗證帳號時，通常會在儲存前傳送小型模型請求並等待 `response.completed`。預設使用 `gpt-5.6-luna`，HTTP 400 或 HTTP 404 時改用 `gpt-5.5` 重試。公開錯誤僅包含固定分類，不包含原始回應本文。
 
 若新 OAuth 憑證的已驗證用量查詢確認5小時、每週或每月額度耗盡，則不呼叫模型而直接儲存帳號，顯示**等待驗證**。重新啟動或更新權杖也不會使其可用。額度恢復後重新整理額度：只有完整的最新用量顯示有餘額，才會傳送小型驗證請求；請求完成後帳號才可用於路由。查詢或驗證失敗將保留等待狀態。一般狀態輪詢不會傳送該請求。首次註冊時用量未知仍需一般預熱驗證。
 
@@ -341,7 +341,7 @@ ocx service install    # 常駐：登入時自動啟動，崩潰後自動重新
 ocx config set codexPool '{"excludedPlans":["free"]}'
 ```
 
-這是選擇策略，不是封鎖。被排除的帳號保留憑證、用量紀錄與執行緒親和性，仍顯示在帳號清單中，也仍可透過 `work/gpt-5.4` 這類明確選擇使用。改變的只是自動輪換不再挑它，包括它已經是使用中帳號或已綁定執行緒的情況——訂閱到期後留下的正是這種狀態。
+這是選擇策略，不是封鎖。被排除的帳號保留憑證、用量紀錄與執行緒親和性，仍顯示在帳號清單中，也仍可透過 `work/gpt-5.5` 這類明確選擇使用。改變的只是自動輪換不再挑它，包括它已經是使用中帳號或已綁定執行緒的情況——訂閱到期後留下的正是這種狀態。
 
 有兩處刻意的限制。主 Codex 帳號不會因方案被排除：僅選擇模式的路由不讀取受保護的原生憑證而隱去其方案，涵蓋主帳號的規則會自相矛盾。此外，當沒有未被排除的帳號時，被排除的帳號仍會回應而不是失敗；要完全停止服務，仍然是暫停所有帳號。沒有對應的 `minimumPlan`，因為為 ChatGPT 方案排序需要一個這裡並不存在的全序。
 
@@ -360,3 +360,9 @@ ocx restore back # 讓普通 Codex 再次指向仍在執行的 proxy
 當 opencodex 作為受管的 [背景服務](/zh-tw/reference/cli/#ocx-service) 執行時，會設定 `OCX_SERVICE=1`，
 因此 service 驅動的 restart **不會**反覆改寫 Codex 設定；只有明確執行 `ocx stop` 或
 `ocx service stop` 才會恢復原生 Codex。
+
+## 分頁歷史記錄安全拒絕
+
+如果受影響的歷史儲存區支援分頁，提供者切換可能傳回 `history_paginated_requires_native_writer`。OpenCodex 會保留目前設定、設定檔、模型目錄、歷史檔案及復原依據，而不在 Codex 之外分配序號；可遷移儲存區中的 legacy 記錄也受保護。不執行切換、僅保留外部提供者的路徑仍可使用。
+
+請勿刪除對話仍參照的提供者定義、反覆執行 `ocx sync` 或舊版復原，也不要改寫使用中的歷史檔案來繞過拒絕。保留檔案，復原前關閉相關對話，只回報確切錯誤與版本，不要公開私人歷史。需要與原生寫入器協調的已驗證修正。備份或指令碼成功不能證明顯示已復原；重新開啟 Codex 後確認對話。
diff --git a/docs-site/src/content/docs/zh-tw/guides/combos.md b/docs-site/src/content/docs/zh-tw/guides/combos.md
index bb8ef901f9..ce3ad70a94 100644
--- a/docs-site/src/content/docs/zh-tw/guides/combos.md
+++ b/docs-site/src/content/docs/zh-tw/guides/combos.md
@@ -154,6 +154,8 @@ ocx combo set balanced \
 
 `reset-window` 將每個請求路由至快取供應商配額快照顯示下一個時段最早重設的合格目標（五小時、每週、每月或自訂）。這會優先使用最早重新取得額度的供應商。沒有最新配額資料的目標，以及發生平手時，皆維持設定順序。`weight` 與 `stickyLimit` 不影響此策略。
 
+此排序與傳送前的供應商排除，需要適用於目前單一 API 金鑰全部模型推論的最新限額資訊。OAuth／目前帳戶摘要、轉送呼叫者憑證的路由、多金鑰，以及憑證或目的地位址已變更的快照，在這項預先判斷中僅供顯示。透過 `Authorization`、`x-api-key` 或 `x-goog-api-key` 標頭覆寫憑證時也適用相同規則；僅供搜尋或 MCP 使用的時段不參與判斷。若所有符合條件的目標都沒有適用的重設時間，則依設定順序選擇。實際帳戶選擇與重試仍套用一般限制。
+
 ## 目標失敗時會發生什麼
 
 Combo 失敗分為**跳轉**失敗與**終端**失敗。
@@ -217,9 +219,7 @@ Codex v2 子代理有一個重要限制（[issue #92](https://github.com/lidge-j
 
 開啟本機儀表板並選擇 **Combos**。該工作區可建立、編輯、重新命名與移除 combo，且其目標 picker 會排除已停用的模型與巢狀 combo。
 
-每個目標也會顯示即時額度徽章：**可用**、**額度已用盡**或**額度未知**。只有當所有已啟用目標都有最新、
-完整的額度耗盡證據時，儲存與建立操作才會停用。缺失、過期、格式錯誤或聚合不完整的證據會維持未知，
-絕不會鎖住控制項。額度恢復後，操作會自動重新啟用。
+每個目標也會顯示即時額度徽章：**可用**、**額度已用盡**或**額度未知**。只有當每個可用目標均有目前有效的伺服器確認，顯示其所設定憑證的推論限額已耗盡時，編輯器才會因配額而停用儲存與建立。僅供顯示的帳戶、模型、搜尋與 MCP 配額，以及缺失或已過期的路由依據，都不會觸發此限制。此限制會在適用的重設時間或資料有效期限結束時解除，並在頁面變為作用中或可見狀態時重新檢查；重新整理會同時重新載入 Combo 資料與配額。
 
 ### CLI
 
diff --git a/docs-site/src/content/docs/zh-tw/guides/integrations.md b/docs-site/src/content/docs/zh-tw/guides/integrations.md
index cd767e0a9b..9d8252b279 100644
--- a/docs-site/src/content/docs/zh-tw/guides/integrations.md
+++ b/docs-site/src/content/docs/zh-tw/guides/integrations.md
@@ -1,9 +1,9 @@
 ---
 title: 整合
-description: 從儀表板把 opencodex 連接到 OpenCode、Pi、OMP、Hermes、OpenClaw、Kimi Code、Gajae Code、DeepSeek Harness、MiniMax Code、ZCode、Prime Agent、Aside 與 Raycast——每個客戶端一個開關，每次寫入前都會先備份。
+description: 從儀表板把 opencodex 連接到 OpenCode、Pi、OMP、Hermes、OpenClaw、Kimi Code、gjc、DeepSeek Harness、MiniMax Code、ZCode、Prime Agent、Aside、Raycast 與 omo——每個客戶端一個開關，每次寫入前都會先備份。
 ---
 
-**整合（Integrations）** 分頁會把 opencodex 的 provider 區塊寫入客戶端自己的設定檔，也會把它移除。共有十三個客戶端以這種方式運作，每個都有一個開關：
+**整合（Integrations）** 分頁會把 opencodex 的 provider 區塊寫入客戶端自己的設定檔，也會把它移除。共有十五個客戶端以這種方式運作，每個都有一個開關：
 
 | 客戶端 | 設定檔 | 格式 | 變更生效時機 | 憑證 |
 |---|---|---|---|---|
@@ -13,13 +13,15 @@ description: 從儀表板把 opencodex 連接到 OpenCode、Pi、OMP、Hermes、
 | Hermes | `~/.hermes/config.yaml` | YAML | 新 sessions | `OPENCODEX_HERMES_API_KEY` |
 | OpenClaw | `~/.openclaw/openclaw.json` | JSON5 | 立即，在執行中的 gateway 上 | `OPENCODEX_OPENCLAW_API_KEY` |
 | Kimi Code | `~/.kimi-code/config.toml` | TOML | 重新啟動時，或 `/reload` | loopback 佔位符 |
-| Gajae Code | `~/.gjc/agent/models.yml` | YAML | 新 sessions，或當你開啟 `/model` 時 | `OPENCODEX_GAJAE_API_KEY` |
+| gjc | `~/.gjc/agent/models.yml` | YAML | 新 sessions，或當你開啟 `/model` 時 | `OPENCODEX_GAJAE_API_KEY` |
 | DeepSeek Harness (DSH) | `$DSH_HOME/settings.yaml`（預設 `~/.dsh/settings.yaml`） | YAML | 熱重載 | 非秘密的 loopback bearer 佔位符 |
 | MiniMax Code | `~/.minimax/config.yaml` | YAML | 新 sessions，或開啟模型選擇器後 | loopback 佔位符 |
 | Prime Agent | `~/.prime/agent/models.json` | JSON | 新 sessions | loopback 佔位符 |
 | ZCode | `~/.zcode/v2/config.json` | JSON | 重新啟動時 | loopback 佔位符 |
 | Aside | `~/.aside/u/<account>/models.json` | JSON | 完全結束並重新開啟 Aside 後 | loopback 佔位符 |
 | Raycast | `~/.config/raycast/ai/providers.yaml` | YAML | 儲存後立即生效——Raycast 會監看該檔案 | 無——僅限 loopback |
+| omo | `~/.omo/agent/models.json` | JSON | 新工作階段 | loopback 佔位符 |
+| Cline CLI | `~/.cline/data/settings/providers.json` + `models.json` | JSON | 結束並重新啟動後 | 僅限 loopback |
 
 受管理 DSH 支援的相容性下限是 **DSH 0.1.0-rc.6**。OpenCodex 只擁有
 `llm-pi-ai.providers.opencodex`：Apply 與 Refresh 會取代該片段，Disable 只移除該片段，
@@ -80,7 +82,7 @@ opencodex 從自己的環境讀取這些變數。如果你的 gateway 以 profil
 - **Restore this point…** 會出現在較舊的操作上，或當檔案在那次操作之後有變更時。跨過這樣的變更做回復會再詢問一次，才覆蓋你的較新編輯——並且也會備份它們，所以那次的回復本身也可以復原。
 - 每個客戶端保留十份備份。超過之後，最舊的快照檔案會被移除，其歷史列顯示為 **Backup expired**。
 
-停用只移除 opencodex 記錄為自己寫入的條目。如果你的檔案在我們寫入之後有變更，後續行為取決於我們自己的條目是否完好，以及檔案的格式。對於嚴格 JSON 設定檔（OpenCode、Pi），在我們的區塊**旁邊**進行的編輯——例如新增 MCP 伺服器或你自己的 provider——會顯示為**需要更新**：重新整理會在保留你的條目的前提下合併寫入，但格式可能會被正規化。例外情況是 JSON 無法精確重寫的內容——例如 `1e999` 這類非有限數字、重寫會被四捨五入的數字（極大的整數，或小到會塌縮成零的數字）、`-0`、同一個物件裡重複出現的鍵，或巢狀層數超過 1000 層——此時開關會鎖定，確保沒有任何值被悄悄改動或刪除。**OMP、DSH 與 Hermes** 同樣不受旁邊編輯影響，但原因不同：它們的 writer 只逐位元組修補自己的 `providers.opencodex` 範圍，檔案其餘部分從不會被重寫。至於其餘可以包含註解的格式（OpenClaw、Kimi Code、Gajae Code、MiniMax Code、Raycast——以整份文件寫出的 YAML、JSON5 與 TOML），或當我們自己的條目被編輯過時，開關會鎖定，停用會拒絕執行，而不是猜測哪些編輯是你的。
+停用只移除 opencodex 記錄為自己寫入的條目。如果你的檔案在我們寫入之後有變更，後續行為取決於我們自己的條目是否完好，以及檔案的格式。對於嚴格 JSON 設定檔（OpenCode、Pi），在我們的區塊**旁邊**進行的編輯——例如新增 MCP 伺服器或你自己的 provider——會顯示為**需要更新**：重新整理會在保留你的條目的前提下合併寫入，但格式可能會被正規化。例外情況是 JSON 無法精確重寫的內容——例如 `1e999` 這類非有限數字、重寫會被四捨五入的數字（極大的整數，或小到會塌縮成零的數字）、`-0`、同一個物件裡重複出現的鍵，或巢狀層數超過 1000 層——此時開關會鎖定，確保沒有任何值被悄悄改動或刪除。**OMP、DSH 與 Hermes** 同樣不受旁邊編輯影響，但原因不同：它們的 writer 只逐位元組修補自己的 `providers.opencodex` 範圍，檔案其餘部分從不會被重寫。至於其餘可以包含註解的格式（OpenClaw、Kimi Code、gjc、MiniMax Code、Raycast——以整份文件寫出的 YAML、JSON5 與 TOML），或當我們自己的條目被編輯過時，開關會鎖定，停用會拒絕執行，而不是猜測哪些編輯是你的。
 
 ## 誠實的預期
 
@@ -90,7 +92,7 @@ opencodex 從自己的環境讀取這些變數。如果你的 gateway 以 profil
 
 TOML 日期與時間值也會阻止自動重寫：合併步驟會將這些帶有型別的值轉成加引號的字串，陣列和行內表格中的值也一樣。原本就加引號的日期字串仍受支援；若要保留不加引號的日期型別，請手動編輯設定。
 
-**Pi、Kimi Code、Gajae Code、MiniMax Code 與受管理 DSH 整合只能對 loopback bind 運作。** 前四者的設定沒有非 loopback bind 所需的 `x-opencodex-api-key` header 欄位。DSH 雖然提供通用 headers map，但 rc.6 並未把這個專用准入 header 記錄為受支援的整合契約，因此受管理 writer 會選擇安全拒絕，而不自行猜測。請改用 SSH tunnel，或由本機 forwarder 加上該 header 後再以 loopback 存取。
+**Pi、Kimi Code、gjc、MiniMax Code 與受管理 DSH 整合只能對 loopback bind 運作。** 前四者的設定沒有非 loopback bind 所需的 `x-opencodex-api-key` header 欄位。DSH 雖然提供通用 headers map，但 rc.6 並未把這個專用准入 header 記錄為受支援的整合契約，因此受管理 writer 會選擇安全拒絕，而不自行猜測。請改用 SSH tunnel，或由本機 forwarder 加上該 header 後再以 loopback 存取。
 
 **產生的 OMP 整合也刻意只支援 loopback。** OMP 確實支援 provider 層級的 headers，但這個最初的整合不會發出遠端 `x-opencodex-api-key` 憑證連線。手動的遠端 OMP 設定目前不在受管理的整合範圍內。
 
@@ -127,8 +129,8 @@ ocx mcode
 ```
 
 完成一次連接後，`ocx sync` 與 `POST /api/sync` 會更新 OpenCodex 已擁有的
-MCode、Pi、Aside 與 Raycast 目錄。proxy 啟動也會更新已擁有的 Raycast 目錄。
-模型可見性、provider 或 preset 變更會更新 Pi、Aside 與 Raycast。若區塊已刪除、
+MCode、Pi、Aside、Raycast 與 omo 目錄。proxy 啟動也會更新已擁有的 Raycast 目錄。
+模型可見性、provider 或 preset 變更會更新 Pi、Aside、Raycast 與 omo。若區塊已刪除、
 遭外部修改、不安全或由你手動移除，sync 會保持原檔不動；只有在你確定要重新
 連接時才再次執行 enable。
 
@@ -147,3 +149,15 @@ OAuth 或 API key，並拒絕 `--api-key`、`--base-url` 與 `--region` 覆寫
 `--confirm-drift` 永遠不會被擅自假設。如果檔案在你正要回復的操作之後有變更，指令會拒絕並告訴你，因為覆蓋你較新的編輯是你的決定。
 
 客戶端細節是針對各專案自己的設定格式驗證過的；檢查了什麼、何時檢查，請見 `devlog/_fin/260802_client_toggle_api/002_client_toggle_matrix.md` 中的研究筆記。
+
+## Cline CLI
+
+Cline CLI 使用 providers.json 與 models.json。修改或同步前請結束 Cline，完成後重新啟動。復原會還原兩個原始檔案，預設供應商保持不變。此整合不會遷移舊版 VS Code 擴充功能的儲存資料。
+
+```bash
+ocx integration client enable --client cline
+ocx integration client history --client cline
+ocx integration client restore --op <operation-id>
+```
+
+[CLI / rollback / CLINE_PROVIDER_SETTINGS_PATH](/guides/integrations/#cline-cli).
diff --git a/docs-site/src/content/docs/zh-tw/guides/providers.md b/docs-site/src/content/docs/zh-tw/guides/providers.md
index 1b189cd91b..63b2eeaeb8 100644
--- a/docs-site/src/content/docs/zh-tw/guides/providers.md
+++ b/docs-site/src/content/docs/zh-tw/guides/providers.md
@@ -84,8 +84,9 @@ ChatGPT passthrough catalog 也會加入 GPT-5.6 Sol/Terra/Luna 的裸 slug：`g
 ## 2. 帳號登入（OAuth）
 
 有八個 provider preset 使用 OAuth 登入，另加透過實驗性非官方 device-flow bridge 的 GitHub Copilot。
-opencodex 會把 credential 存在 `~/.opencodex/auth.json` 並自動 refresh。登入 CLI 也接受 `chatgpt`；
-它會取得 ChatGPT credential，同時建立 `forward` 模式的 provider 條目。
+opencodex 會把 credential 存在 `~/.opencodex/auth.json` 並自動 refresh。登入 CLI 也接受 `ocx login codex`，
+但它不是上面的 provider：它會轉到 Codex 帳號池登入（與 `ocx account login codex` 相同的流程）。該帳號池
+有獨立的帳號 ledger，這條路徑需要 proxy 正在執行。`chatgpt` 與 `openai` 是同一條路徑的別名。
 
 ```bash
 ocx login xai          # xAI Grok
@@ -96,8 +97,9 @@ ocx login kiro         # 匯入 kiro-cli credential（或 token fallback）
 ocx login google-antigravity
 ocx login cursor       # 獨立 Cursor PKCE 登入
 ocx login command-code # Command Code browser OAuth（或匯入 ~/.commandcode/auth.json）
+ocx login devin       # Cognition/Devin 的 Auth0 瀏覽器登入
 ocx login github-copilot  # GitHub device flow → Copilot token（Copilot Pro/Business）
-ocx login chatgpt      # 獨立 ChatGPT OAuth 登入
+ocx login codex        # Codex 帳號池（別名：chatgpt、openai；需要 proxy 正在執行）
 ocx logout <provider>
 ```
 
@@ -110,6 +112,8 @@ ocx logout <provider>
 | `kiro` | `kiro` | `https://runtime.us-east-1.kiro.dev` | 初次登入會匯入已安裝且已登入的 `kiro-cli` session。Unix 可用 `curl -fsSL https://cli.kiro.dev/install` &#124; `bash` 安裝；Windows PowerShell 使用 `irm 'https://cli.kiro.dev/install.ps1'` &#124; `iex`，再執行 `kiro-cli login`。**Add account** 會先登出 `kiro-cli`、啟動新的 browser login，切換 `kiro-cli` 所使用的帳號並保存 account-scoped profile metadata。既有 OpenCodex 帳號會保留；取消或失敗時會恢復先前的 `kiro-cli` session。 |
 | `google-antigravity` | `google` | `https://daily-cloudcode-pa.googleapis.com` | 透過 Cloud Code Assist wire 使用 Google OAuth。即時探索使用 CCA 經認證的 `v1internal:fetchAvailableModels` 端點，發布目前登入帳號可用的 agent 模型；維護中的 catalog 作為 fallback。 |
 | `cursor` | `cursor` | `https://api2.cursor.sh` | 實驗性 PKCE 登入、即時 HTTP/2 transport 與按帳號篩選的模型探索。 |
+| `devin` | `devin` | `https://server.codeium.com` | 實驗性的非官方 Cognition/Devin 橋接。登入會開啟 Auth0 瀏覽器頁面，再以 `RegisterUser` 將權杖換成長期 API 金鑰。模型清單依帳號透過 `GetCascadeModelConfigs` 即時取得，串流僅走 Connect-RPC 上的 `runTurn` 路徑。預設不在儀表板預設集內，需手動啟用。 |
+| `devin-cli` | `devin` | `https://server.codeium.com` | 匯入本機已安裝 Devin CLI 已持有的憑證（`devin auth login` 會寫入它自己的 `credentials.toml`），接著與 `devin` 提供者一樣透過 Cognition 的 Connect-RPC api-server 串流。不需瀏覽器登入，也不需貼上金鑰。模型清單與內容視窗來自帳號自身的目錄。若要改用 CLI 自帶的本機 agent 迴圈（ACP stdio），請使用另取名稱的項目並設定 `"adapter": "devin-cli"`。|
 | `github-copilot` | `openai-chat` | `https://api.githubcopilot.com` | 實驗性。GitHub device flow + `copilot_internal` exchange（VS Code OAuth client）。需要有效 Copilot 訂閱；不是官方第三方 API。 |
 
 Google Antigravity 帳戶與供應商的配額查詢（包括模型清單備援）使用固定的 Google 計量端點。這些目標支援透明 Fake-IP DNS，同時保留 TLS 驗證、重新導向拒絕與私有位址檢查。自訂 base URL 只改變模型請求，不改變配額目標；`NO_PROXY` 仍使用直連政策。
@@ -184,7 +188,8 @@ credential。caller 沒有送出時，opencodex **不會**捏造官方 client id
 **診斷與重新認證。** 一般 `ocx status` 會印出 OAuth health 區塊，只顯示遮蔽後 account id，不含 token。
 `ocx doctor` 會新增 OAuth reliability 區段，包含 writable-store／single-flight check，以及帶 recovery
 Action 的 WARN row。OAuth provider 帳號需要重新認證時，執行 `ocx login <provider>`，或在儀表板使用
-Reauthenticate。Codex pool 帳號不是 `ocx login` provider，請透過儀表板 Codex account pool 重新認證。
+Reauthenticate。Codex pool 帳號不是那些 provider 之一，但 `ocx login codex --reauth` 會轉到它們的帳號池
+重新認證，儀表板的 Codex account pool 也做同一件事。
 相關命令請參見 CLI 參考的 [`ocx status` / `ocx doctor`](/zh-tw/reference/cli/)。
 
 ### Kiro credential 匯入
@@ -318,7 +323,7 @@ incomplete 關閉，不會被誤報為成功。
 > pay-as-you-go 費用。preset 使用 curated static model catalog，因為 Ark `/models` 也包含 embedding、
 > image、video 與 3D resource，Coding gateway 會回傳相同 broad catalog，而 Agent Plan gateway 沒有
 > `/models` resource。Pay-as-you-go 預設 `doubao-seed-2-1-pro-260628`，curated catalog 也包含目前的
-> DeepSeek 與 GLM text model。Coding Plan 預設 `ark-code-latest`；Agent Plan 預設 `deepseek-v4-pro`。
+> DeepSeek 與 GLM text model。Coding Plan 預設 `ark-code-latest`；Agent Plan 預設 `deepseek-v4-flash`。
 
 > **Volcengine Plan 使用限制：** Volcengine 文件指出 Coding Plan 與 Agent Plan quota 只能在受支援的
 > AI coding tool 內使用，並警告把 plan key 用於一般 API call 可能導致訂閱停權或帳號封鎖。透過
@@ -505,7 +510,7 @@ key 來自 [ollama.com/settings/keys](https://ollama.com/settings/keys)。openco
 REST API（`POST /api/chat`）連線，而非 OpenAI-compatible 介面，並向 provider 動態探索模型清單，
 因此新的 Ollama Cloud 模型不需改設定就會出現。opencodex 依 vision capability 分類其
 cloud lineup，讓 [vision sidecar](/zh-tw/guides/sidecars/) 只對純文字模型生效。純文字模型，例如
-`glm-5.2`、`deepseek-v4-pro`、`gpt-oss`、`qwen3-coder`、`minimax-m2.x`、`nemotron-3-*`，會列在
+`glm-5.2`、`deepseek-v4-flash`、`gpt-oss`、`qwen3-coder`、`minimax-m2.x`、`nemotron-3-*`，會列在
 `noVisionModels`；原生 vision 模型，例如 `kimi-k2.6`、`minimax-m3`、`gemma4`、`qwen3.5`、
 `gemini-3-flash-preview`，不會列入。matching 可容忍 Ollama 的 `:size` tag，因此 `gpt-oss` 同時涵蓋
 `gpt-oss:120b` 與 `gpt-oss:20b`。
diff --git a/docs-site/src/content/docs/zh-tw/guides/sidecars.md b/docs-site/src/content/docs/zh-tw/guides/sidecars.md
index 60131afd19..97c073d3ba 100644
--- a/docs-site/src/content/docs/zh-tw/guides/sidecars.md
+++ b/docs-site/src/content/docs/zh-tw/guides/sidecars.md
@@ -70,7 +70,7 @@ OAuth 帳號時使用 `anthropic`，否則使用 `openai`。明確選擇 `anthro
 只有當每個 combo 成員都能原生或透過 sidecar 接受圖像，且 combo 的 `imageInput` 設定未停用時，combo 才會宣告圖像輸入；
 如此 Codex 應用程式等用戶端會允許附件，而不會在 sidecar 執行前阻擋它們。Dashboard 和管理 API 目前顯示的預設值是
 `gpt-5.6-luna`，啟動時也會把明確儲存的舊 `gpt-5.4-mini` 值遷移到 Luna。只有在
-`visionSidecar.model` 欄位不存在或為空字串時，vision 執行路徑才會使用程式碼中的 `gpt-5.4-mini` 回退值。
+`visionSidecar.model` 欄位不存在或為空字串時，vision 執行路徑才會使用程式碼中的 `gpt-5.6-luna` 回退值。
 
 - 圖像可以來自 user、developer 和 tool-result message，也包括 Codex 的 `view_image` 結果。
 - 每張圖像會以 `reasoning.effort: "low"` 傳送給設定的原生 vision 模型，描述結果會就地替換
@@ -108,7 +108,7 @@ OAuth 帳號時使用 `anthropic`，否則使用 `openai`。明確選擇 `anthro
   "providers": {
     "ollama-cloud": {
       "baseUrl": "https://ollama.com/v1",
-      "noVisionModels": ["glm-5.2", "gpt-oss", "qwen3-coder", "deepseek-v4-pro"]
+      "noVisionModels": ["glm-5.2", "gpt-oss", "qwen3-coder", "deepseek-v4-flash"]
     }
   }
 }
diff --git a/docs-site/src/content/docs/zh-tw/guides/sub-agent-surface.md b/docs-site/src/content/docs/zh-tw/guides/sub-agent-surface.md
index 59be70f24d..b18e2d34c1 100644
--- a/docs-site/src/content/docs/zh-tw/guides/sub-agent-surface.md
+++ b/docs-site/src/content/docs/zh-tw/guides/sub-agent-surface.md
@@ -215,7 +215,7 @@ opencodex 會將磁碟上的模型目錄與目前使用者擁有的每個 Codex
 
 | 模型 | 線路上的 `max` | 選擇 `ultra` 後的線路值 |
 | --- | --- | --- |
-| gpt-5.5、gpt-5.4、gpt-5.4-mini | xhigh | xhigh（先轉為 max，再經 `nativeEffortClamp`） |
+| gpt-5.5 | xhigh | xhigh（先轉為 max，再經 `nativeEffortClamp`） |
 | gpt-5.6-sol、gpt-5.6-terra | max | max |
 | gpt-5.6-luna | max | 其精確上游階梯不提供該選項 |
 | 路由模型 | 由適配器對映或限制 | 先轉為 max，再由適配器對映或限制 |
diff --git a/docs-site/src/content/docs/zh-tw/guides/web-dashboard.md b/docs-site/src/content/docs/zh-tw/guides/web-dashboard.md
index 358624f2f9..3b7005fd76 100644
--- a/docs-site/src/content/docs/zh-tw/guides/web-dashboard.md
+++ b/docs-site/src/content/docs/zh-tw/guides/web-dashboard.md
@@ -43,7 +43,7 @@ GUI session 簽發到服務的頁面中，並在到期或代理重啟時靜默
 | **Windows 托盤** | 安裝使用者登入托盤，一鍵控制代理啟動、停止、重啟、面板和狀態。托盤不是代理重啟服務。 |
 | **Codex 自動啟動** | 允許已安裝的 Codex launcher shim 執行 `ocx ensure`。此開關不會安裝 shim 或後臺服務。 |
 | **Providers** | 新增、編輯、啟用/停用、刪除 provider，並在支援時管理 OAuth 帳號池和 API key 池。 |
-| **Add provider** | 搜尋 registry preset，選擇帳號登入、API key 服務、本機伺服器或自訂 endpoint。 |
+| **Add provider** | 分頁上方的單一搜尋框可同時搜尋帳號、免費、本機、付費四個分頁。搜尋時選取的分頁不會跳轉，結果依分頁分組並顯示數量。本機執行環境（Ollama、vLLM、LM Studio、LiteLLM）有專屬分頁，過長的說明會截斷為兩行，點擊即可查看全文。 |
 | **Codex Auth** | 新增 ChatGPT/Codex 池帳號，選擇下一 session 的帳號，重新整理 5h / 每週 / 30d 配額，啟用或停用配額自動切換，設定其 1–100% 閾值和臨時故障 failover。 |
 | **Subagents** | 在 `spawn_agent` override 列表中置頂最多五個原生或路由模型。 |
 | **Models** | 開關原生 GPT 與路由模型，設定 provider allowlist、上下文上限、v1/base/v2 以及 v2 thread 數量。 |
diff --git a/docs-site/src/content/docs/zh-tw/reference/adapters.md b/docs-site/src/content/docs/zh-tw/reference/adapters.md
index c74a22304a..6fe65246b0 100644
--- a/docs-site/src/content/docs/zh-tw/reference/adapters.md
+++ b/docs-site/src/content/docs/zh-tw/reference/adapters.md
@@ -166,6 +166,16 @@ Kiro 的 assistant 文字本身沒有可靠的回合結束標記，但終止的
   executor，並繞過 Codex 審批和 sandbox 語義；舊的 `unsafeAllowNativeLocalExec: true` 僅在
   `nativeLocalExec` 未設定時等效。
 
+## `devin`
+
+**目標：** Cognition 的 `exa.api_server_pb.ApiServerService/GetChatMessage`（`server.codeium.com`，Connect 串流）。
+**認證：** 來自 `provider.apiKey` 或轉送 authorization 標頭的 Devin/Cognition API 金鑰。登入會開啟 Auth0 瀏覽器頁面，再透過 `SeatManagementService.RegisterUser` 換取長期金鑰。
+
+- 使用 `runTurn` 而非一般的 fetch/parse 路徑。請求與伺服器事件由 `devin/cloud-direct/wire.ts` 手寫的 protobuf 分幀處理。
+- 以 `GetCascadeModelConfigs` 依帳號取得模型；方案未涵蓋的模型在清單階段就被濾除。
+- Cognition 對工具說明設有長度上限與完全比對的封鎖清單。轉接器會改寫已知語句並截斷過長說明。
+- 金鑰不會更新。失效後請重新執行 `ocx login devin`。
+
 ## `azure-openai`（別名：`azure`）
 
 **目標：** **Azure OpenAI**。封裝 `openai-responses`，因此同樣是 `passthrough: true`。
diff --git a/docs-site/src/content/docs/zh-tw/reference/cli/agents.md b/docs-site/src/content/docs/zh-tw/reference/cli/agents.md
index d04c099ebf..d9585b2520 100644
--- a/docs-site/src/content/docs/zh-tw/reference/cli/agents.md
+++ b/docs-site/src/content/docs/zh-tw/reference/cli/agents.md
@@ -130,7 +130,7 @@ ocx claude desktop import <path> [--apply]         驗證並匯入 JSON
 
 ## 客戶端設定匯出
 
-### `ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|prime|aside|raycast>`
+### `ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|prime|aside|raycast|omo>`
 
 印出連接到執行中代理的客戶端設定。此指令會用所選客戶端的原生格式，序列化含有 base URL、模型清單，以及適用的環境變數參考或 loopback 佔位符的 `opencodex` provider 區塊。
 
@@ -138,7 +138,7 @@ ocx claude desktop import <path> [--apply]         驗證並匯入 JSON
 
 | 旗標 | 動作 |
 | --- | --- |
-| `--client <opencode\|pi\|omp\|hermes\|openclaw\|kimi\|gajae\|dsh\|mcode\|zcode\|prime\|aside\|raycast>` | 必填。選擇客戶端設定格式。 |
+| `--client <opencode\|pi\|omp\|hermes\|openclaw\|kimi\|gajae\|dsh\|mcode\|zcode\|prime\|aside\|raycast\|omo>` | 必填。選擇客戶端設定格式。 |
 | `--json` | 僅在 stdout 印出設定 JSON，使重導向能擷取逐位元組輸出。所有診斷訊息（含 `--out` 寫入提示）皆送至 stderr。 |
 | `--out <path>` | 將設定寫入 `<path>`。拒絕覆寫既有檔案。 |
 | `--force` | 允許 `--out` 覆寫既有檔案。 |
@@ -165,7 +165,9 @@ ocx export --client opencode --out ~/opencodex-opencode.json
 | `mcode` | `~/.minimax/config.yaml` (設定後 `MINIMAX_DATA_DIR` 優先，其次為舊的 `MAVIS_DATA_DIR`；相對路徑會被拒絕) | `mcode-config.yaml` | 無——loopback 佔位符 |
 | `zcode` | `~/.zcode/v2/config.json` (設定後 `ZCODE_DATA_DIR` 優先；相對路徑會被拒絕) | `config.json` | 無——loopback 佔位符 |
 | `prime` | `~/.prime/agent/models.json` (設定後 `PRIME_AGENT_CODING_AGENT_DIR` 優先；相對路徑會被拒絕) | `prime-models.json` | 無——loopback 佔位符 |
+| `aside` | `~/.aside/u/<account>/models.json`，對應 Aside 自己的 `accounts.json` 指定的目前帳戶；資訊清單無法讀取時會被拒絕，而不是退回任一帳戶 | `aside-models.json` | 無——loopback 佔位符 |
 | `raycast` | `~/.config/raycast/ai/providers.yaml`（macOS 與 Windows 相同；Raycast 不遵循 `XDG_CONFIG_HOME`） | `raycast-providers.yaml` | 無——僅限 loopback，不會寫入 `api_keys` 項目 |
+| `omo` | `~/.omo/agent/models.json`（設定後依序由 `OMO_CODING_AGENT_DIR`、`SENPI_CODING_AGENT_DIR`、`PI_CODING_AGENT_DIR` 優先；相對路徑會被拒絕） | `omo-models.json` | 無——loopback 佔位符 |
 
 Raycast 匯出是一份獨立的 `providers.yaml` 文件，在 `providers` 序列中只有一個 `id: opencodex` 元素：`name: OpenCodex`、proxy 的 `/v1` base URL，以及每個路由模型及其 `abilities`（`tools` 與 `system_message` 一律支援，`vision` 依目錄的輸入模態而定，`reasoning_effort` 在模型有 effort 階梯時設定，`temperature` 對推理模型關閉）。Custom Providers 是 Raycast Pro 功能，且 Raycast 會監看該檔案，因此儲存後的變更不需重新啟動即可生效。格式說明見 [manual.raycast.com/ai/custom-providers](https://manual.raycast.com/ai/custom-providers)。不會寫入任何 `api_keys` 項目，所以此匯出僅限 loopback，非 loopback 的 bind 會被拒絕。
 
@@ -180,7 +182,7 @@ opencode 會插值 `{env:OPENCODEX_OPENCODE_API_KEY}`。Pi 與 OMP 的匯出不
 
 金鑰永不被序列化。設定只帶有文件化的環境變數參考，或非秘密的 loopback 佔位符。loopback 代理（`127.0.0.1`，預設值）完全不需要准入金鑰。只有客戶端 schema 支援、且代理綁定超出 loopback 時，才設定被引用的變數；關於准入金鑰的簽發方式，請見[遠端存取](/zh-tw/reference/configuration/#remote-access)。上游 provider 本身的金鑰是完全不同的事，依[供應商](/zh-tw/guides/providers/)個別設定。
 
-Gajae 是例外：`OPENCODEX_GAJAE_API_KEY` 只會從環境提供 provider 憑證，但其 schema 無法傳送遠端准入 header，因此產生的 Gajae 整合仍僅支援 loopback。
+gjc 是例外：`OPENCODEX_GAJAE_API_KEY` 只會從環境提供 provider 憑證，但其 schema 無法傳送遠端准入 header，因此產生的 gjc 整合仍僅支援 loopback。
 
 相同的 payload 亦由 `GET /api/client-config` 提供，並在儀表板的 API 分頁渲染，因此 CLI、API 與 GUI 使用相同的位元組。
 
diff --git a/docs-site/src/content/docs/zh-tw/reference/cli/providers-accounts.md b/docs-site/src/content/docs/zh-tw/reference/cli/providers-accounts.md
index fbf1ff186c..0e3bbe4b78 100644
--- a/docs-site/src/content/docs/zh-tw/reference/cli/providers-accounts.md
+++ b/docs-site/src/content/docs/zh-tw/reference/cli/providers-accounts.md
@@ -44,7 +44,7 @@ ocx models live --provider ark --json
 
 啟動供應商已註冊的登入流程。OAuth 供應商會開啟瀏覽器並在 `~/.opencodex/` 下儲存自動重新整理的憑證；API-key 登入供應商會開啟其金鑰儀表板、提示輸入金鑰、在可能時驗證它，並儲存產生的供應商設定。當名稱缺失或未知時，指令會印出目前接受的 OAuth 與 API-key 供應商 id。
 
-在 `ocx status` / `ocx doctor` 回報需要重新認證或終端 refresh 失敗後，請使用相同指令**重新認證**（或在儀表板中使用 Reauthenticate）。Codex pool 帳號不是公開的 `ocx login` 供應商——請改由儀表板 Codex 帳號池（Reauthenticate）或無頭的 `ocx account reauth` 流程重新認證。
+在 `ocx status` / `ocx doctor` 回報需要重新認證或終端 refresh 失敗後，請使用相同指令**重新認證**（或在儀表板中使用 Reauthenticate）。Codex pool 帳號不是上面那些 OAuth／API key 供應商，但 `ocx login codex` 可以到達：它會轉到帳號池登入，所以 `ocx login codex --reauth` 等同於 `ocx account reauth codex`。儀表板的 Codex 帳號池（Reauthenticate）也可以。這條路徑跑在 proxy 內部，需要 proxy 正在執行。
 
 ```bash
 ocx login xai
@@ -62,7 +62,7 @@ ocx login anthropic
 透過執行中的代理列出並切換供應商帳號與 API-key 池。隨附的說明介面如下：
 
 ```text
-Usage: ocx account <list|current|use|refresh|auto-switch|login|reauth|code|cancel|remove|add-key|reset-credits> ...
+Usage: ocx account <list|current|use|refresh|auto-switch|login|reauth|code|cancel|remove|add-key|reset-credits|grok-reset-coupons> ...
 
 list [provider]     Codex 帳號池、OAuth 帳號與 API 金鑰（識別碼依 API 回傳遮罩顯示）。
 current <provider>  顯示現用帳號或金鑰。
@@ -73,6 +73,7 @@ remove <provider> <id> --yes  在存在檢查後移除已儲存的帳號或金
 add-key <provider> [--label <label>]  僅從 piped stdin 讀取並新增金鑰。
 login/reauth/code/cancel  從無頭 shell 執行瀏覽器或手動 code 認證。
 reset-credits <id|main> [--consume --yes]  檢查或消耗 Codex reset credits。
+grok-reset-coupons [<id>] [--consume --yes] [--token-id <token-id>] [--operation-id <uuid>]  檢查或兌換 Grok reset coupons。
 Codex 池選擇套用於清除既有親和性後的下一個請求；進行中的請求保留其擷取的帳號。
 ```
 
@@ -132,11 +133,11 @@ Codex 池選擇套用於清除既有親和性後的下一個請求；進行中
 
 ### `ocx account auto-switch <provider> <on|off|status|threshold <0-100>> [--json]`
 
-控制 `openai` Codex 帳戶池閾值，或儲存通用 OAuth 帳戶池閾值。`on` 儲存 80%，`off` 儲存 0%，`threshold <n>` 接受 0–100。通用池的閾值目前不參與執行；儲存閾值不會啟用閾值切換、改變供應商啟用設定或停用 429 錯誤後的輪替。通用池的查詢與修改結果使用伺服器確認值。通用池的 `poolEnabled` 是已儲存的供應商設定，`null` 表示未指定，並不代表繼承後的實際狀態。`inert: true` 表示閾值未套用；能力未知時也不會回報 `enabled: true`。API 金鑰供應商、Anthropic 與無效值會被拒絕。
+控制 `openai` Codex 帳戶池閾值，或儲存通用 OAuth 帳戶池閾值。`on` 儲存 80%，`off` 儲存 0%，`threshold <n>` 接受 0–100。通用池的閾值只有在 `pool.kernel` 開啟且 `strategy: "fill-first"` 時才參與選擇；旗標關閉時，儲存閾值不會啟用閾值切換。兩種情況下都不會改變供應商啟用設定或停用 429 錯誤後的輪替。通用池的查詢與修改結果使用伺服器確認值。通用池的 `poolEnabled` 是已儲存的供應商設定，`null` 表示未指定，並不代表繼承後的實際狀態。`inert: true` 表示閾值已儲存但未套用，`inert: false` 表示帳戶池正在套用它。沒有 `inert` 欄位表示能力未知，此時同樣不會回報 `enabled: true`。API 金鑰供應商、Anthropic 與無效值會被拒絕。
 
 ```text
 openai: { provider, autoSwitchThreshold: number, enabled: boolean }
-generic OAuth: { provider, autoSwitchThreshold: number | null, enabled: boolean, poolEnabled: boolean | null, inert: true | null }
+generic OAuth: { provider, autoSwitchThreshold: number | null, enabled: boolean, poolEnabled: boolean | null, inert: boolean | null }
 ```
 
 ### `ocx account login|reauth|code|cancel ...`
@@ -167,6 +168,26 @@ security find-generic-password -w openrouter | ocx account add-key openrouter --
 
 檢查帳號的 Codex reset credits。消耗 credit 是破壞性的，需要同時提供 `--consume` 與 `--yes`。
 
+### `ocx account grok-reset-coupons [<account-id>] [--consume --yes [--token-id <id>] [--operation-id <uuid>]] [--json]`
+
+檢查或兌換 xAI / Grok 帳號剩餘的 reset coupons。
+
+未加上 `--consume` 呼叫時，回傳可用的 coupon token 與其有效期間：
+
+```bash
+ocx account grok-reset-coupons
+ocx account grok-reset-coupons acc_xai_01 --json
+```
+
+兌換 reset coupon 會改變計費狀態，並永久消耗一個 coupon token。`--consume` 嚴格要求同時提供 `--yes`：
+
+```bash
+ocx account grok-reset-coupons --consume --yes
+ocx account grok-reset-coupons --consume --yes --token-id <token-id>
+```
+
+傳入 `--operation-id <uuid>`（必須是有效的 UUIDv4）可保證結算具備冪等性。當網路中斷或命令重試時，相同的 operation id 會重播已持久化的結果，而不會再消耗一個 coupon。
+
 ### `ocx account priority <provider> <account-id|main> [<-100..100|first|earlier|normal|later|last|reset>] [--json]`
 
 讀取或設定某個 Codex pool account 的選擇順序：**數值越高越早使用**，預設為 `0`，範圍是
@@ -259,7 +280,7 @@ Preview 建置使用 `<OPENCODEX_HOME>/native-main-profiles`。該配置絕不
 | `provider <name> <on\|off>` | `--json` | 在單次寫入中啟用或停用一個供應商的所有模型。 |
 | `selected <provider>` | `--set <id,id...>`, `--clear`, `--json` | 讀取或替換供應商模型允許清單。`--clear` 移除允許清單，使每個模型都被提供。 |
 | `context <status\|value <tokens>\|provider <name> <on\|off>\|all <on\|off>>` | `--json` | 讀取或設定 context-window 上限，全域或 per 供應商。 |
-| `shadow <status\|set> [model\|-]` | `--enabled <on\|off>`, `--json` | 讀取或設定 Codex 背景 helper 呼叫的替換模型。`-` 清除模型。`status` 亦回報 `sourceModels`，即代理攔截的 helper slug（預設：`gpt-5.4-mini` 與 `gpt-5.6-luna`）。 |
+| `shadow <status\|set> [model\|-]` | `--enabled <on\|off>`, `--json` | 讀取或設定 Codex 背景 helper 呼叫的替換模型。`-` 清除模型。`status` 亦回報 `sourceModels`，即代理攔截的 helper slug（預設：`gpt-5.6-luna`；0.144.x 以前的用戶端使用已退役的 `gpt-5.4-mini`，可透過 `sourceModels` 還原）。 |
 
 ```bash
 ocx models live --json                                  # Codex 目前實際可見的模型
diff --git a/docs-site/src/content/docs/zh-tw/reference/configuration/agents.md b/docs-site/src/content/docs/zh-tw/reference/configuration/agents.md
index 4fb07c6d29..d3fdf7059b 100644
--- a/docs-site/src/content/docs/zh-tw/reference/configuration/agents.md
+++ b/docs-site/src/content/docs/zh-tw/reference/configuration/agents.md
@@ -59,7 +59,7 @@ opencodex 會跳過已停用、不可路由、不健康、冷卻中或達到配
   "injectionModel": "gpt-5.5",
   "injectionEffort": "high",
   "syncCodexSubagentDefaults": true,
-  "subagentModelFallback": ["gpt-5.4-mini"],
+  "subagentModelFallback": ["gpt-5.6-luna"],
   "subagentModelFallbackPollMs": 60000,
   "subagentEffortCap": "high"
 }
diff --git a/docs-site/src/content/docs/zh-tw/reference/configuration/providers.md b/docs-site/src/content/docs/zh-tw/reference/configuration/providers.md
index 74ee860ff1..ff67793990 100644
--- a/docs-site/src/content/docs/zh-tw/reference/configuration/providers.md
+++ b/docs-site/src/content/docs/zh-tw/reference/configuration/providers.md
@@ -34,8 +34,9 @@ ocx models provider openrouter on
 | `pausedCodexAccountIds?` | `string[]` | `[]` | 被排除於池選擇直到恢復的帳號，包含暫停時的 main `__main__` 帳號。 |
 | `codexAccountNamespaces?` | `Record<string, string>` | — | 公開模型選擇器命名空間到已儲存 Codex 帳號目標。這會驗證並持久化映射，但不會自行新增 picker 列或變更路由。 |
 | `activeCodexAccountId?` | `string` | — | 為下一個請求手動選擇的池帳號。選擇清除執行緒親和性；進行中的請求保留擷取的憑證。 |
-| `autoSwitchThreshold?` | `number` | `80` | 主動切換的用量閾值。`quota` 可在其下一個請求時重新評估綁定與未綁定任務；`fill-first` 僅將其用作未綁定指派的排空點；一般 `round-robin` 選擇不使用它。分數使用最熱的已知 5h、週或 30d 配額視窗。`0` 僅停用基於用量的主動切換，而非未綁定指派或失敗復原。 |
-| `accountPoolStrategy?` | `"quota" \| "round-robin" \| "fill-first"` | `"quota"` | 新／未綁定 Codex 請求的指派策略。當請求沒有即時（父執行緒 id、配額 scope）親和性時即為未綁定；可見的既有任務在代理重啟或親和性重置後可變為未綁定。`quota` 在無現用帳號時選擇最低用量的合格帳號，將合格現用帳號保持在 `autoSwitchThreshold` 以下，且在閾值後可將未綁定請求或主動重新綁定綁定任務到較低用量的合格帳號。`round-robin` 均勻分配未綁定請求；`fill-first` 持續將未綁定請求指派到現用帳號直到冷卻、不可用或設定的排空閾值。 |
+| `autoSwitchThreshold?` | `number` | `80` | 主動切換的用量閾值。`quota` 可在下一個請求時重新評估未綁定任務，且預設在用量越過此閾值時也會重新評估綁定任務。開啟 `pool.cacheAffinity` 後，綁定任務在越過閾值後仍會保留帳號，直到該帳號耗盡或無法繼續服務。`fill-first` 僅將其用作未綁定指派的排空點；一般 `round-robin` 選擇不使用它。分數使用最熱的已知 5h、週或 30d 配額視窗。`0` 僅停用基於用量的主動切換，而非未綁定指派或失敗復原。 |
+| `accountPoolStrategy?` | `"quota" \| "round-robin" \| "fill-first"` | `"quota"` | 新／未綁定 Codex 請求的指派策略。當請求沒有即時（父執行緒 id、配額 scope）親和性時即為未綁定；可見的既有任務在代理重啟或親和性重置後可變為未綁定。`quota` 在無現用帳號時選擇最低用量的合格帳號，將合格現用帳號保持在 `autoSwitchThreshold` 以下，且在閾值後可將未綁定請求移至較低用量的合格帳號；未開啟 `pool.cacheAffinity` 時，也可主動重新綁定綁定任務。開啟後，綁定任務會保留到帳號耗盡（已知用量 100%）或無法繼續服務。`round-robin` 均勻分配未綁定請求；`fill-first` 持續將未綁定請求指派到現用帳號直到冷卻、不可用或設定的排空閾值。 |
+| `pool.cacheAffinity?` | `boolean` | `false` | 綁定 Codex 執行緒的選擇性 cache-affinity 排序，獨立於 `pool.kernel`。預設關閉；格式錯誤視為關閉。開啟後，即時綁定優先於配額餘裕：`quota` 不會只因用量越過 `autoSwitchThreshold` 就移動執行緒。帳號暫停、無法使用或真正耗盡（已知用量 100%）時仍會離開，因此親和性是重排而非釘死。 |
 | `accountPoolStickyLimit?` | `number` | `1` | 在前進一個 round-robin 選擇前保留的新／未綁定任務指派；計數器在任務綁定時前進，而非在上游成功後。範圍 1–100。 |
 | `upstreamFailoverThreshold?` | `number` | `3` | 未來新 session 容錯移轉前的連續暫時性失敗。設 `0` 停用。 |
 | `modelCacheTtlMs?` | `number` | `300000` | Per-供應商 `/models` 快取的新鮮度視窗。 |
@@ -96,6 +97,7 @@ ocx models provider openrouter on
 | `noTopPModels?` | `string[]` | 拒絕呼叫者指定 `top_p` 的模型。 |
 | `noPenaltyModels?` | `string[]` | 拒絕 presence/frequency penalty 的模型。 |
 | `noStructuredOutputModels?` | `string[]` | 其 `openai-chat` 端點拒絕 `response_format` 的精確模型 ID。僅精確符合的請求模型會省略該欄位；structured-output 轉譯對其他每個 `openai-chat` 模型保持啟用。 |
+| `noJsonSchemaModels?` | `string[]` | 其 `openai-chat` 端點拒絕 `json_schema` 形式但仍接受 `json_object` 的精確模型 ID。這類請求會降級為 `json_object` 而非被丟棄，因此要求 JSON 的呼叫端仍會拿到 JSON。同一模型同時列在兩份清單時，以 `noStructuredOutputModels` 為準。`opencode go`、`opencode zen`、`opencode free` 預設已為其 DeepSeek 路由內建。 |
 | `parallelToolCalls?` | `boolean` | 切換平行工具呼叫。OpenAI Chat 預設開啟；非 chat adapter 僅在明確 `true` 時廣告。 |
 | `responsesItemIdRepair?` | `{ message?: string[]; reasoning?: string[]; repairMissingTerminalIds?: boolean }` | 預設停用的下游 SSE 修復，用於精確佔位 id 與缺失的終端 id。Function-call id 永不被重寫。 |
 | `transientRetryOn5xx?` | `{ enabled?: boolean; attempts?: number }` | 僅限使用金鑰認證的 `openai-chat` 供應商。選擇性重試串流開始前的暫時性上游狀態（500、502、503、504、520、521、522）：未設定時停用；只要有此物件即啟用，除非 `enabled: false`。涵蓋初始 `Responses` 請求、終止防護續接、原生 `/v1/chat/completions`，以及 429／帳號復原的重新擷取。`attempts` 是單一請求允許傳送至上游的總次數，包含第一次（1..10，預設 3）；這是與連線重設復原共用的單一請求範圍預算，因此 `3` 表示最多只有三個實際請求會送達供應商。等待採固定 400 毫秒、上限 5 秒的指數退避，並遵循 `Retry-After`。此機制獨立於處理速率限制的 `retryOn429`；串流中的失敗絕不重播。 |
@@ -128,7 +130,7 @@ API-key 供應商可持有字面值金鑰或環境參考。OAuth 供應商使用
 
 ## Codex 帳號池
 
-在儀表板中使用 **Codex Auth** 新增池帳號並重新整理配額。`config.json` 儲存非秘密中繼資料；access 與 refresh token 使用強化的憑證存放。池路由將新／未綁定指派、基於用量的主動切換與失敗復原分開。綁定任務通常保留親和性，但 `quota` 可在其超過用量閾值後的下一個請求時重新綁定它，而暫停、冷卻、重新認證與失敗處理可獨立清除或移動路由。未綁定請求沒有即時帳號綁定；這可包含代理重啟或親和性重置後的既有可見任務。Pre-stream 的 429 或 402 在同一個請求中於一個合格的備用帳號上重試一次，即使基於用量的主動切換關閉。帳號變更保留並重播對話 context，但跨帳號的供應商端 prompt-cache 重用不保證，cache 可能需要重新暖機。
+在儀表板中使用 **Codex Auth** 新增池帳號並重新整理配額。`config.json` 儲存非秘密中繼資料；access 與 refresh token 使用強化的憑證存放。池路由將新／未綁定指派、基於用量的主動切換與失敗復原分開。綁定任務通常保留親和性。預設下 `quota` 可在超過用量閾值後的下一個請求時重新綁定它；開啟 `pool.cacheAffinity` 後，該重新綁定會等到綁定帳號耗盡或無法繼續服務。暫停、冷卻、重新認證與失敗處理可獨立清除或移動路由。未綁定請求沒有即時帳號綁定；這可包含代理重啟或親和性重置後的既有可見任務。Pre-stream 的 429 或 402 在同一個請求中於一個合格的備用帳號上重試一次，即使基於用量的主動切換關閉。帳號變更保留並重播對話 context，但跨帳號的供應商端 prompt-cache 重用不保證，cache 可能需要重新暖機。
 
 在 **401/403** 時，App 登入清除該帳號的行程本地親和性並要求重新認證。
 在 **429** 時，opencodex 遵循 `Retry-After`、啟動帳號冷卻、清除親和性，並可能將請求輪換到另一個合格的池帳號。這些失敗轉換在 `autoSwitchThreshold: 0` 時仍然活躍；該設定僅停用基於用量的主動切換。
@@ -137,7 +139,7 @@ API-key 供應商可持有字面值金鑰或環境參考。OAuth 供應商使用
 
 | 策略 | 行為 |
 | --- | --- |
-| `quota`（預設） | 若無現用帳號，跨 5 小時、週與 30 天視窗選擇最低用量的合格帳號。否則將合格現用帳號保持在 `autoSwitchThreshold` 以下；在超過閾值後，未綁定請求或綁定任務的下一個請求可移至較低用量的合格帳號。`0` 停用此用量驅動的重新評估，而非失敗復原。 |
+| `quota`（預設） | 若無現用帳號，跨 5 小時、週與 30 天視窗選擇最低用量的合格帳號。否則將合格現用帳號保持在 `autoSwitchThreshold` 以下；在超過閾值後，未綁定請求可移至較低用量的合格帳號，未開啟 `pool.cacheAffinity` 時綁定任務的下一個請求也可。開啟後，cache affinity 優先於配額餘裕，綁定任務會保留到帳號耗盡（已知用量 100%）或無法繼續服務。`0` 停用此用量驅動的重新評估，而非失敗復原。 |
 | `round-robin` | 在合格帳號間均勻指派未綁定請求。`autoSwitchThreshold` 不變更一般 round-robin 選擇。`accountPoolStickyLimit`（1–100）計數一次選擇上的指派，而非成功的上游回應。 |
 | `fill-first` | 將未綁定請求指派到現用帳號直到冷卻、重新認證或設定的排空閾值；未知用量不強制切換。健康的綁定任務保留親和性。 |
 
@@ -180,7 +182,7 @@ API-key 供應商可持有字面值金鑰或環境參考。OAuth 供應商使用
 | `failureBackoffMaxSeconds?` | `number` | `3600` | Backoff 上限與永久失敗延遲。 |
 | `codexWarmupEnabled?` | `boolean` | `false` | 選擇加入合成 Codex 池帳號驗證。 |
 | `codexWarmupMaxAgeSeconds?` | `number` | `691200` | 8 天後重新驗證帳號。 |
-| `codexWarmupModel?` | `string` | `gpt-5.4-mini` | 用於可選暖機的原生模型。 |
+| `codexWarmupModel?` | `string` | `gpt-5.6-luna` | 用於可選暖機的原生模型。 |
 
 ## 固定供應商端點
 
@@ -386,7 +388,7 @@ Vercel AI Gateway 可在多個底層推論供應商之間路由一個模型。`v
       "baseUrl": "https://ollama.com/v1",
       "apiKey": "${OLLAMA_API_KEY}",
       "defaultModel": "glm-5.2",
-      "noVisionModels": ["glm-5.2", "gpt-oss", "qwen3-coder", "deepseek-v4-pro"]
+      "noVisionModels": ["glm-5.2", "gpt-oss", "qwen3-coder", "deepseek-v4-flash"]
     }
   },
   "subagentModels": ["anthropic/claude-opus-5", "ollama-cloud/glm-5.2"],
diff --git a/docs-site/src/content/docs/zh-tw/reference/configuration/server.md b/docs-site/src/content/docs/zh-tw/reference/configuration/server.md
index 4649b51f97..402015f060 100644
--- a/docs-site/src/content/docs/zh-tw/reference/configuration/server.md
+++ b/docs-site/src/content/docs/zh-tw/reference/configuration/server.md
@@ -188,7 +188,7 @@ OpenAI backend 需要 ChatGPT 登入與啟用的 ChatGPT `forward` 供應商。C
 | --- | --- | --- | --- |
 | `enabled?` | `boolean` | 可用時開啟 | 主圖片描述開關。 |
 | `backend?` | `"openai" \| "anthropic"` | 自動 | 明確值優先；未設定時優先使用可用的已儲存 Anthropic OAuth 憑證，否則使用 `openai`。 |
-| `model?` | `string` | 視 backend 而定 | OpenAI 為 `gpt-5.4-mini` 或 Anthropic 為 `claude-sonnet-5`。 |
+| `model?` | `string` | 視 backend 而定 | OpenAI 為 `gpt-5.6-luna` 或 Anthropic 為 `claude-sonnet-5`。 |
 | `maxDescriptionsPerTurn?` | `number` | `8` | 每個主回合允許的新描述快取未命中。`0` 停用呼叫；無效值使用預設。 |
 | `timeoutMs?` | `number` | `45000` | Sidecar 擷取逾時。整數 1–2147483647。 |
 
diff --git a/docs-site/src/content/docs/zh-tw/reference/management-api.md b/docs-site/src/content/docs/zh-tw/reference/management-api.md
index ca899bc730..8ea6cd79dd 100644
--- a/docs-site/src/content/docs/zh-tw/reference/management-api.md
+++ b/docs-site/src/content/docs/zh-tw/reference/management-api.md
@@ -64,11 +64,15 @@ Session 簽發在需要 data-plane 認證時停用，這包含遠端綁定。遠
 | `GET /api/grok` | 讀取 Grok 受管設定狀態與候選模型 | 400 狀態讀取失敗 |
 | `PUT /api/grok/selection` | 持久化排除的 Grok 模型 | 400 無效或過大選擇 |
 | `POST /api/grok/apply` | 透過受管同步套用持久化的 Grok 設定 | 409 `grok_apply_busy`；400/500 套用失敗 |
+| `GET /api/grok/reset-coupons?accountId=...` | 讀取活躍或指定 xAI 帳號剩餘的 Grok 計費重置 token 與有效期間 | 400 缺失帳號；401 未認證；502 上游 gRPC-Web 錯誤 |
+| `POST /api/grok/reset-coupons/consume` | 兌換一個合格的 reset coupon。請求主體為 `{ accountId?, tokenId?, operationId? }`。選用的 `operationId`（UUIDv4）可讓兌換具備冪等性：重複相同 id 會重播持久化結果，而不會重複兌換。 | 400 無效的 JSON/UUID；401 未認證；409 `identity_mismatch`；502 上游錯誤；503 ledger 容量 |
 | `GET, PUT /api/claude-desktop` | 讀取或持久化 Claude Desktop 路由／原生設定檔 | 400 無效或不可用指派 |
 | `POST /api/claude-desktop/apply` | 將儲存的設定檔寫入 Claude Desktop 的受管設定 | 400/500 寫入失敗 |
 | `GET /api/claude-desktop/status` | 檢查已儲存 vs 已套用設定檔與 Desktop 健康 | 400 狀態讀取失敗 |
 | `GET, PUT /api/claude-code` | 讀取或更新 Claude Code 閘道、auth-mode、model-map、context、agent 與 sidecar 設定 | 400 無效欄位或結構 |
 
+儀表板從 **Providers > xAI Grok > Accounts** 驅動這兩條 coupon 路徑：每個已登入帳號列都帶有票券徽章，顯示剩餘的 reset coupon 數量，徽章會開啟對話框，列出有效期間並兌換最接近到期的 reset coupon。該對話框會送出由客戶端鑄造的 `operationId`，並在逾時後停止送出而不重試，因為日誌記錄仍為開啟的兌換會再次執行。`ocx account grok-reset-coupons` 仍是終端機等價指令。
+
 關於模型名冊與加密 worker-task 行為背後的概念，請見[子代理介面](/zh-tw/guides/sub-agent-surface/)。
 
 ### 用戶端整合復原日誌
diff --git a/docs-site/src/content/docs/zh-tw/reference/proxy-formats.md b/docs-site/src/content/docs/zh-tw/reference/proxy-formats.md
index 361a5892be..483319ac58 100644
--- a/docs-site/src/content/docs/zh-tw/reference/proxy-formats.md
+++ b/docs-site/src/content/docs/zh-tw/reference/proxy-formats.md
@@ -239,6 +239,8 @@ Responses 系列和 Chat 請求接受專用標頭或 Bearer 欄位中的代理
 
 沒有金鑰且不使用 OAuth 的 Cursor 路由可以使用呼叫端另外提供的 bearer，但不能使用代理 secret 或自動補入的 ChatGPT main 憑證。Combo/policy 選擇及實際發生的 shadow/thread-spawn 路由改寫不會將呼叫端的原始憑證傳遞給新目標。正規 OpenAI 路由僅在 JWT 包含 ChatGPT 帳戶宣告，且任何明確提供的帳戶標頭都與該宣告相符時，才可在內部路由變更後還原呼叫端的單一非代理金鑰 bearer。 將呼叫端驗證轉送至選用的 OpenAI sidecar 時，需要單一 JWT，以及明確提供且相符的 `chatgpt-account-id`。即使明確提供了帳戶標頭，opaque bearer 也不會跨路由變更還原。 除此之外，最終目標必須擁有自己的設定、OAuth 或已儲存憑證，否則請求會在本機失敗。只有 thread-spawn 標記而沒有路由變更時，不會移除憑證。
 
+對於未設定金鑰的 Cursor Chat 請求，只有實際規劃了 OpenAI 輔助呼叫且存在標準的 Direct 候選時，才會補充已儲存的 main 驗證。無關的 Cursor 請求不會透過此流程佔用 native main，因此不會延遲設定檔切換。輔助呼叫憑證仍受啟動和切換保護限制，並與 Cursor bearer 分離。Pool 及明確指定帳號的輔助呼叫保留現有帳號選擇。
+
 Claude replay 只會以目前 turn 已取得所有權的記憶體 snapshot 保留 main 憑證，並且僅在最終目標為正規 ChatGPT 路由時還原它。
 
 :::caution
diff --git a/docs/README.md b/docs/README.md
index 6a72059024..00e5bd352f 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -4,5 +4,6 @@ This folder contains investigations and diagnostic notes. It is not the primary
 is not the maintainer source of truth for current invariants.
 
 - Public user workflows live in [`../docs-site/`](../docs-site).
-- Current maintainer invariants live in [`../structure/`](../structure).
+- Current maintainer invariants live in [`../structure/`](../structure); start at
+  [`INDEX.md`](../structure/INDEX.md).
 - Keep files here when the detail is useful for archaeology, debugging, or source research.
diff --git a/docs/codex-app-model-catalog.md b/docs/codex-app-model-catalog.md
index a6cd01da27..2e8c7e3c63 100644
--- a/docs/codex-app-model-catalog.md
+++ b/docs/codex-app-model-catalog.md
@@ -107,8 +107,8 @@ The recognized Codex effort ladder is `low < medium < high < xhigh < max < ultra
   `prefer_websockets`/`supports_websockets` follow the central websocket gate. A future
   `gpt-5.6-*` slug the snapshot predates falls back to template synthesis plus
   `ensureGpt56ReasoningLevels` (appends `max`+`ultra`).
-- Snapshot scope is deliberately gpt-5.6-only: the bundled upstream entries for
-  `gpt-5.5`/`gpt-5.4` are staler than the installed catalog's live entries (e.g. snapshot
+- Snapshot scope is deliberately gpt-5.6-only: the bundled upstream entries for older natives
+  such as `gpt-5.5` are staler than the installed catalog's live entries (e.g. snapshot
   gpt-5.5 carries `tool_mode: null`), so substituting them would downgrade real data. On-disk
   sync also self-heals fallback-quality 5.6 entries (display_name stamped with the bare slug)
   by upgrading them to the snapshot entry; genuine entries from a newer installed codex are
diff --git a/docs/shadow-call-intercept.md b/docs/shadow-call-intercept.md
index d0e7248734..dc271588b4 100644
--- a/docs/shadow-call-intercept.md
+++ b/docs/shadow-call-intercept.md
@@ -14,9 +14,11 @@ its configured reasoning effort.
 The helper model is not stable across client versions. Codex used `gpt-5.4-mini` up to 0.144.x and
 moved to `gpt-5.6-luna` in 0.145.0, which silently disabled a single-literal intercept
 ([#311](https://github.com/lidge-jun/opencodex/issues/311)). The intercept therefore matches a
-**set** of source-model prefixes — `gpt-5.4-mini` and `gpt-5.6-luna` by default — so a client bump
-does not quietly turn the feature off. Routed ids (`provider/model`) are never matched: a shadow
-call is always a bare native slug, and an explicit routed selection must not be hijacked.
+**set** of source-model prefixes — `gpt-5.6-luna` by default — so a client bump does not quietly
+turn the feature off. `gpt-5.4-mini` is retired upstream and is no longer a default prefix, but it
+remains a valid `sourceModels` entry for anyone still serving 0.144.x clients. Routed ids
+(`provider/model`) are never matched: a shadow call is always a bare native slug, and an explicit
+routed selection must not be hijacked.
 
 ## The problem
 
diff --git a/gui/public/provider-icons/README.md b/gui/public/provider-icons/README.md
index 1aab8d651c..793190db02 100644
--- a/gui/public/provider-icons/README.md
+++ b/gui/public/provider-icons/README.md
@@ -12,6 +12,9 @@ License/source notes for the additional candidates are recorded in
 
 Export-client marks (used by the API tab's connect rows, not the provider list):
 
+- `cline-color.svg` — reuses the existing provider mark already tracked in this directory
+  for Cline CLI; no new image was imported for the file integration.
+
 - `pi.svg` — fetched 2026-08-02 from `https://pi.dev/favicon.svg`, the Pi
   project's own favicon, unmodified. Pi is `earendil-works/pi`
   (formerly `badlogic/pi-mono`).
@@ -57,6 +60,19 @@ Export-client marks (used by the API tab's connect rows, not the provider list):
   behind — is removed because the path never leaves the frame and the rect
   would read as a second ink to the mark tooling here.
 
+- `omo.svg` — fetched 2026-09-12 from `https://omo.dev/brand/omo-mark.svg`, the
+  24px header mark on omo's own site. The identical file (4021 bytes, MD5
+  `c33f72d7c4612c290834ba860f644557`) is committed as
+  `.github/assets/omo-icon-light.svg` in `code-yeongyu/oh-my-openagent` and
+  rendered as that README's logo, which is what identifies it as the intended
+  square lockup rather than an incidental asset. Note the branch: that repository's
+  default branch is `dev`, so the `main` raw path 404s. Copied unmodified,
+  `viewBox="0 0 1024 1024"`. Used for the `omo` client (`omo-ai@beta`).
+  `omo.dev/icon.svg` was rejected for being a single `<text>O</text>` glyph, the
+  same rule that sent Hermes to a trace; `omo-logo.png` is a superseded 3D
+  illustration and `omo.png` a landscape screenshot. The npm tarball ships no
+  image at all.
+
 - `minimax.svg` — fetched 2026-08-31 from
   `https://raw.githubusercontent.com/MiniMax-AI/MiniMax-01/main/figures/minimax.svg`,
   MiniMax's own symbol as committed in their own model repository. The API-docs
@@ -88,6 +104,24 @@ at 20px.
   `viewBox="0 0 823 823"` by centering the 823x806 trace. Named
   `hermes-agent` rather than `hermes` because Hermes is also a provider name
   and this directory is one flat namespace.
+- `devin.svg` — fetched 2026-09-12 from `https://docs.devin.ai/logo/light.svg`,
+  Devin's own documentation logo, and CROPPED to its symbol. The source is a
+  160x24 horizontal lockup: the three-leaf mark occupies the left 24 units and
+  the `devin` wordmark starts at x=34.2, so a `viewBox="0 0 24 24"` window keeps
+  the whole symbol and excludes every wordmark path. The thirteen symbol paths
+  and all seven gradients are verbatim — nothing is translated, so the
+  `userSpaceOnUse` gradient coordinates stay valid — and only the two wordmark
+  paths are dropped. Cropping a lockup to its symbol is what `cursor-color.svg`
+  and `gajae-code.svg` already do; the alternative here was a wordmark in a 20px
+  box, which this file refuses.
+
+  `devin.ai/favicon.svg` sits behind a Vercel security checkpoint that answers
+  429 with an HTML page, and `cognition.ai` publishes only a raster favicon, so
+  the docs site is the reachable first-party vector. Windsurf does publish
+  `windsurf.com/favicon.svg` — a plated `W` — but that names the retired brand
+  for a provider labelled Cognition. Multi-colour gradient, so it is drawn as an
+  image and is not a candidate for the masked set.
+
 - `gajae-code.svg` — traced 2026-08-31 from `Yeachan-Heo/gajae-code`
   `assets/character.png` (3190496 bytes, 1550x2048 RGBA), the mascot. No SVG
   exists upstream: `assets/` and `docs/` hold only raster, `public/` is a 404,
@@ -148,6 +182,12 @@ Decisions that are not obvious from looking at the file:
 - `raycast.svg` **is not masked.** One ink, but that ink is #FF6363 — Raycast
   red, the same case as `openai.svg` and `deepseek-harness.svg`. Legible on both
   surfaces as an image.
+- `omo.svg` **is not masked.** Two inks: an `#F4F4F4` rounded plate carrying an
+  `#041617` face. The plate is opaque and covers most of the canvas, so masking
+  — which reads alpha, not color — would paint a filled rounded tile and discard
+  the face entirely. This is the plated case `qoder.svg` already established, and
+  it is why a plated mark is not a candidate for the monochrome set however
+  neutral its inks look.
 
 Both directions are enforced in `gui/tests/integration-marks.test.ts`, including a
 luminance check that fails any single-ink near-neutral mark left as an image. That
diff --git a/gui/public/provider-icons/devin.svg b/gui/public/provider-icons/devin.svg
new file mode 100644
index 0000000000..c0620e2602
--- /dev/null
+++ b/gui/public/provider-icons/devin.svg
@@ -0,0 +1,49 @@
+<svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M7.95343 21.1394C4.89586 21.1304 2.25471 19.458 0.987296 16.2895C-0.280118 13.121 0.108924 9.16314 1.74363 5.61504C4.8012 5.62409 7.44235 7.29648 8.70976 10.465C9.97718 13.6335 9.58814 17.5913 7.95343 21.1394Z" fill="white"/>
+<path d="M7.95343 21.1394C4.89586 21.1304 2.25471 19.458 0.987296 16.2895C-0.280118 13.121 0.108924 9.16314 1.74363 5.61504C4.8012 5.62409 7.44235 7.29648 8.70976 10.465C9.97718 13.6335 9.58814 17.5913 7.95343 21.1394Z" fill="url(#paint0_radial_115_86)"/>
+<path d="M7.95343 21.1394C4.89586 21.1304 2.25471 19.458 0.987296 16.2895C-0.280118 13.121 0.108924 9.16314 1.74363 5.61504C4.8012 5.62409 7.44235 7.29648 8.70976 10.465C9.97718 13.6335 9.58814 17.5913 7.95343 21.1394Z" fill="black" fill-opacity="0.5" style="mix-blend-mode:hard-light"/>
+<path d="M7.95343 21.1394C4.89586 21.1304 2.25471 19.458 0.987296 16.2895C-0.280118 13.121 0.108924 9.16314 1.74363 5.61504C4.8012 5.62409 7.44235 7.29648 8.70976 10.465C9.97718 13.6335 9.58814 17.5913 7.95343 21.1394Z" fill="url(#paint1_linear_115_86)" fill-opacity="0.5" style="mix-blend-mode:hard-light"/>
+<path d="M7.9354 21.1112C4.89702 21.0957 2.27411 19.4306 1.01347 16.279C-0.248375 13.1244 0.135612 9.18218 1.76165 5.64327C4.80004 5.65882 7.42295 7.32385 8.68359 10.4755C9.94543 13.63 9.56144 17.5723 7.9354 21.1112Z" stroke="url(#paint2_linear_115_86)" stroke-opacity="0.05" stroke-width="0.056338"/>
+<path d="M7.31038 21.2574C11.3543 20.2215 14.8836 17.3754 16.6285 13.2361C18.3735 9.09671 17.9448 4.58749 15.8598 0.976291C11.8159 2.01214 8.2866 4.85826 6.54167 8.99762C4.79674 13.137 5.2254 17.6462 7.31038 21.2574Z" fill="white"/>
+<path d="M7.31038 21.2574C11.3543 20.2215 14.8836 17.3754 16.6285 13.2361C18.3735 9.09671 17.9448 4.58749 15.8598 0.976291C11.8159 2.01214 8.2866 4.85826 6.54167 8.99762C4.79674 13.137 5.2254 17.6462 7.31038 21.2574Z" fill="url(#paint3_radial_115_86)"/>
+<path d="M16.6025 13.2251C14.8642 17.349 11.3512 20.1866 7.32411 21.2248C5.25257 17.624 4.82926 13.1324 6.56764 9.00855C8.30603 4.88472 11.819 2.04706 15.8461 1.00889C17.9176 4.60967 18.3409 9.10131 16.6025 13.2251Z" stroke="url(#paint4_linear_115_86)" stroke-opacity="0.05" stroke-width="0.056338"/>
+<path d="M7.23368 21.2069C9.78906 23.2373 13.2102 23.9506 16.5772 22.8141C19.9441 21.6775 22.5058 18.9445 23.7304 15.6382C21.175 13.6078 17.7538 12.8944 14.3869 14.031C11.0199 15.1676 8.45822 17.9006 7.23368 21.2069Z" fill="white"/>
+<path d="M7.23368 21.2069C9.78906 23.2373 13.2102 23.9506 16.5772 22.8141C19.9441 21.6775 22.5058 18.9445 23.7304 15.6382C21.175 13.6078 17.7538 12.8944 14.3869 14.031C11.0199 15.1676 8.45822 17.9006 7.23368 21.2069Z" fill="url(#paint5_radial_115_86)"/>
+<path d="M7.23368 21.2069C9.78906 23.2373 13.2102 23.9506 16.5772 22.8141C19.9441 21.6775 22.5058 18.9445 23.7304 15.6382C21.175 13.6078 17.7538 12.8944 14.3869 14.031C11.0199 15.1676 8.45822 17.9006 7.23368 21.2069Z" fill="black" fill-opacity="0.2" style="mix-blend-mode:hard-light"/>
+<path d="M7.23368 21.2069C9.78906 23.2373 13.2102 23.9506 16.5772 22.8141C19.9441 21.6775 22.5058 18.9445 23.7304 15.6382C21.175 13.6078 17.7538 12.8944 14.3869 14.031C11.0199 15.1676 8.45822 17.9006 7.23368 21.2069Z" fill="url(#paint6_linear_115_86)" fill-opacity="0.5" style="mix-blend-mode:hard-light"/>
+<path d="M16.5682 22.7874C13.2176 23.9184 9.81361 23.2124 7.2672 21.1975C8.49194 17.9068 11.0444 15.189 14.3959 14.0577C17.7465 12.9266 21.1504 13.6326 23.6968 15.6476C22.4721 18.9383 19.9196 21.656 16.5682 22.7874Z" stroke="url(#paint7_linear_115_86)" stroke-opacity="0.05" stroke-width="0.056338"/>
+<defs>
+<radialGradient id="paint0_radial_115_86" cx="0" cy="0" r="1" gradientUnits="userSpaceOnUse" gradientTransform="translate(-3.00503 15.023) rotate(-10.029) scale(17.9572 17.784)">
+<stop stop-color="#00B0BB"/>
+<stop offset="1" stop-color="#00DB65"/>
+</radialGradient>
+<linearGradient id="paint1_linear_115_86" x1="7.39036" y1="4.81308" x2="1.62975" y2="18.6894" gradientUnits="userSpaceOnUse">
+<stop stop-color="#18E299"/>
+<stop offset="1"/>
+</linearGradient>
+<linearGradient id="paint2_linear_115_86" x1="7.94816" y1="8.01562" x2="1.7612" y2="18.746" gradientUnits="userSpaceOnUse">
+<stop/>
+<stop offset="1" stop-opacity="0"/>
+</linearGradient>
+<radialGradient id="paint3_radial_115_86" cx="0" cy="0" r="1" gradientUnits="userSpaceOnUse" gradientTransform="translate(8.11404 20.8822) rotate(-75.7542) scale(21.6246 23.7772)">
+<stop stop-color="#00BBBB"/>
+<stop offset="0.712616" stop-color="#00DB65"/>
+</radialGradient>
+<linearGradient id="paint4_linear_115_86" x1="7.60205" y1="5.8709" x2="15.5561" y2="16.3719" gradientUnits="userSpaceOnUse">
+<stop/>
+<stop offset="1" stop-opacity="0"/>
+</linearGradient>
+<radialGradient id="paint5_radial_115_86" cx="0" cy="0" r="1" gradientUnits="userSpaceOnUse" gradientTransform="translate(7.84537 21.5181) rotate(-20.3525) scale(18.5603 17.32)">
+<stop stop-color="#00B0BB"/>
+<stop offset="1" stop-color="#00DB65"/>
+</radialGradient>
+<linearGradient id="paint6_linear_115_86" x1="16.8078" y1="13.0071" x2="10.0409" y2="22.9937" gradientUnits="userSpaceOnUse">
+<stop stop-color="#00B1BC"/>
+<stop offset="1"/>
+</linearGradient>
+<linearGradient id="paint7_linear_115_86" x1="16.8078" y1="13.0071" x2="14.1687" y2="23.841" gradientUnits="userSpaceOnUse">
+<stop/>
+<stop offset="1" stop-opacity="0"/>
+</linearGradient>
+</defs>
+</svg>
diff --git a/gui/public/provider-icons/omo.svg b/gui/public/provider-icons/omo.svg
new file mode 100644
index 0000000000..21c1b35c6e
--- /dev/null
+++ b/gui/public/provider-icons/omo.svg
@@ -0,0 +1,42 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024">
+  <path fill="#F4F4F4" d="M512.00 100.50 C591.13 100.50 697.66 102.37 749.39 106.27 C801.11 110.17 802.35 115.84 822.35 123.90 C842.34 131.96 856.40 141.68 869.36 154.64 C882.32 167.60 892.04 181.66 900.10 201.65 C908.16 221.65 913.83 222.89 917.73 274.61 C921.63 326.34 923.50 432.87 923.50 512.00 C923.50 591.13 921.63 697.66 917.73 749.39 C913.83 801.11 908.16 802.35 900.10 822.35 C892.04 842.34 882.32 856.40 869.36 869.36 C856.40 882.32 842.34 892.04 822.35 900.10 C802.35 908.16 801.11 913.83 749.39 917.73 C697.66 921.63 591.13 923.50 512.00 923.50 C432.87 923.50 326.34 921.63 274.61 917.73 C222.89 913.83 221.65 908.16 201.65 900.10 C181.66 892.04 167.60 882.32 154.64 869.36 C141.68 856.40 131.96 842.34 123.90 822.35 C115.84 802.35 110.17 801.11 106.27 749.39 C102.37 697.66 100.50 591.13 100.50 512.00 C100.50 432.87 102.37 326.34 106.27 274.61 C110.17 222.89 115.84 221.65 123.90 201.65 C131.96 181.66 141.68 167.60 154.64 154.64 C167.60 141.68 181.66 131.96 201.65 123.90 C221.65 115.84 222.89 110.17 274.61 106.27 C326.34 102.37 432.87 100.50 512.00 100.50Z"/>
+  <g transform="scale(0.5)">
+    <g transform="translate(0.000000,2048.000000) scale(0.050000,-0.050000)">
+      <path fill="#041617" fill-rule="evenodd" d="M9270 32167 c-309 -64 -456 -152 -621 -373 -562 -748 -776 -2689
+-547 -4984 118 -1187 325 -2600 570 -3890 143 -753 152 -653 -128 -1380 -403
+-1045 -643 -1873 -812 -2800 -853 -4689 1979 -7986 7858 -9148 1140 -225 2514
+-397 3202 -400 l361 -2 79 55 c264 182 210 642 -111 942 -387 362 -950 532
+-2801 845 -3004 507 -4249 965 -5520 2030 -1358 1138 -2012 2878 -1809 4810
+545 5195 6617 8726 13529 7866 5506 -684 9480 -4255 9480 -8518 0 -2607 -1462
+-4522 -4157 -5448 -927 -318 -1534 -459 -3203 -740 -1851 -313 -2414 -483
+-2801 -845 -321 -300 -375 -760 -111 -942 l79 -55 361 2 c688 3 2062 175 3202
+400 5879 1162 8711 4459 7858 9148 -169 927 -409 1755 -812 2800 -280 727
+-271 627 -128 1380 245 1290 452 2703 570 3890 271 2720 -77 4861 -855 5259
+-758 388 -2310 -238 -5021 -2024 -868 -571 -764 -557 -1489 -211 -3271 1558
+-6755 1558 -10026 0 -725 -346 -621 -360 -1489 211 -2371 1562 -3959 2278
+-4708 2122z m4132 -3345 c175 -175 124 -268 -409 -739 -1028 -910 -1995 -2053
+-2713 -3209 -97 -156 -200 -318 -228 -359 -221 -321 -646 -76 -469 270 153
+301 883 1334 1388 1965 578 723 1466 1614 2029 2035 191 142 288 151 402 37z
+m14507 -1 c496 -341 1482 -1323 2080 -2071 505 -631 1235 -1664 1388 -1965
+177 -346 -248 -591 -469 -270 -28 41 -131 203 -228 359 -718 1156 -1685 2299
+-2713 3209 -535 473 -585 564 -407 742 100 100 199 99 349 -4z M19910 25308 c-4039 -205 -7212 -1666 -9086 -4184 -1840 -2473 -1753
+-5794 196 -7540 1161 -1040 2447 -1518 5420 -2015 1374 -229 1998 -380 2456
+-591 754 -348 1163 -1000 1033 -1650 -10 -49 -1 -72 47 -124 l60 -64 444 0
+444 0 60 64 c48 52 57 75 47 124 -130 650 279 1302 1033 1650 458 211 1082
+362 2456 591 2973 497 4259 975 5420 2015 2084 1866 2026 5374 -131 7956
+-2063 2469 -5995 3966 -9899 3768z m-4644 -4374 c1356 -360 2272 -1909 1998
+-3378 -426 -2278 -2856 -3144 -4424 -1576 -1497 1496 -924 4218 1031 4899 393
+137 996 161 1395 55z m11480 35 c1491 -261 2504 -1921 2154 -3532 -487 -2247
+-3108 -3024 -4525 -1341 -1719 2042 -129 5310 2371 4873z m-6948 -2980 c172
+-40 341 -133 495 -273 95 -86 143 -116 187 -116 44 0 92 30 187 116 718 650
+1716 188 1854 -860 35 -267 18 -968 -25 -1048 -119 -219 -350 -251 -491 -68
+-68 89 -73 124 -85 670 -13 623 -25 675 -200 838 -212 198 -516 199 -735 2
+-180 -161 -192 -212 -205 -840 -12 -546 -17 -581 -85 -670 -122 -159 -308
+-159 -430 0 -68 89 -73 124 -85 670 -13 628 -25 679 -205 840 -219 197 -523
+196 -735 -2 -175 -163 -187 -215 -200 -838 -12 -546 -17 -581 -85 -670 -141
+-183 -372 -151 -491 68 -74 136 -54 1039 30 1332 170 594 758 978 1304 849z M14340 20290 c-1858 -372 -2230 -3228 -546 -4191 1280 -732 2786 338
+2786 1981 0 1391 -1068 2445 -2240 2210z M25990 20291 c-1733 -343 -2208 -2981 -732 -4069 1287 -949 2981 108
+2982 1860 0 1392 -1070 2443 -2250 2209z"/>
+    </g>
+  </g>
+</svg>
diff --git a/gui/src/account-pool-strategy.ts b/gui/src/account-pool-strategy.ts
index 4dbc7b9e2b..b2532b0fc7 100644
--- a/gui/src/account-pool-strategy.ts
+++ b/gui/src/account-pool-strategy.ts
@@ -52,35 +52,3 @@ export function parseAccountPoolStickyLimitDraft(value: string): number | null {
   const n = Number(trimmed);
   return n >= MIN_ACCOUNT_POOL_STICKY_LIMIT && n <= MAX_ACCOUNT_POOL_STICKY_LIMIT ? n : null;
 }
-
-export type PoolStrategyFetch = (input: string, init: RequestInit) => Promise<Response>;
-
-export async function putCodexPoolStrategy(
-  apiBase: string,
-  body: { strategy?: AccountPoolStrategy; stickyLimit?: number },
-  fetchImpl: PoolStrategyFetch = (input, init) => fetch(input, init),
-): Promise<{ ok: true; strategy: AccountPoolStrategy; stickyLimit: number } | { ok: false }> {
-  if (body.strategy === undefined && body.stickyLimit === undefined) return { ok: false };
-  try {
-    const response = await fetchImpl(`${apiBase}/api/codex-auth/pool-strategy`, {
-      method: "PUT",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        ...(body.strategy !== undefined ? { strategy: body.strategy } : {}),
-        ...(body.stickyLimit !== undefined ? { stickyLimit: body.stickyLimit } : {}),
-      }),
-    });
-    if (!response.ok) return { ok: false };
-    const json = await response.json() as {
-      accountPoolStrategy?: unknown;
-      accountPoolStickyLimit?: unknown;
-    };
-    return {
-      ok: true,
-      strategy: normalizeAccountPoolStrategy(json.accountPoolStrategy ?? body.strategy),
-      stickyLimit: normalizeAccountPoolStickyLimit(json.accountPoolStickyLimit ?? body.stickyLimit),
-    };
-  } catch {
-    return { ok: false };
-  }
-}
diff --git a/gui/src/app-routing.ts b/gui/src/app-routing.ts
index c5971ffb6b..e2184af3d2 100644
--- a/gui/src/app-routing.ts
+++ b/gui/src/app-routing.ts
@@ -101,6 +101,8 @@ export const INTEGRATION_TAB_HASHES = [
   "integrations/prime",
   "integrations/aside",
   "integrations/raycast",
+  "integrations/omo",
+  "integrations/cline",
 ] as const;
 
 export function hashBelongsToPage(rawHash: string, page: Page): boolean {
diff --git a/gui/src/codex-auto-switch.ts b/gui/src/codex-auto-switch.ts
index ed7d7168da..eac76dbbfc 100644
--- a/gui/src/codex-auto-switch.ts
+++ b/gui/src/codex-auto-switch.ts
@@ -1,5 +1,7 @@
 export const DEFAULT_AUTO_SWITCH_THRESHOLD = 80;
 
+import { CODEX_POOL_PROVIDER, putPoolSettings } from "./pool-settings";
+
 const AUTO_SWITCH_PUT_TIMEOUT_MS = 10_000;
 
 export type AutoSwitchFetch = (input: string, init: RequestInit) => Promise<Response>;
@@ -78,15 +80,15 @@ export async function putAutoSwitchThreshold(
   timeoutMs = AUTO_SWITCH_PUT_TIMEOUT_MS,
 ): Promise<boolean> {
   if (!Number.isInteger(threshold) || threshold < 0 || threshold > 100) return false;
-  try {
-    const response = await fetchImpl(`${apiBase}/api/codex-auth/auto-switch`, {
-      method: "PUT",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ threshold }),
-      signal: AbortSignal.timeout(timeoutMs),
-    });
-    return response.ok;
-  } catch {
-    return false;
-  }
+  // Through the shared client, which maps `threshold` onto the contract's
+  // `autoSwitchThreshold` and sends the provider. This function reports only ok/not-ok, so a
+  // body the route silently ignored would read here as a successful save that changed nothing.
+  const settings = await putPoolSettings(
+    apiBase,
+    CODEX_POOL_PROVIDER,
+    { threshold },
+    (input, init) => fetchImpl(input, init as RequestInit),
+    { signal: AbortSignal.timeout(timeoutMs) },
+  );
+  return settings !== null;
 }
diff --git a/gui/src/combo-workspace-data.ts b/gui/src/combo-workspace-data.ts
index bf8b881c55..b89bff656f 100644
--- a/gui/src/combo-workspace-data.ts
+++ b/gui/src/combo-workspace-data.ts
@@ -4,6 +4,7 @@
  */
 
 import { SUPPORTED_NATIVE_OPENAI_SLUGS } from "../../src/codex/catalog/native-models";
+import { PROVIDER_QUOTA_MAX_AGE_MS } from "../../src/providers/quota-types";
 import type { TKey } from "./i18n/shared";
 
 export { SUPPORTED_NATIVE_OPENAI_SLUGS };
@@ -92,7 +93,7 @@ export type ComboQuotaState = "available" | "exhausted" | "unknown";
 export type ProviderQuotaStates = Readonly<Record<string, ComboQuotaState>>;
 
 /** Matches the management endpoint's bounded last-good quota lifetime. */
-export const COMBO_QUOTA_MAX_AGE_MS = 30 * 60_000;
+export const COMBO_QUOTA_MAX_AGE_MS = PROVIDER_QUOTA_MAX_AGE_MS;
 
 let comboTargetKeySeq = 0;
 
@@ -282,133 +283,36 @@ function finiteNumber(value: unknown): number | null {
   return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
 
-function quotaTimestampIsFresh(value: unknown, now: number): boolean {
-  const timestamp = finiteNumber(value);
-  return timestamp !== null && now - timestamp < COMBO_QUOTA_MAX_AGE_MS;
-}
-
-function nonNegativeInteger(value: unknown): number | null {
-  const number = finiteNumber(value);
-  return number !== null && Number.isInteger(number) && number >= 0 ? number : null;
-}
-
-function aggregateWindowIsComplete(value: unknown, now: number): boolean {
-  const window = recordFromUnknown(value);
-  const usedPercent = finiteNumber(window?.usedPercent);
-  return !!window
-    && usedPercent !== null
-    && usedPercent >= 0
-    && nonNegativeInteger(window.includedAccounts) !== null
-    && (nonNegativeInteger(window.includedAccounts) ?? 0) > 0
-    && nonNegativeInteger(window.excludedAccounts) === 0
-    && window.incomplete === false
-    && quotaTimestampIsFresh(window.updatedAt, now);
-}
-
-function aggregateEvidenceIsComplete(value: unknown, now: number): boolean {
-  const aggregation = recordFromUnknown(value);
-  if (
-    !aggregation
-    || aggregation.kind !== "capacity-weighted-v1"
-    || aggregation.scope !== "routable-known"
-    || aggregation.presentation !== "aggregate"
-    || aggregation.incomplete !== false
-  ) return false;
-
-  for (const key of [
-    "includedAccounts",
-    "excludedAccounts",
-    "unknownPlanAccounts",
-    "missingQuotaAccounts",
-    "pausedAccounts",
-    "reauthAccounts",
-    "staleQuotaAccounts",
-    "partialWindowAccounts",
-  ] as const) {
-    if (nonNegativeInteger(aggregation[key]) === null) return false;
-  }
-  if ((nonNegativeInteger(aggregation.includedAccounts) ?? 0) === 0) return false;
-  for (const key of [
-    "excludedAccounts",
-    "unknownPlanAccounts",
-    "missingQuotaAccounts",
-    "pausedAccounts",
-    "reauthAccounts",
-    "staleQuotaAccounts",
-    "partialWindowAccounts",
-  ] as const) {
-    if (aggregation[key] !== 0) return false;
-  }
-
-  let hasWindow = false;
-  for (const key of ["fiveHour", "weekly", "monthly"] as const) {
-    if (!Object.hasOwn(aggregation, key)) continue;
-    if (!aggregateWindowIsComplete(aggregation[key], now)) return false;
-    hasWindow = true;
-  }
-  if (Object.hasOwn(aggregation, "customWindows")) {
-    if (!Array.isArray(aggregation.customWindows)) return false;
-    for (const value of aggregation.customWindows) {
-      const custom = recordFromUnknown(value);
-      if (!custom || typeof custom.label !== "string" || !custom.label.trim()) return false;
-      if (!aggregateWindowIsComplete(custom, now)) return false;
-      hasWindow = true;
-    }
-  }
-  return hasWindow;
+function routingQuotaFromReport(raw: Record<string, unknown>, now: number): {
+  state: "available" | "exhausted";
+  validUntil: number;
+} | null {
+  const routing = recordFromUnknown(raw.routingQuota);
+  if (!routing || (routing.state !== "available" && routing.state !== "exhausted")) return null;
+  const updatedAt = finiteNumber(routing.updatedAt);
+  const validUntil = finiteNumber(routing.validUntil);
+  if (updatedAt === null || updatedAt < 0 || updatedAt > now
+    || now - updatedAt >= COMBO_QUOTA_MAX_AGE_MS
+    || validUntil === null || validUntil <= now
+    || validUntil > updatedAt + COMBO_QUOTA_MAX_AGE_MS) return null;
+  return { state: routing.state, validUntil };
 }
 
 function quotaStateFromReport(raw: Record<string, unknown>, now: number): ComboQuotaState {
-  if (!quotaTimestampIsFresh(raw.updatedAt, now)) return "unknown";
-  const quota = recordFromUnknown(raw.quota);
-  if (!quota || !quotaTimestampIsFresh(quota.updatedAt, now)) return "unknown";
-  if (raw.aggregation !== undefined && !aggregateEvidenceIsComplete(raw.aggregation, now)) return "unknown";
-
-  let hasEvidence = false;
-  let exhausted = false;
-  for (const key of ["fiveHourPercent", "weeklyPercent", "monthlyPercent"] as const) {
-    if (!Object.hasOwn(quota, key)) continue;
-    const percent = finiteNumber(quota[key]);
-    if (percent === null || percent < 0) return "unknown";
-    hasEvidence = true;
-    if (percent >= 100) exhausted = true;
-  }
-  for (const key of ["fiveHourResetAt", "weeklyResetAt", "monthlyResetAt"] as const) {
-    if (Object.hasOwn(quota, key) && finiteNumber(quota[key]) === null) return "unknown";
-  }
-
-  if (Object.hasOwn(quota, "customWindows")) {
-    if (!Array.isArray(quota.customWindows)) return "unknown";
-    for (const value of quota.customWindows) {
-      const window = recordFromUnknown(value);
-      const percent = finiteNumber(window?.percent);
-      if (!window || typeof window.label !== "string" || !window.label.trim() || percent === null || percent < 0) {
-        return "unknown";
-      }
-      if (Object.hasOwn(window, "resetAt") && finiteNumber(window.resetAt) === null) return "unknown";
-      hasEvidence = true;
-      if (percent >= 100) exhausted = true;
-    }
-  }
+  return routingQuotaFromReport(raw, now)?.state ?? "unknown";
+}
 
-  if (Object.hasOwn(quota, "creditsUsd")) {
-    const credits = recordFromUnknown(quota.creditsUsd);
-    if (!credits) return "unknown";
-    const used = finiteNumber(credits.used);
-    const limit = finiteNumber(credits.limit);
-    const remaining = finiteNumber(credits.remaining);
-    const percent = finiteNumber(credits.percent);
-    if (used === null || used < 0 || limit === null || limit < 0 || remaining === null || percent === null || percent < 0) {
-      return "unknown";
-    }
-    if (credits.unlimited !== undefined && typeof credits.unlimited !== "boolean") return "unknown";
-    if (Object.hasOwn(credits, "expiresAt") && finiteNumber(credits.expiresAt) === null) return "unknown";
-    hasEvidence = true;
-    if (credits.unlimited !== true && remaining <= 0) exhausted = true;
+/** The next expiry also wakes the page when no poll response has arrived. */
+export function nextProviderQuotaStateExpiration(reports: unknown, now = Date.now()): number | undefined {
+  if (!Array.isArray(reports)) return undefined;
+  let next: number | undefined;
+  for (const value of reports) {
+    const report = recordFromUnknown(value);
+    if (!report || typeof report.provider !== "string" || !report.provider.trim()) continue;
+    const routing = routingQuotaFromReport(report, now);
+    if (routing && (next === undefined || routing.validUntil < next)) next = routing.validUntil;
   }
-
-  if (!hasEvidence) return "unknown";
-  return exhausted ? "exhausted" : "available";
+  return next;
 }
 
 /** Fail-unknown parser for the live `/api/provider-quotas` report array. */
diff --git a/gui/src/components/AddProviderModal.tsx b/gui/src/components/AddProviderModal.tsx
index 09f4fcb1d6..f19abbb836 100644
--- a/gui/src/components/AddProviderModal.tsx
+++ b/gui/src/components/AddProviderModal.tsx
@@ -1,5 +1,5 @@
 import { usageSummary30dResourceKey } from "../usage-summary-resource";
-import { useEffect, useMemo, useReducer, useRef } from "react";
+import { useEffect, useMemo, useReducer, useRef, useState } from "react";
 import { IconX } from "../icons";
 import { useT } from "../i18n/shared";
 import { useKeyedClientResource } from "../client-resource";
@@ -12,6 +12,7 @@ import {
 import { oauthTosRisk } from "../oauth-tos-risk";
 import OAuthTosWarningModal from "./OAuthTosWarningModal";
 import ProviderCatalog from "./provider-catalog/ProviderCatalog";
+import ProviderNoteModal from "./provider-catalog/ProviderNoteModal";
 import type { AccountLoginRow, AccountLoginStatus } from "./provider-catalog/ProviderCatalog";
 import type { CatalogPreset } from "./provider-catalog/provider-presets";
 import type { CatalogLoginHint } from "./provider-catalog/login-hint-visibility";
@@ -62,6 +63,13 @@ export default function AddProviderModal({
   const aliveRef = useRef(true);
   const previousFocusRef = useRef<HTMLElement | null>(null);
   const dialogRef = useRef<HTMLDivElement>(null);
+  // The full-note popup is owned here, not in the catalog: it has to render as a sibling
+  // of this overlay, and its open state has to be visible to the Escape handler below.
+  const [notePreset, setNotePreset] = useState<Preset | null>(null);
+  // The unified search text is owned here for the same reason: Escape has to clear a
+  // non-empty query instead of closing the dialog, and the handler that decides is this
+  // component's.
+  const [catalogQuery, setCatalogQuery] = useState("");
 
   const oauthPoll = useKeyedClientResource(
     `add-provider-oauth:${apiBase}`,
@@ -125,11 +133,23 @@ export default function AddProviderModal({
 
   useEffect(() => {
     const onKey = (e: KeyboardEvent) => {
-      if (e.key === "Escape" && !oauthTosPending) onClose();
+      // This listener is on `window` and does not read `defaultPrevented`, so a native
+      // <dialog> cancel does not stop it. Every stacked overlay has to be named here or
+      // Escape closes the whole add-provider modal out from under it.
+      // Kept as a `!oauthTosPending` expression on purpose: tests/gui/oauth-tos-warning.test.ts
+      // source-scans this file for that exact substring, because the guard is the only thing
+      // stopping Escape from closing the modal out from under a stacked overlay.
+      const noOverlayOpen = !oauthTosPending && !notePreset;
+      if (e.key !== "Escape" || !noOverlayOpen) return;
+      // Escape unwinds one layer at a time: the note popup, then a live search, then the
+      // dialog. Closing the modal on the keystroke that was meant to clear a query throws
+      // away everything the user typed into the form behind it.
+      if (catalogQuery) { setCatalogQuery(""); return; }
+      onClose();
     };
     window.addEventListener("keydown", onKey);
     return () => window.removeEventListener("keydown", onKey);
-  }, [onClose, oauthTosPending]);
+  }, [onClose, oauthTosPending, notePreset, catalogQuery]);
 
   const presetDescription = (candidate: Preset): string | undefined => {
     const key = codexPresetDescriptionKey(candidate);
@@ -256,8 +276,11 @@ export default function AddProviderModal({
             usageRank={usageRank}
             presetsLoading={presetsLoading}
             initialTier={initialTier}
+            query={catalogQuery}
+            onQueryChange={setCatalogQuery}
             onSelectPreset={p => choosePreset(p)}
             onSelectCustom={() => choosePreset(fallbackPresets[0]!)}
+            onShowNote={p => setNotePreset(p)}
             accountRows={accountRows}
             accountStatus={accountStatus}
             busyProvider={accountBusy}
@@ -339,6 +362,16 @@ export default function AddProviderModal({
         }}
       />
     )}
+    {notePreset?.note && (
+      <ProviderNoteModal
+        key={notePreset.id}
+        providerId={notePreset.id}
+        label={notePreset.label}
+        adapter={notePreset.adapter}
+        note={notePreset.note}
+        onClose={() => setNotePreset(null)}
+      />
+    )}
     </>
   );
 }
diff --git a/gui/src/components/CodexPoolStrategySetting.tsx b/gui/src/components/CodexPoolStrategySetting.tsx
index b0acdab3f4..e575baed0c 100644
--- a/gui/src/components/CodexPoolStrategySetting.tsx
+++ b/gui/src/components/CodexPoolStrategySetting.tsx
@@ -1,3 +1,4 @@
+import { putCodexPoolStrategy } from "../pool-settings";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { useT } from "../i18n/shared";
 import {
@@ -6,7 +7,7 @@ import {
   normalizeAccountPoolStickyLimit,
   normalizeAccountPoolStrategy,
   parseAccountPoolStickyLimitDraft,
-  putCodexPoolStrategy,
+  
   type AccountPoolStrategy,
 } from "../account-pool-strategy";
 import AccountPoolStrategyControls from "./AccountPoolStrategyControls";
diff --git a/gui/src/components/apikeys-workspace/ClientConfigDialog.tsx b/gui/src/components/apikeys-workspace/ClientConfigDialog.tsx
index 0d315825f1..e8d1cdefcd 100644
--- a/gui/src/components/apikeys-workspace/ClientConfigDialog.tsx
+++ b/gui/src/components/apikeys-workspace/ClientConfigDialog.tsx
@@ -78,7 +78,7 @@ export default function ClientConfigDialog({
             {t("api.clientConfig.missingLimits", { count: envelope.modelsWithoutLimits, total: envelope.modelCount })}
           </p>
         )}
-        {!hasKeys && (
+        {!hasKeys && client !== "cline" && (
           // Informational, never blocking: an agent may legitimately want the shape
           // first, so both actions stay enabled.
           <p className="muted small awi-clientconfig-nokey">
@@ -91,14 +91,14 @@ export default function ClientConfigDialog({
           <CopyableExample text={envelope.destination} />
         </div>
         <div className="awi-clientconfig-line">
-          <span className="muted text-label">{t("api.clientConfig.envHint")}</span>
+          {client !== "cline" && <span className="muted text-label">{t("api.clientConfig.envHint")}</span>}
           <CopyableExample text={envelope.exportHint} />
         </div>
-        <p className="muted small awi-clientconfig-merge">{t("api.clientConfig.mergeWarning")}</p>
+        <p className="muted small awi-clientconfig-merge">{t(client === "cline" ? "api.clientConfig.clineBundle" : "api.clientConfig.mergeWarning")}</p>
         {/* The old <details> is gone — this is the one place the answer lives now,
             so it is a labelled paragraph rather than a fold. */}
         <p className="muted text-label awi-clientconfig-where-title">{t("api.clientConfig.whereDisclosure")}</p>
-        <p className="muted small">{t("api.clientConfig.whereBody")}</p>
+        <p className="muted small">{t(client === "cline" ? "integrations.semantics.cline" : "api.clientConfig.whereBody")}</p>
 
         <div className="modal-actions">
           <button type="button" className="btn btn-primary btn-sm" onClick={onCopy}>
diff --git a/gui/src/components/apikeys-workspace/ClientConfigPanel.tsx b/gui/src/components/apikeys-workspace/ClientConfigPanel.tsx
index 7bdd1da726..bcb03b0706 100644
--- a/gui/src/components/apikeys-workspace/ClientConfigPanel.tsx
+++ b/gui/src/components/apikeys-workspace/ClientConfigPanel.tsx
@@ -74,7 +74,7 @@ export default function ClientConfigPanel({
     }
   }, [t]);
 
-  const downloadJson = useCallback((_client: ExportClientId, envelope: ClientConfigEnvelope, json: string) => {
+  const downloadJson = useCallback((client: ExportClientId, envelope: ClientConfigEnvelope, json: string) => {
     // Mechanics per ClaudeDesktop.exportProfile: the anchor is an implementation
     // detail of a real <button>, and the filename comes from the envelope so it
     // matches the destination file's own name.
@@ -85,7 +85,7 @@ export default function ClientConfigPanel({
     anchor.click();
     URL.revokeObjectURL(url);
     // "Downloaded", never "applied": a file in ~/Downloads changed nothing yet.
-    setAnnouncement(t("api.clientConfig.downloadedAnnounce", {
+    setAnnouncement(t(client === "cline" ? "api.clientConfig.clineDownloaded" : "api.clientConfig.downloadedAnnounce", {
       filename: envelope.filename,
       destination: envelope.destination,
     }));
diff --git a/gui/src/components/apikeys-workspace/client-config-clients.ts b/gui/src/components/apikeys-workspace/client-config-clients.ts
index afd4484551..e164810fbb 100644
--- a/gui/src/components/apikeys-workspace/client-config-clients.ts
+++ b/gui/src/components/apikeys-workspace/client-config-clients.ts
@@ -8,7 +8,7 @@
  * with EXPORT_CLIENT_IDS by hand; adding a client server-side renders no row
  * until this tuple changes.
  */
-export const CLIENTS = ["opencode", "pi", "omp", "hermes", "openclaw", "kimi", "gajae", "dsh", "mcode", "zcode", "prime", "aside", "raycast"] as const;
+export const CLIENTS = ["opencode", "pi", "omp", "hermes", "openclaw", "kimi", "gajae", "dsh", "mcode", "zcode", "prime", "aside", "raycast", "omo", "cline"] as const;
 export type ExportClientId = (typeof CLIENTS)[number];
 
 export const CLIENT_LABEL_KEYS = {
@@ -25,6 +25,8 @@ export const CLIENT_LABEL_KEYS = {
   prime: "api.clientConfig.clientPrime",
   aside: "api.clientConfig.clientAside",
   raycast: "api.clientConfig.clientRaycast",
+  omo: "api.clientConfig.clientOmo",
+  cline: "api.clientConfig.clientCline",
 } as const;
 
 /**
@@ -73,6 +75,10 @@ export const CLIENT_MARKS: Partial<Record<ExportClientId, string>> = {
   aside: "/provider-icons/aside.svg",
   // Raycast red (#FF6363) is the brand, so like `dsh` it stays an image.
   raycast: "/provider-icons/raycast.svg",
+  // Two inks: an #F4F4F4 plate carrying an #041617 face. Masking reads alpha,
+  // so it would paint the plate and throw the face away — see the README.
+  omo: "/provider-icons/omo.svg",
+  cline: "/provider-icons/cline-color.svg",
 };
 
 /**
diff --git a/gui/src/components/integration-marks.ts b/gui/src/components/integration-marks.ts
index eca38510bd..58873cb1cb 100644
--- a/gui/src/components/integration-marks.ts
+++ b/gui/src/components/integration-marks.ts
@@ -58,6 +58,8 @@ export const INTEGRATION_MARKS: Record<OverviewClientId, string | null> = {
   prime: CLIENT_MARKS.prime ?? null,
   aside: CLIENT_MARKS.aside ?? null,
   raycast: CLIENT_MARKS.raycast ?? null,
+  omo: CLIENT_MARKS.omo ?? null,
+  cline: CLIENT_MARKS.cline ?? null,
 };
 
 /**
diff --git a/gui/src/components/provider-catalog/CatalogAccountRow.tsx b/gui/src/components/provider-catalog/CatalogAccountRow.tsx
new file mode 100644
index 0000000000..e5f824225d
--- /dev/null
+++ b/gui/src/components/provider-catalog/CatalogAccountRow.tsx
@@ -0,0 +1,130 @@
+/**
+ * One Accounts-tab login row. Split out of ProviderCatalog when unified search made the
+ * list composition (four groups, headings, jump chips) the interesting part of that file
+ * and this row's nine-way button matrix the noise. Behaviour is unchanged.
+ */
+import { useT } from "../../i18n/shared";
+import { LoginHint } from "../login-url-block";
+import { ProviderIcon } from "../provider-workspace/ProviderRail";
+import { shouldShowLoginHint, type CatalogLoginHint } from "./login-hint-visibility";
+import type { AccountLoginRow, AccountLoginStatus } from "./account-row-types";
+
+export default function CatalogAccountRow({
+  row,
+  status,
+  busyProvider,
+  loginHint,
+  paste,
+  onLogin,
+  onCancelLogin,
+  onLogout,
+  onManage,
+}: {
+  row: AccountLoginRow;
+  status?: AccountLoginStatus;
+  busyProvider: string | null;
+  loginHint: CatalogLoginHint | null;
+  paste?: {
+    value: string;
+    busy: boolean;
+    message: string;
+    ok: boolean;
+    onChange: (value: string) => void;
+    onSubmit: (provider: string) => void;
+  };
+  onLogin?: (provider: string, addAccount?: boolean) => void;
+  onCancelLogin?: (provider: string) => void;
+  onLogout?: (provider: string) => void;
+  onManage?: (provider: string) => void;
+}) {
+  const t = useT();
+  const busy = busyProvider === row.id;
+  const loggedIn = !!status?.loggedIn;
+  const statusText = loggedIn
+    ? (status?.email ?? row.statusLabel ?? t("modal.accountLoggedIn"))
+    : (status?.error ?? row.statusLabel ?? t("modal.accountLoggedOut"));
+  // A first-time add is the one moment the operator has no other way in:
+  // the provider has no workspace panel yet, so without this the
+  // authorization URL is computed and never drawn.
+  const showHint = shouldShowLoginHint(row, busyProvider, loginHint);
+  return (
+    <div className={`list-row provider-catalog-account-row${showHint ? " provider-catalog-account-row--waiting" : ""}`}>
+      <div className="provider-catalog-account-row-head">
+        {/* Account rows are providers too. A logo beside Cursor and a bare
+            tile beside Kiro reads as a bug, not as a distinction. */}
+        <ProviderIcon name={row.id} cls="provider-icon provider-icon-sm" />
+        <div>
+          <div className="title">{row.label}</div>
+          <div className="sub">{statusText}</div>
+        </div>
+        <div className="provider-catalog-badges">
+          {row.kind === "key" ? null : row.kind === "codex" ? (
+            <>
+              {loggedIn && (
+                <a className="btn btn-ghost" href={row.href ?? "#codex-set"}>{t("modal.accountManage")}</a>
+              )}
+              {onLogin && (
+                <button type="button"
+                  className={loggedIn ? "btn btn-ghost" : "btn btn-primary"}
+                  disabled={busy}
+                  onClick={() => { if (!busy) onLogin(row.id); }}
+                >
+                  {busy ? t("codexAuth.enablingOpenai") : loggedIn ? t("modal.accountAdd") : t("modal.accountLogin")}
+                </button>
+              )}
+            </>
+          ) : loggedIn ? (
+            <>
+              {onManage && (
+                <button type="button" className="btn btn-ghost" onClick={() => onManage(row.id)}>
+                  {t("modal.accountManage")}
+                </button>
+              )}
+              {onLogin && (
+                <button
+                  type="button"
+                  className="btn btn-ghost"
+                  disabled={busy}
+                  onClick={() => { if (!busy) onLogin(row.id, true); }}
+                >
+                  {busy ? t("prov.waitingBrowser") : t("modal.accountAdd")}
+                </button>
+              )}
+              {busy && onCancelLogin && (
+                <button type="button" className="btn btn-ghost" onClick={() => onCancelLogin(row.id)}>
+                  {t("common.cancel")}
+                </button>
+              )}
+              {onLogout && !busy && (
+                <button type="button" className="btn btn-ghost" onClick={() => onLogout(row.id)}>
+                  {t("modal.accountLogout")}
+                </button>
+              )}
+            </>
+          ) : busy ? (
+            onCancelLogin && <button type="button" className="btn btn-ghost" onClick={() => onCancelLogin(row.id)}>{t("common.cancel")}</button>
+          ) : (
+            onLogin && <button type="button" className="btn btn-primary" onClick={() => onLogin(row.id)}>{t("modal.accountLogin")}</button>
+          )}
+        </div>
+      </div>
+      {showHint && loginHint && (
+        <LoginHint
+          hint={{ url: loginHint.url, deviceCode: loginHint.deviceCode, instructions: loginHint.instructions }}
+          {...(paste
+            ? {
+              paste: {
+                value: paste.value,
+                busy: paste.busy,
+                message: paste.message,
+                ok: paste.ok,
+                onChange: paste.onChange,
+                onSubmit: () => paste.onSubmit(row.id),
+              },
+            }
+            : {})}
+        />
+      )}
+    </div>
+  );
+}
diff --git a/gui/src/components/provider-catalog/ProviderCatalog.tsx b/gui/src/components/provider-catalog/ProviderCatalog.tsx
index 82fe041b95..c342461733 100644
--- a/gui/src/components/provider-catalog/ProviderCatalog.tsx
+++ b/gui/src/components/provider-catalog/ProviderCatalog.tsx
@@ -1,32 +1,40 @@
 /**
  * ProviderCatalog — the browse surface of the add-provider modal: Accounts /
- * Free / Paid tabs over a single searchable scroll list, and account login
- * rows on the Accounts tab. Presentational: presets/usage arrive via props;
+ * Free / Local / Paid tabs over a single searchable scroll list, and account
+ * login rows on the Accounts tab. Presentational: presets/usage arrive via props;
  * view state (tab, query) lives here; selection lifts up.
  */
-import { useMemo, useState } from "react";
+import { Fragment, useEffect, useId, useMemo, useRef, useState } from "react";
 import { useT } from "../../i18n/shared";
 import {
   bucketPresets,
   pinSponsors,
-  filterPresets,
+  noteNeedsReveal,
+  matchesCatalogQuery,
+  sortCatalogMatches,
+  filterAccountRows,
+  dropPresetsCoveredByAccounts,
   type CatalogPreset,
+  type CatalogTier,
 } from "./provider-presets";
-import { shouldShowLoginHint, type CatalogLoginHint } from "./login-hint-visibility";
-import { LoginHint } from "../login-url-block";
+import { type CatalogLoginHint } from "./login-hint-visibility";
+import CatalogAccountRow from "./CatalogAccountRow";
+import type { AccountLoginRow, AccountLoginStatus } from "./account-row-types";
 import { ProviderIcon } from "../provider-workspace/ProviderRail";
 
-export type AccountLoginStatus = { loggedIn: boolean; email?: string; error?: string; needsReauth?: boolean };
-export type AccountLoginRow = {
-  id: string;
-  label: string;
-  kind: "oauth" | "key" | "codex";
-  statusLabel?: string;
-  /** Optional deep-link for codex/account-pool management. */
-  href?: string;
-};
+export type { AccountLoginRow, AccountLoginStatus };
 
-export type CatalogTier = "accounts" | "free" | "paid";
+export type { CatalogTier };
+
+/** Tab order. Local sits between Free and Paid: logged in, free cloud, my machine, billed. */
+const TIER_TABS = ["accounts", "free", "local", "paid"] as const;
+
+const TIER_TAB_LABEL = {
+  accounts: "modal.tab.accounts",
+  free: "modal.tab.free",
+  local: "modal.tab.local",
+  paid: "modal.tab.paid",
+} as const;
 
 const EMPTY_USAGE_RANK: Record<string, number> = {};
 const EMPTY_ACCOUNT_ROWS: AccountLoginRow[] = [];
@@ -37,8 +45,11 @@ export default function ProviderCatalog({
   usageRank = EMPTY_USAGE_RANK,
   presetsLoading = false,
   initialTier = "free",
+  query,
+  onQueryChange,
   onSelectPreset,
   onSelectCustom,
+  onShowNote,
   accountRows = EMPTY_ACCOUNT_ROWS,
   accountStatus = EMPTY_ACCOUNT_STATUS,
   busyProvider = null,
@@ -53,8 +64,18 @@ export default function ProviderCatalog({
   usageRank?: Record<string, number>;
   presetsLoading?: boolean;
   initialTier?: CatalogTier;
+  /**
+   * The unified search text, owned by the modal. It lives up there because the
+   * add-provider modal's Escape handler is on `window` and registers before this
+   * component's would: Escape has to clear a non-empty query instead of closing the
+   * dialog, and a child listener never gets the chance.
+   */
+  query: string;
+  onQueryChange: (value: string) => void;
   onSelectPreset: (preset: CatalogPreset) => void;
   onSelectCustom: () => void;
+  /** Open the full-note popup for a row whose note is clamped. Owned by the modal. */
+  onShowNote?: (preset: CatalogPreset) => void;
   /** Accounts-tab login rows; empty (default) degrades to preset-only rendering. */
   accountRows?: AccountLoginRow[];
   accountStatus?: Record<string, AccountLoginStatus>;
@@ -78,7 +99,19 @@ export default function ProviderCatalog({
 }) {
   const t = useT();
   const [tier, setTier] = useState<CatalogTier>(initialTier);
-  const [query, setQuery] = useState("");
+  const rowsId = useId();
+  const groupId = (candidate: CatalogTier) => `${rowsId}-${candidate}`;
+  const rowsRef = useRef<HTMLDivElement>(null);
+  const searching = query.trim().length > 0;
+
+  /**
+   * Entering or leaving search mode, and switching tabs, replaces the dataset entirely.
+   * Restoring an old scroll offset onto a different list lands somewhere meaningless, so
+   * the list goes back to the top instead.
+   */
+  useEffect(() => {
+    if (rowsRef.current) rowsRef.current.scrollTop = 0;
+  }, [tier, searching]);
 
   const catalog = useMemo(() => presets.filter(p => p.id !== "custom"), [presets]);
 
@@ -98,7 +131,96 @@ export default function ProviderCatalog({
 
   const buckets = useMemo(() => bucketPresets(pinSponsors(ranked)), [ranked]);
   const tierList = buckets[tier];
-  const rows = useMemo(() => filterPresets(tierList, query), [tierList, query]);
+
+  /**
+   * Search mode replaces browse mode rather than filtering inside it. While a query is
+   * live the selected tab is frozen and every group is rendered, because a jump from
+   * Free to Accounts would not merely change which rows are listed - it changes the kind
+   * of row, from a preset-select button to a login row with Log in and Add account
+   * buttons. Clearing the query returns to the tab the user actually chose.
+   */
+  const accountMatches = useMemo(
+    () => (searching ? filterAccountRows(accountRows, query, busyProvider) : accountRows),
+    [accountRows, query, searching, busyProvider],
+  );
+
+  const presetGroups = useMemo(() => {
+    const presetTabs = TIER_TABS.filter(candidate => candidate !== "accounts");
+    if (!searching) {
+      return tier === "accounts" ? [] : [{ tier, rows: tierList }];
+    }
+    return presetTabs.map(candidate => ({
+      tier: candidate,
+      rows: sortCatalogMatches(
+        dropPresetsCoveredByAccounts(
+          buckets[candidate].filter(p => matchesCatalogQuery(p, query)),
+          accountMatches,
+        ),
+        query,
+      ),
+    }));
+  }, [searching, tier, tierList, buckets, query, accountMatches]);
+
+  const counts = useMemo(() => {
+    const byTier = Object.fromEntries(presetGroups.map(group => [group.tier, group.rows.length])) as Record<CatalogTier, number>;
+    return { ...byTier, accounts: accountMatches.length } as Record<CatalogTier, number>;
+  }, [presetGroups, accountMatches]);
+
+  const totalMatches = TIER_TABS.reduce((sum, candidate) => sum + (counts[candidate] ?? 0), 0);
+  const matchedTiers = TIER_TABS.filter(candidate => (counts[candidate] ?? 0) > 0);
+
+  /**
+   * What is actually on screen right now. In browse mode that is one tab, and it is NOT
+   * `totalMatches`: the accounts bucket is unfiltered while browsing, and an OpenAI login
+   * row is almost always present, so keying the loading and empty states off the total
+   * left a still-loading Free tab rendering a blank pane instead of saying it was loading.
+   */
+  const visibleCount = searching
+    ? totalMatches
+    : tier === "accounts" ? accountMatches.length : (presetGroups[0]?.rows.length ?? 0);
+
+  /**
+   * A chip scrolls its group into view; it does not change `tier`. Focus moves to the
+   * heading so a keyboard user lands where they aimed - unless a login is in flight,
+   * because that row owns the paste field the user may be typing into.
+   */
+  const jumpToGroup = (candidate: CatalogTier) => {
+    const container = rowsRef.current;
+    // Looked up by data attribute rather than by id: the id comes from `useId`, which
+    // emits colons, so selecting on it needs `CSS.escape` — and `CSS` does not exist in
+    // the happy-dom environment the GUI tests run in, so a chip click would throw there
+    // rather than merely be untested. The tier values are plain lowercase words.
+    const heading = container?.querySelector<HTMLElement>(`[data-catalog-group="${candidate}"]`);
+    if (!container || !heading) return;
+    // Scroll the list itself rather than calling scrollIntoView: `.modal-card` is also a
+    // scroll container, so delegating to the browser can drag the search field out of
+    // view while jumping between groups inside a 360px list.
+    container.scrollTop = heading.offsetTop - container.offsetTop;
+    // `preventScroll` for the same reason the scroll is manual: the default would let the
+    // focus move drag the translucent modal card that the list sits inside.
+    if (!busyProvider) heading.focus({ preventScroll: true });
+  };
+
+  /** ArrowDown out of the input lands on the first result, never on a chip. */
+  const onSearchKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
+    if (e.key !== "ArrowDown") return;
+    const first = rowsRef.current?.querySelector<HTMLElement>("button:not(:disabled), a[href]");
+    if (!first) return;
+    e.preventDefault();
+    first.focus();
+  };
+
+  const groupHeading = (candidate: CatalogTier, count: number) => (
+    <h4
+      id={groupId(candidate)}
+      data-catalog-group={candidate}
+      className="provider-catalog-group-head"
+      tabIndex={-1}
+    >
+      <span>{t(TIER_TAB_LABEL[candidate])}</span>
+      <span className="provider-catalog-group-count">{count}</span>
+    </h4>
+  );
 
   const badges = (p: CatalogPreset) => {
     const auth = p.codexAccountMode === "direct" ? <span className="badge badge-green">{t("modal.badge.direct")}</span>
@@ -121,158 +243,141 @@ export default function ProviderCatalog({
 
   return (
     <div className="provider-catalog">
-      <div className="provider-catalog-tabs" role="tablist">
-        {(["accounts", "free", "paid"] as const).map(candidate => (
-          <button type="button"
-            key={candidate}
-            role="tab"
-            aria-selected={tier === candidate}
-            className={`provider-catalog-tab${tier === candidate ? " active" : ""}`}
-            onClick={() => { setTier(candidate); setQuery(""); }}
-          >
-            {t(candidate === "accounts" ? "modal.tab.accounts" : candidate === "free" ? "modal.tab.free" : "modal.tab.paid")}
-          </button>
-        ))}
-      </div>
+      {/* Search first, then the filters it overrides. It reaches every tab, so putting it
+          under one tab's header would say the opposite of what it does. */}
+      <input
+        className="input provider-catalog-search"
+        type="search"
+        value={query}
+        onChange={e => onQueryChange(e.target.value)}
+        onKeyDown={onSearchKeyDown}
+        placeholder={t("modal.search")}
+        aria-label={t("modal.search")}
+      />
+
+      {searching ? (
+        // Not a tablist any more: the panel below is showing every group, so a `tab` with
+        // `aria-selected` would announce "Free, selected" over a Paid row. These are jump
+        // chips with counts, and a chip with no matches is disabled rather than hidden so
+        // the strip does not reflow under the pointer on every keystroke.
+        <div className="provider-catalog-tabs provider-catalog-tabs--chips">
+          {TIER_TABS.map(candidate => (
+            <button type="button"
+              key={candidate}
+              className="provider-catalog-tab provider-catalog-chip"
+              disabled={(counts[candidate] ?? 0) === 0}
+              // An empty group renders nothing, so pointing at its id would dangle.
+              {...((counts[candidate] ?? 0) > 0 ? { "aria-controls": groupId(candidate) } : {})}
+              onClick={() => jumpToGroup(candidate)}
+            >
+              {t(TIER_TAB_LABEL[candidate])}
+              <span className="provider-catalog-chip-count">{counts[candidate] ?? 0}</span>
+            </button>
+          ))}
+        </div>
+      ) : (
+        <div className="provider-catalog-tabs" role="tablist">
+          {TIER_TABS.map(candidate => (
+            <button type="button"
+              key={candidate}
+              role="tab"
+              aria-selected={tier === candidate}
+              aria-controls={rowsId}
+              className={`provider-catalog-tab${tier === candidate ? " active" : ""}`}
+              onClick={() => setTier(candidate)}
+            >
+              {t(TIER_TAB_LABEL[candidate])}
+            </button>
+          ))}
+        </div>
+      )}
 
-      {tier === "accounts" && (
+      {!searching && tier === "accounts" && (
         <div className="provider-catalog-accounts-hint muted text-label">
           {t("modal.accountsHint")}
         </div>
       )}
 
-      <input
-        className="input provider-catalog-search"
-        value={query}
-        onChange={e => setQuery(e.target.value)}
-        placeholder={t("modal.search")}
-      />
+      <div className="sr-only" aria-live="polite" aria-atomic="true">
+        {searching
+          ? (totalMatches === 0
+            ? t("modal.noMatch")
+            : t("modal.searchResults", {
+              count: totalMatches,
+              tiers: matchedTiers.map(candidate => t(TIER_TAB_LABEL[candidate])).join(", "),
+            }))
+          : ""}
+      </div>
 
-      <div className="provider-catalog-rows">
-        {presetsLoading && rows.length === 0 && (
+      <div className="provider-catalog-rows" id={rowsId} ref={rowsRef}>
+        {presetsLoading && visibleCount === 0 && (
           <div className="muted text-control provider-catalog-empty">{t("modal.catalogLoading")}</div>
         )}
-        {tier !== "accounts" && rows.map(p => (
-          <button type="button" key={p.id} className="list-row" onClick={() => onSelectPreset(p)}>
-            {/*
-              The one list a user reads to CHOOSE a provider, and until now the only
-              provider surface with no marks at all. `CatalogPreset.id` is the
-              registry id, so this reuses `providerIconSrc` and, with it, the
-              mask/plate decision the rail already owns -- a mark cannot be legible
-              in the workspace and invisible here.
-            */}
-            <ProviderIcon name={p.id} adapter={p.adapter} cls="provider-icon provider-icon-sm" />
-            <div>
-              <div className="title">{p.label}</div>
-              <div className="sub"><code className="chip">{p.adapter}</code>{p.note ? ` · ${p.note}` : ""}</div>
-            </div>
-            <div className="provider-catalog-badges">{badges(p)}</div>
-          </button>
-        ))}
-        {tier !== "accounts" && !presetsLoading && rows.length === 0 && (
-          <div className="muted text-control provider-catalog-empty">{t("modal.noMatch")}</div>
+        {(searching || tier === "accounts") && accountMatches.length > 0 && (
+          <Fragment key="accounts">
+            {searching && groupHeading("accounts", accountMatches.length)}
+            {accountMatches.map(row => (
+              <CatalogAccountRow
+                key={row.id}
+                row={row}
+                status={accountStatus[row.id]}
+                busyProvider={busyProvider}
+                loginHint={loginHint}
+                {...(paste ? { paste } : {})}
+                {...(onLogin ? { onLogin } : {})}
+                {...(onCancelLogin ? { onCancelLogin } : {})}
+                {...(onLogout ? { onLogout } : {})}
+                {...(onManage ? { onManage } : {})}
+              />
+            ))}
+          </Fragment>
         )}
-
-        {tier === "accounts" && accountRows.map(row => {
-          const status = accountStatus[row.id];
-          const busy = busyProvider === row.id;
-          const loggedIn = !!status?.loggedIn;
-          const statusText = loggedIn
-            ? (status?.email ?? row.statusLabel ?? t("modal.accountLoggedIn"))
-            : (status?.error ?? row.statusLabel ?? t("modal.accountLoggedOut"));
-          // A first-time add is the one moment the operator has no other way in:
-          // the provider has no workspace panel yet, so without this the
-          // authorization URL is computed and never drawn.
-          const showHint = shouldShowLoginHint(row, busyProvider, loginHint);
-          return (
-            <div key={row.id} className={`list-row provider-catalog-account-row${showHint ? " provider-catalog-account-row--waiting" : ""}`}>
-              <div className="provider-catalog-account-row-head">
-              {/* Account rows are providers too. A logo beside Cursor and a bare
-                  tile beside Kiro reads as a bug, not as a distinction. */}
-              <ProviderIcon name={row.id} cls="provider-icon provider-icon-sm" />
+        {presetGroups.map(group => group.rows.length === 0 ? null : (
+          <Fragment key={group.tier}>
+          {searching && groupHeading(group.tier, group.rows.length)}
+          {group.rows.map(p => (
+          // The reveal control is a SIBLING of the row button, never a child of it: the row
+          // is already a <button>, and a button inside a button is invalid HTML that the
+          // parser may hoist out of the row -- at which point `stopPropagation` never runs.
+          <div key={p.id} className="provider-catalog-row-wrap">
+            <button type="button" className="list-row" onClick={() => onSelectPreset(p)}>
+              {/*
+                The one list a user reads to CHOOSE a provider, and until now the only
+                provider surface with no marks at all. `CatalogPreset.id` is the
+                registry id, so this reuses `providerIconSrc` and, with it, the
+                mask/plate decision the rail already owns -- a mark cannot be legible
+                in the workspace and invisible here.
+              */}
+              <ProviderIcon name={p.id} adapter={p.adapter} cls="provider-icon provider-icon-sm" />
               <div>
-                <div className="title">{row.label}</div>
-                <div className="sub">{statusText}</div>
+                <div className="title">{p.label}</div>
+                <div className="sub"><code className="chip">{p.adapter}</code>{p.note ? ` · ${p.note}` : ""}</div>
               </div>
-              <div className="provider-catalog-badges">
-                {row.kind === "key" ? null : row.kind === "codex" ? (
-                  <>
-                    {loggedIn && (
-                      <a className="btn btn-ghost" href={row.href ?? "#codex-set"}>{t("modal.accountManage")}</a>
-                    )}
-                    {onLogin && (
-                      <button type="button"
-                        className={loggedIn ? "btn btn-ghost" : "btn btn-primary"}
-                        disabled={busy}
-                        onClick={() => { if (!busy) onLogin(row.id); }}
-                      >
-                        {busy ? t("codexAuth.enablingOpenai") : loggedIn ? t("modal.accountAdd") : t("modal.accountLogin")}
-                      </button>
-                    )}
-                  </>
-                ) : loggedIn ? (
-                  <>
-                    {onManage && (
-                      <button type="button" className="btn btn-ghost" onClick={() => onManage(row.id)}>
-                        {t("modal.accountManage")}
-                      </button>
-                    )}
-                    {onLogin && (
-                      <button
-                        type="button"
-                        className="btn btn-ghost"
-                        disabled={busy}
-                        onClick={() => { if (!busy) onLogin(row.id, true); }}
-                      >
-                        {busy ? t("prov.waitingBrowser") : t("modal.accountAdd")}
-                      </button>
-                    )}
-                    {busy && onCancelLogin && (
-                      <button type="button" className="btn btn-ghost" onClick={() => onCancelLogin(row.id)}>
-                        {t("common.cancel")}
-                      </button>
-                    )}
-                    {onLogout && !busy && (
-                      <button type="button" className="btn btn-ghost" onClick={() => onLogout(row.id)}>
-                        {t("modal.accountLogout")}
-                      </button>
-                    )}
-                  </>
-                ) : busy ? (
-                  onCancelLogin && <button type="button" className="btn btn-ghost" onClick={() => onCancelLogin(row.id)}>{t("common.cancel")}</button>
-                ) : (
-                  onLogin && <button type="button" className="btn btn-primary" onClick={() => onLogin(row.id)}>{t("modal.accountLogin")}</button>
-                )}
-              </div>
-              </div>
-              {showHint && loginHint && (
-                <LoginHint
-                  hint={{ url: loginHint.url, deviceCode: loginHint.deviceCode, instructions: loginHint.instructions }}
-                  {...(paste
-                    ? {
-                      paste: {
-                        value: paste.value,
-                        busy: paste.busy,
-                        message: paste.message,
-                        ok: paste.ok,
-                        onChange: paste.onChange,
-                        onSubmit: () => paste.onSubmit(row.id),
-                      },
-                    }
-                    : {})}
-                />
-              )}
-            </div>
-          );
-        })}
-        {tier === "accounts" && accountRows.length === 0 && !presetsLoading && (
+              <div className="provider-catalog-badges">{badges(p)}</div>
+            </button>
+            {onShowNote && noteNeedsReveal(p.note) && (
+              <button
+                type="button"
+                className="link-btn provider-catalog-note-more"
+                onClick={() => onShowNote(p)}
+              >
+                {t("modal.noteMore")}
+              </button>
+            )}
+          </div>
+        ))}
+          </Fragment>
+        ))}
+        {!presetsLoading && visibleCount === 0 && (
           <div className="muted text-control provider-catalog-empty">{t("modal.noMatch")}</div>
         )}
       </div>
 
       <div className="provider-catalog-footer">
         <div style={{ flex: 1 }} />
-        {tier !== "accounts" && (
+        {/* Browse copy. "Not listed?" is the escape hatch at the end of a list you read,
+            not a search result, so it stays out of the way while a query is live. */}
+        {!searching && tier !== "accounts" && (
           <button type="button" className="link-btn" onClick={onSelectCustom}>{t("modal.notListed")}</button>
         )}
       </div>
diff --git a/gui/src/components/provider-catalog/ProviderNoteModal.tsx b/gui/src/components/provider-catalog/ProviderNoteModal.tsx
new file mode 100644
index 0000000000..cbaaf3f0fe
--- /dev/null
+++ b/gui/src/components/provider-catalog/ProviderNoteModal.tsx
@@ -0,0 +1,84 @@
+/**
+ * Full-text popup for a catalog row's provider note.
+ *
+ * The catalog clamps a note to two lines, because a few of them are paragraphs: the
+ * `opencode-free` note is ~1100 characters and `meta-muse` is longer still, and at the
+ * modal width either one fills the entire 360px scroll viewport, so the row it belongs
+ * to becomes the only row a user can see.
+ *
+ * Native `<dialog>` + `showModal()`, deliberately the same shape as
+ * `OAuthTosWarningModal`: it gives focus trapping and a backdrop for free, and — the
+ * part a hand-rolled overlay does not get — it restores focus to the control that
+ * opened it when it closes. It is rendered as a sibling of the add-provider overlay
+ * rather than inside it, so there is no dialog nested in a dialog's DOM.
+ */
+import { useCallback, useEffect, useId, useRef } from "react";
+import { useT } from "../../i18n/shared";
+import { IconX } from "../../icons";
+import { ProviderIcon } from "../provider-workspace/ProviderRail";
+
+export default function ProviderNoteModal({
+  providerId,
+  label,
+  adapter,
+  note,
+  onClose,
+}: {
+  providerId: string;
+  label: string;
+  adapter: string;
+  note: string;
+  onClose: () => void;
+}) {
+  const t = useT();
+  const titleId = useId();
+  const bodyId = useId();
+  const dialogRef = useRef<HTMLDialogElement>(null);
+
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    const trigger = document.activeElement as HTMLElement | null;
+    if (dialog && !dialog.open) dialog.showModal();
+    return () => {
+      if (dialog?.open) dialog.close();
+      if (trigger?.isConnected) trigger.focus({ preventScroll: true });
+    };
+  }, []);
+
+  // Native <dialog> fires "cancel" on Escape — forward it so this popup closes first
+  // and the add-provider modal underneath stays open.
+  const handleCancel = useCallback((e: React.SyntheticEvent) => {
+    e.preventDefault();
+    onClose();
+  }, [onClose]);
+
+  return (
+    <dialog
+      ref={dialogRef}
+      aria-labelledby={titleId}
+      aria-describedby={bodyId}
+      className="modal-overlay"
+      onCancel={handleCancel}
+    >
+      <button type="button" className="modal-backdrop-dismiss" aria-label={t("common.close")} tabIndex={-1} onClick={onClose} />
+      <div className="modal-card provider-note-card" onClick={e => e.stopPropagation()}>
+        <div className="modal-head">
+          <h3 id={titleId} className="provider-note-title">
+            <ProviderIcon name={providerId} adapter={adapter} cls="provider-icon provider-icon-sm" />
+            {label}
+          </h3>
+          <button type="button" className="btn btn-ghost btn-icon" aria-label={t("common.close")} onClick={onClose}>
+            <IconX />
+          </button>
+        </div>
+        <div id={bodyId} className="provider-note-body">
+          <code className="chip">{adapter}</code>
+          <p className="modal-desc provider-note-text">{note}</p>
+        </div>
+        <div className="modal-actions">
+          <button type="button" className="btn btn-ghost" onClick={onClose}>{t("common.close")}</button>
+        </div>
+      </div>
+    </dialog>
+  );
+}
diff --git a/gui/src/components/provider-catalog/account-row-types.ts b/gui/src/components/provider-catalog/account-row-types.ts
new file mode 100644
index 0000000000..e1a63d41ff
--- /dev/null
+++ b/gui/src/components/provider-catalog/account-row-types.ts
@@ -0,0 +1,15 @@
+/**
+ * Shapes shared by the catalog's Accounts rows. They live here rather than in
+ * ProviderCatalog so CatalogAccountRow can import them without a cycle back through
+ * the component that renders it.
+ */
+export type AccountLoginStatus = { loggedIn: boolean; email?: string; error?: string; needsReauth?: boolean };
+
+export type AccountLoginRow = {
+  id: string;
+  label: string;
+  kind: "oauth" | "key" | "codex";
+  statusLabel?: string;
+  /** Optional deep-link for codex/account-pool management. */
+  href?: string;
+};
diff --git a/gui/src/components/provider-catalog/provider-presets.ts b/gui/src/components/provider-catalog/provider-presets.ts
index ae05e55e7f..d030bd158a 100644
--- a/gui/src/components/provider-catalog/provider-presets.ts
+++ b/gui/src/components/provider-catalog/provider-presets.ts
@@ -7,6 +7,7 @@
  */
 
 import { providerTier, type ProviderTier, type WorkspaceProvider, type WorkspaceItem } from "../../provider-workspace/catalog";
+import { isLocalProvider } from "../../provider-workspace/kind";
 import type { ProviderPayload } from "../../provider-payload";
 
 /** Row shape returned by GET /api/provider-presets (mirrors DerivedProviderPreset). */
@@ -73,10 +74,41 @@ export function presetTier(preset: CatalogPreset): ProviderTier {
   return providerTier(preset.id, presetTierInput(preset));
 }
 
-/** Tab buckets for the catalog: accounts / free / paid, preserving input order per bucket. */
-export function bucketPresets(presets: CatalogPreset[]): Record<ProviderTier, CatalogPreset[]> {
-  const buckets: Record<ProviderTier, CatalogPreset[]> = { accounts: [], free: [], paid: [] };
-  for (const preset of presets) buckets[presetTier(preset)].push(preset);
+/**
+ * Browse tabs in the add-provider catalog. Four-way, and deliberately NOT `ProviderTier`:
+ * the workspace keeps a three-way pricing/ownership tier for badges, rail sorting and the
+ * Free count, where `isFreeProvider` folds local runtimes into free on purpose. Only the
+ * catalog needs Local as a browse destination, so the split stops at this file.
+ */
+export type CatalogTier = "accounts" | "free" | "local" | "paid";
+
+/**
+ * A local-runtime row: explicit `local` auth or a loopback base URL. Delegates to the one
+ * helper the providers rail already classifies with, so a preset and its configured
+ * counterpart can never disagree about being local.
+ */
+export function isLocalCatalogPreset(preset: CatalogPreset): boolean {
+  return isLocalProvider(presetTierInput(preset));
+}
+
+/** Tab buckets for the catalog: accounts / free / local / paid, preserving input order per bucket. */
+export function bucketPresets(presets: CatalogPreset[]): Record<CatalogTier, CatalogPreset[]> {
+  const buckets: Record<CatalogTier, CatalogPreset[]> = { accounts: [], free: [], local: [], paid: [] };
+  for (const preset of presets) {
+    // Local is peeled off AFTER `presetTier` has spoken, which is what lets `presetTier`
+    // keep returning `"free"` for Ollama and leaves the workspace Free count untouched.
+    //
+    // Accounts is checked first as a forward guard, not because the case can arise today:
+    // `isAccountProvider` requires the exact `https://chatgpt.com/backend-api/codex` base
+    // URL, so no row can be both accounts-tier and loopback. If that classifier is ever
+    // widened, this ordering is what stops a local-looking account row from being pulled
+    // out of the tab where a user logs in.
+    const tier = presetTier(preset);
+    const bucket: CatalogTier = tier === "accounts" ? "accounts"
+      : isLocalCatalogPreset(preset) ? "local"
+      : tier;
+    buckets[bucket].push(preset);
+  }
   return buckets;
 }
 
@@ -87,6 +119,96 @@ export function filterPresets(presets: CatalogPreset[], query: string): CatalogP
   return presets.filter(p => p.label.toLowerCase().includes(q) || p.id.toLowerCase().includes(q));
 }
 
+/** Every nonempty note has a full-text route: rendered clipping depends on width,
+ * adapter chips and badges, so no character threshold can safely hide the control. */
+export function noteNeedsReveal(note: string | undefined): boolean {
+  return !!note?.trim();
+}
+
+/**
+ * Queries that mean "a runtime on my own machine" without naming one. Resolved through
+ * `isLocalCatalogPreset` rather than a substring match, so `localhost` finds the Local
+ * group instead of matching every base URL that happens to contain the word.
+ */
+const LOCAL_QUERY_ALIASES = new Set(["local", "localhost", "ollama", "vllm", "lmstudio", "lm studio", "self-hosted", "selfhosted"]);
+
+/**
+ * Unified-search match for one preset.
+ *
+ * The haystack stays label + id, for the same reason `filterPresets` documents: a
+ * substring match on the adapter would return Ollama, vLLM, LM Studio, Groq, Cerebras
+ * and PackyCode for the query `openai`, and matching base URLs would return every local
+ * row for `localhost`. It widens in exactly two controlled ways instead — an *equality*
+ * match on the adapter id, so `cursor` finds Cursor while `openai` still does not match
+ * `openai-chat`, and the local aliases above.
+ */
+export function matchesCatalogQuery(preset: CatalogPreset, query: string): boolean {
+  const q = query.trim().toLowerCase();
+  if (!q) return true;
+  if (preset.label.toLowerCase().includes(q)) return true;
+  if (preset.id.toLowerCase().includes(q)) return true;
+  if (preset.adapter.toLowerCase() === q) return true;
+  return LOCAL_QUERY_ALIASES.has(q) && isLocalCatalogPreset(preset);
+}
+
+/**
+ * Order matched rows WITHIN one group: exact id or label first, then a label/id prefix,
+ * then everything else in the order the caller already established — which carries the
+ * sponsor pin, then usage rank, then label. Deliberately never applied across groups: a
+ * paid sponsor sorted above free NVIDIA on the query `nim` reads as an ad slot, and the
+ * sponsor already has a badge and a pin inside its own group.
+ */
+export function sortCatalogMatches(presets: CatalogPreset[], query: string): CatalogPreset[] {
+  const q = query.trim().toLowerCase();
+  if (!q) return presets;
+  const rank = (p: CatalogPreset): number => {
+    const label = p.label.toLowerCase();
+    const id = p.id.toLowerCase();
+    if (id === q || label === q) return 0;
+    if (label.startsWith(q) || id.startsWith(q)) return 1;
+    return 2;
+  };
+  return presets
+    .map((preset, index) => ({ preset, index }))
+    .sort((a, b) => rank(a.preset) - rank(b.preset) || a.index - b.index)
+    .map(entry => entry.preset);
+}
+
+/**
+ * Account-tab login rows are a different shape from presets and are built elsewhere, so
+ * they get their own label/id filter rather than a widened `filterPresets`.
+ *
+ * `pinnedId` is the provider with a login in flight. It survives a non-matching query on
+ * purpose: the row owns the authorization URL and the paste field, and unmounting it
+ * mid-login throws away what the user is in the middle of doing.
+ */
+export function filterAccountRows<T extends { id: string; label: string }>(
+  rows: readonly T[],
+  query: string,
+  pinnedId?: string | null,
+): T[] {
+  const q = query.trim().toLowerCase();
+  if (!q) return [...rows];
+  return rows.filter(row =>
+    row.id === pinnedId
+    || row.label.toLowerCase().includes(q)
+    || row.id.toLowerCase().includes(q));
+}
+
+/**
+ * Drop presets that a matched login row already represents. A login row and a preset can
+ * share an id (`openai`); the login row is the one that can actually be acted on, so it
+ * wins rather than the same provider appearing twice under two different tiers.
+ */
+export function dropPresetsCoveredByAccounts(
+  presets: CatalogPreset[],
+  accountRows: readonly { id: string }[],
+): CatalogPreset[] {
+  if (accountRows.length === 0) return presets;
+  const covered = new Set(accountRows.map(row => row.id));
+  return presets.filter(preset => !covered.has(preset.id));
+}
+
 const SPONSOR_RANK: Record<NonNullable<CatalogPreset["sponsor"]>, number> = { main: 0, standard: 1 };
 
 /**
diff --git a/gui/src/components/provider-workspace/AnthropicAccountPoolSettings.tsx b/gui/src/components/provider-workspace/AnthropicAccountPoolSettings.tsx
index 4d7c66b970..84120b54c4 100644
--- a/gui/src/components/provider-workspace/AnthropicAccountPoolSettings.tsx
+++ b/gui/src/components/provider-workspace/AnthropicAccountPoolSettings.tsx
@@ -4,6 +4,7 @@
  */
 import { useCallback, useEffect, useState } from "react";
 import { useT } from "../../i18n/shared";
+import { getPoolSettings, putPoolSettings } from "../../pool-settings";
 import {
   ACCOUNT_POOL_QUOTA_WINDOWS,
   DEFAULT_ACCOUNT_POOL_QUOTA_WINDOW,
@@ -60,16 +61,11 @@ export default function AnthropicAccountPoolSettings({
     // mount-then-unmount dropped the request entirely. The abort controller already covers
     // in-flight cancellation, which is the part that actually needs to be cancellable.
     void Promise.resolve()
-      .then(() => fetch(`${apiBase}/api/oauth/accounts/pool?provider=anthropic`, { signal: ac.signal }))
-      .then(res => {
-        if (!res.ok) throw new Error("load");
-        return res.json() as Promise<{
-          enabled?: boolean;
-          autoSwitchThreshold?: number;
-          strategy?: unknown;
-          stickyLimit?: unknown;
-          quotaWindow?: unknown;
-        }>;
+      // Through the shared pool client, which speaks the one contract every kind answers on.
+      .then(() => getPoolSettings(apiBase, "anthropic", (input, init) => fetch(input, init), { signal: ac.signal }))
+      .then(settings => {
+        if (!settings) throw new Error("load");
+        return settings;
       })
       .then(json => {
         if (cancelled) return;
@@ -114,24 +110,16 @@ export default function AnthropicAccountPoolSettings({
     setSaving(true);
     setError(null);
     try {
-      const res = await fetch(`${apiBase}/api/oauth/accounts/pool`, {
-        method: "PUT",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({
-          provider: "anthropic",
-          enabled: next.enabled,
-          autoSwitchThreshold: next.threshold,
-          strategy: next.strategy,
-          stickyLimit: next.stickyLimit,
-          quotaWindow: next.quotaWindow,
-        }),
+      // The client owns the field mapping: `threshold` becomes `autoSwitchThreshold` and the
+      // provider is always sent, so no call site can forget either.
+      const json = await putPoolSettings(apiBase, "anthropic", {
+        enabled: next.enabled,
+        threshold: next.threshold,
+        strategy: next.strategy,
+        stickyLimit: next.stickyLimit,
+        quotaWindow: next.quotaWindow,
       });
-      if (!res.ok) throw new Error("save");
-      const json = await res.json().catch(() => null) as {
-        strategy?: unknown;
-        stickyLimit?: unknown;
-        quotaWindow?: unknown;
-      } | null;
+      if (!json) throw new Error("save");
       const savedStrategy = normalizeAccountPoolStrategy(json?.strategy ?? next.strategy);
       const savedSticky = normalizeAccountPoolStickyLimit(json?.stickyLimit ?? next.stickyLimit);
       const savedWindow = normalizeAccountPoolQuotaWindow(json?.quotaWindow ?? next.quotaWindow);
diff --git a/gui/src/components/provider-workspace/GrokResetCoupons.tsx b/gui/src/components/provider-workspace/GrokResetCoupons.tsx
new file mode 100644
index 0000000000..d0deca4fd0
--- /dev/null
+++ b/gui/src/components/provider-workspace/GrokResetCoupons.tsx
@@ -0,0 +1,310 @@
+/**
+ * Grok reset-coupon badge and redemption dialog for xAI OAuth account rows.
+ *
+ * The dialog is deliberately conservative about the one irreversible thing it
+ * does. It always names the coupon it is spending, it holds one client-minted
+ * operation id per confirmation, and when a redemption aborts it stops posting
+ * entirely: the route re-executes a redemption whose journal record is still
+ * open, so a retry after a timeout can spend a second coupon.
+ */
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useI18n, type Locale, type TFn, type TKey } from "../../i18n/shared";
+import { IconAlert, IconTicket } from "../../icons";
+import { daysUntil, formatCreditDate, formatCreditDateTime } from "../codex-account-pool-utils";
+import type { GrokCouponEntry, GrokResetCoupon, GrokResetCouponController } from "../../hooks/useGrokResetCoupons";
+
+function couponsOf(entry: GrokCouponEntry | undefined): GrokResetCoupon[] {
+  return entry?.status === "ready" ? entry.coupons : [];
+}
+
+function newOperationId(): string | undefined {
+  const api = globalThis.crypto;
+  if (api && typeof api.randomUUID === "function") return api.randomUUID();
+  if (api && typeof api.getRandomValues === "function") {
+    const bytes = api.getRandomValues(new Uint8Array(16));
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = [...bytes].map(byte => byte.toString(16).padStart(2, "0")).join("");
+    return [hex.slice(0, 8), hex.slice(8, 12), hex.slice(12, 16), hex.slice(16, 20), hex.slice(20)].join("-");
+  }
+  // Without an id the journal cannot recognise a repeat, so the dialog refuses
+  // rather than letting the route mint a fresh id per attempt.
+  return undefined;
+}
+
+const FAILURE_KEYS: Record<string, TKey> = {
+  auth_failed: "grokCoupon.authFailed",
+  no_account: "grokCoupon.noAccount",
+  no_coupons_available: "grokCoupon.noneAvailable",
+  operation_id_owned_by_another_account: "grokCoupon.identityMismatch",
+  capacity: "grokCoupon.capacity",
+  unavailable: "grokCoupon.capacity",
+  network: "grokCoupon.networkError",
+  redeem_failed: "grokCoupon.redeemFailed",
+};
+
+/** Ticket badge on an xAI account row. Muted at zero, amber when redeemable. */
+export function GrokCouponBadge({ entry, onClick, t }: {
+  entry: GrokCouponEntry | undefined;
+  onClick: () => void;
+  t: TFn;
+}) {
+  if (entry === undefined || entry.status === "loading") {
+    // Reserve the width so the row does not shift when the count lands. Same
+    // aria-hidden placeholder the Codex ticket badge uses.
+    return (
+      <span className="badge badge-muted codex-ticket-badge-slot" aria-hidden="true">
+        <IconTicket width={12} />0
+      </span>
+    );
+  }
+  const count = entry.status === "ready" ? entry.coupons.length : null;
+  const label = count === null
+    ? t("grokCoupon.badgeErrorAria")
+    : t("grokCoupon.badgeAria", { count: String(count) });
+  return (
+    <button
+      type="button"
+      className={`badge ${count ? "badge-amber" : "badge-muted"} badge-clickable`}
+      data-grok-coupon-badge={count === null ? "error" : String(count)}
+      onClick={event => { event.stopPropagation(); onClick(); }}
+      aria-label={label}
+      title={label}
+    >
+      <IconTicket width={12} />
+      {count === null ? <IconAlert width={11} /> : count}
+    </button>
+  );
+}
+
+function GrokCouponItem({ coupon, index, isNext, locale, t }: {
+  coupon: GrokResetCoupon;
+  index: number;
+  isNext: boolean;
+  locale: Locale;
+  t: TFn;
+}) {
+  const days = coupon.validityEnd ? daysUntil(coupon.validityEnd) : null;
+  return (
+    <div className={`credit-item${isNext ? " credit-next" : ""}`}>
+      <div className="credit-item-head">
+        <IconTicket width={13} />
+        <span className="credit-item-label">
+          {isNext ? t("grokCoupon.couponNext") : t("grokCoupon.couponLabel", { n: String(index + 1) })}
+        </span>
+        {isNext && (
+          <span className="badge badge-amber text-micro" style={{ padding: "1px 6px" }}>
+            {t("grokCoupon.couponNextBadge")}
+          </span>
+        )}
+      </div>
+      <div className="credit-item-dates">
+        {coupon.validityStart && <span>{t("grokCoupon.validFrom", { date: formatCreditDate(coupon.validityStart, locale) })}</span>}
+        {days !== null && (
+          <span className={days <= 7 ? "credit-urgent" : ""}>
+            {t("grokCoupon.expires", { date: formatCreditDateTime(coupon.validityEnd, locale), days: String(days) })}
+          </span>
+        )}
+      </div>
+    </div>
+  );
+}
+
+type Outcome = { tone: "ok" | "warn"; key: TKey };
+
+export function GrokResetCouponModal({ accountId, accountLabel, entry, controller, onClose }: {
+  accountId: string;
+  accountLabel: string;
+  entry: GrokCouponEntry | undefined;
+  controller: GrokResetCouponController;
+  onClose: () => void;
+}) {
+  const { locale, t } = useI18n();
+  const dialogRef = useRef<HTMLDialogElement>(null);
+  const redeemRef = useRef<HTMLButtonElement>(null);
+  const [confirming, setConfirming] = useState(false);
+  const [redeeming, setRedeeming] = useState(false);
+  const [checking, setChecking] = useState(false);
+  /** Set by an aborted redemption; while it holds, the dialog posts nothing. */
+  const [unknown, setUnknown] = useState<{ tokenId: string } | null>(null);
+  const [outcome, setOutcome] = useState<Outcome | null>(null);
+  const operationIdRef = useRef<string | undefined>(undefined);
+
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (dialog && !dialog.open) dialog.showModal();
+  }, []);
+
+  useEffect(() => {
+    if (confirming) redeemRef.current?.focus();
+  }, [confirming]);
+
+  const handleCancel = useCallback((event: React.SyntheticEvent) => {
+    event.preventDefault();
+    onClose();
+  }, [onClose]);
+
+  const coupons = couponsOf(entry);
+  const next = coupons[0];
+
+  const startConfirm = () => {
+    if (unknown) return;
+    const id = newOperationId();
+    if (!id) {
+      setOutcome({ tone: "warn", key: "grokCoupon.noOperationId" });
+      return;
+    }
+    operationIdRef.current = id;
+    setOutcome(null);
+    setConfirming(true);
+  };
+
+  const redeem = async () => {
+    if (redeeming || unknown) return;
+    const operationId = operationIdRef.current;
+    if (!next?.tokenId) {
+      setOutcome({ tone: "warn", key: "grokCoupon.noneAvailable" });
+      return;
+    }
+    if (!operationId) {
+      setOutcome({ tone: "warn", key: "grokCoupon.noOperationId" });
+      return;
+    }
+    setRedeeming(true);
+    const result = await controller.redeem(accountId, { tokenId: next.tokenId, operationId });
+    setRedeeming(false);
+    if (result.ok) {
+      operationIdRef.current = undefined;
+      setConfirming(false);
+      setOutcome({ tone: "ok", key: result.replayed ? "grokCoupon.redeemReplayed" : "grokCoupon.redeemSuccess" });
+      return;
+    }
+    if (result.code === "aborted") {
+      // Outcome unknown: hold the id, stop posting, and let the user re-read.
+      setUnknown({ tokenId: next.tokenId });
+      setOutcome(null);
+      void controller.refresh(accountId);
+      return;
+    }
+    if (result.code === "operation_id_owned_by_another_account") operationIdRef.current = undefined;
+    setOutcome({ tone: "warn", key: FAILURE_KEYS[result.code] ?? "grokCoupon.redeemFailed" });
+  };
+
+  const recheck = async () => {
+    if (!unknown || checking) return;
+    setChecking(true);
+    await controller.refresh(accountId);
+    setChecking(false);
+  };
+
+  const unresolvedToken = unknown
+    ? couponsOf(entry).some(coupon => coupon.tokenId === unknown.tokenId)
+    : false;
+  const remaining = String(coupons.length);
+
+  const message = (result: Outcome) => (
+    <p
+      className={result.tone === "ok" ? "pws-status-ok" : "pws-status-warn"}
+      role={result.tone === "ok" ? "status" : "alert"}
+      style={{ marginTop: 12 }}
+    >
+      {t(result.key, { count: remaining })}
+    </p>
+  );
+
+  return (
+    <dialog
+      ref={dialogRef}
+      className="modal-overlay"
+      aria-labelledby="grok-coupon-title"
+      onCancel={handleCancel}
+    >
+      <button type="button" className="modal-backdrop-dismiss" aria-label={t("common.close")} tabIndex={-1} onClick={onClose} />
+      <div className="modal-card" onClick={event => event.stopPropagation()} role="document">
+        {unknown ? (
+          <>
+            <div style={{ textAlign: "center", padding: "12px 0" }}>
+              <div className="confirm-icon"><IconAlert width={22} /></div>
+              <h3 id="grok-coupon-title">{t("grokCoupon.title")}</h3>
+              <p className="pws-status-warn" role="alert">{t("grokCoupon.unknownOutcome")}</p>
+              {!checking && (
+                <p className="faint text-label">
+                  {unresolvedToken ? t("grokCoupon.unresolved") : t("grokCoupon.consumedElsewhere")}
+                </p>
+              )}
+            </div>
+            <div className="modal-actions">
+              <button type="button" className="btn btn-ghost" onClick={onClose}>{t("common.close")}</button>
+              <button type="button" className="btn btn-primary" onClick={() => { void recheck(); }} disabled={checking}>
+                {checking ? t("grokCoupon.checking") : t("grokCoupon.checkResult")}
+              </button>
+            </div>
+          </>
+        ) : !confirming ? (
+          <>
+            <h3 id="grok-coupon-title"><IconTicket width={16} /> {t("grokCoupon.title")}</h3>
+            <div className="card-sub">{accountLabel}</div>
+            <div style={{ margin: "16px 0" }}>
+              {entry === undefined || entry.status === "loading" ? (
+                <p className="faint text-label">{t("common.loading")}</p>
+              ) : entry.status === "error" ? (
+                <>
+                  <p className="faint" role="alert">
+                    {t(entry.reason === "auth" ? "grokCoupon.loadFailedAuth" : "grokCoupon.loadFailed")}
+                  </p>
+                  <button type="button" className="btn btn-ghost" style={{ marginTop: 12 }}
+                    onClick={() => { void controller.refresh(accountId); }}>
+                    {t("grokCoupon.retry")}
+                  </button>
+                </>
+              ) : coupons.length > 0 ? (
+                <>
+                  <p style={{ marginBottom: 12 }}>{t("grokCoupon.available", { count: remaining })}</p>
+                  <div className="credit-list">
+                    {coupons.map((coupon, index) => (
+                      <GrokCouponItem key={coupon.tokenId} coupon={coupon} index={index} isNext={index === 0} locale={locale} t={t} />
+                    ))}
+                  </div>
+                  <button type="button" className="btn btn-primary" style={{ marginTop: 12, width: "100%" }}
+                    onClick={startConfirm} disabled={redeeming}>
+                    {t("grokCoupon.useOne")}
+                  </button>
+                  <p className="card-sub text-caption" style={{ marginTop: 8, textAlign: "center" }}>{t("grokCoupon.fifoNote")}</p>
+                </>
+              ) : (
+                <>
+                  <p className="faint">{t("grokCoupon.none")}</p>
+                  <p className="modal-desc">{t("grokCoupon.desc")}</p>
+                </>
+              )}
+              {outcome && message(outcome)}
+            </div>
+          </>
+        ) : (
+          <>
+            <div style={{ textAlign: "center", padding: "12px 0" }}>
+              <div className="confirm-icon"><IconAlert width={22} /></div>
+              <h3 id="grok-coupon-title">{t("grokCoupon.confirmTitle")}</h3>
+              <p className="modal-desc">{t("grokCoupon.confirmDesc", { count: remaining })}</p>
+              {next?.validityEnd && (
+                <p className="faint text-label">
+                  {t("grokCoupon.confirmWhich", { date: formatCreditDate(next.validityEnd, locale) })}
+                </p>
+              )}
+              <p className="faint text-label">{t("grokCoupon.irreversible")}</p>
+              {outcome && message(outcome)}
+            </div>
+            <div className="modal-actions">
+              <button type="button" className="btn btn-ghost" onClick={() => setConfirming(false)} disabled={redeeming}>
+                {t("common.cancel")}
+              </button>
+              <button ref={redeemRef} type="button" className="btn btn-primary" onClick={() => { void redeem(); }} disabled={redeeming}>
+                {redeeming ? t("grokCoupon.redeeming") : t("grokCoupon.redeem")}
+              </button>
+            </div>
+          </>
+        )}
+      </div>
+    </dialog>
+  );
+}
diff --git a/gui/src/components/provider-workspace/ProviderAuthPanel.tsx b/gui/src/components/provider-workspace/ProviderAuthPanel.tsx
index fecf40ac2b..6ad65475f4 100644
--- a/gui/src/components/provider-workspace/ProviderAuthPanel.tsx
+++ b/gui/src/components/provider-workspace/ProviderAuthPanel.tsx
@@ -3,7 +3,7 @@
  * embedding for the workspace Settings tab (WP091). Consumes WP040+WP060
  * handlers via props-down; no internal auth machinery.
  */
-import { useEffect, useRef, useState } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
 import { useT } from "../../i18n/shared";
 import { IconLock, IconRefresh, IconTrash } from "../../icons";
 import type { WorkspaceItem } from "../../provider-workspace/catalog";
@@ -21,7 +21,9 @@ import AnthropicAccountPoolSettings from "./AnthropicAccountPoolSettings";
 import { LoginHint as LoginHintView } from "../login-url-block";
 import { OpenBrowserPrefToggle } from "../open-browser-pref-toggle";
 import ProviderAccountQuota from "./ProviderAccountQuota";
+import { GrokCouponBadge, GrokResetCouponModal } from "./GrokResetCoupons";
 import type { CodexAccountPoolController } from "../../hooks/useCodexAccountPool";
+import { useGrokResetCoupons } from "../../hooks/useGrokResetCoupons";
 import { Switch } from "../../ui";
 import type {
   AccountLoadState,
@@ -37,6 +39,15 @@ const COCKPIT_IMPORT_MAX_BYTES = 256 * 1024;
 const EMPTY_OAUTH_ACCOUNTS: OAuthAccountRow[] = [];
 const EMPTY_API_KEYS: ApiKeyRow[] = [];
 
+/**
+ * One predicate for "this row cannot spend a coupon right now". The read set and
+ * the badge must agree: a row fetched here and hidden there is a billing RPC
+ * spent on a 401.
+ */
+function accountShowsReauth(account: OAuthAccountRow): boolean {
+  return Boolean(account.needsReauth) || oauthHealthShowsReauth(account.health?.status);
+}
+
 function XaiChatOptInControl({
   initialState,
   onUpdateProvider,
@@ -207,6 +218,22 @@ export default function ProviderAuthPanel({
   }, [connectionIdentity]);
 
   const onRefreshQuota = authHandlers?.onRefreshQuota;
+  const surface = providerAuthSurface({ ...item, hasApiKey: item.hasApiKey || keys.length > 0 });
+  const isOauth = surface === "oauth-accounts";
+  const isKeyAuth = surface === "api-keys";
+  // Grok reset coupons live behind a billing RPC rather than the quota payload,
+  // so the xAI rows read them once per roster instead of riding the quota probe.
+  // The gate names the OAuth surface here rather than relying on the roster
+  // loader three files away to leave `accounts` empty for key-auth xAI.
+  const grokCouponsEnabled = isOauth && item.name === "xai" && accounts.length > 0;
+  const grokAccountIds = useMemo(
+    () => (grokCouponsEnabled
+      ? accounts.filter(account => !accountShowsReauth(account)).map(account => account.id)
+      : []),
+    [grokCouponsEnabled, accounts],
+  );
+  const grokCoupons = useGrokResetCoupons({ apiBase, accountIds: grokAccountIds, enabled: grokCouponsEnabled });
+  const [couponAccount, setCouponAccount] = useState<OAuthAccountRow | null>(null);
   const refreshQuota = async () => {
     if (!onRefreshQuota || refreshingQuota) return;
     const generation = ++quotaRefreshGeneration.current;
@@ -222,10 +249,6 @@ export default function ProviderAuthPanel({
     }
   };
 
-  const surface = providerAuthSurface({ ...item, hasApiKey: item.hasApiKey || keys.length > 0 });
-  const isOauth = surface === "oauth-accounts";
-  const isKeyAuth = surface === "api-keys";
-
   if (surface === "codex-accounts") {
     return (
       <section className="pwi-section pwi-auth-section" aria-label={t("pws.availableAccounts")}>
@@ -495,7 +518,7 @@ export default function ProviderAuthPanel({
                   const label = oauthAccountDisplayLabel(accounts, account, t);
                   const switching = switchingAccountId === account.id;
                   const healthStatus = account.health?.status;
-                  const showReauth = Boolean(account.needsReauth) || oauthHealthShowsReauth(healthStatus);
+                  const showReauth = accountShowsReauth(account);
                   const inCooldown = oauthHealthIsCooldown(healthStatus);
                   const maskedId = displayAccountId(account.id);
                   const healthLabel = formatOAuthHealthLabel(t, account.health);
@@ -536,6 +559,13 @@ export default function ProviderAuthPanel({
                         {t("pws.reauthenticate")}
                       </button>
                     )}
+                    {grokCouponsEnabled && !showReauth && (
+                      <GrokCouponBadge
+                        entry={grokCoupons.entries[account.id]}
+                        t={t}
+                        onClick={() => setCouponAccount(account)}
+                      />
+                    )}
                     <button type="button" className="btn btn-ghost btn-sm"
                       onClick={() => void authHandlers.onEditAlias(item.name, "oauth", account.id, account.alias)}>
                       {t("prov.editAlias")}
@@ -557,6 +587,15 @@ export default function ProviderAuthPanel({
                 })}
               </ul>
             )}
+            {couponAccount && (
+              <GrokResetCouponModal
+                accountId={couponAccount.id}
+                accountLabel={oauthAccountDisplayLabel(accounts, couponAccount, t)}
+                entry={grokCoupons.entries[couponAccount.id]}
+                controller={grokCoupons}
+                onClose={() => setCouponAccount(null)}
+              />
+            )}
             {accountLoadState === "ready" && loggedIn && accounts.length === 0 && (
               <div className="pwi-auth-state pwi-auth-state--empty">{t("pws.noAccounts")}</div>
             )}
diff --git a/gui/src/hooks/useGrokResetCoupons.ts b/gui/src/hooks/useGrokResetCoupons.ts
new file mode 100644
index 0000000000..3296f7cacb
--- /dev/null
+++ b/gui/src/hooks/useGrokResetCoupons.ts
@@ -0,0 +1,209 @@
+/**
+ * useGrokResetCoupons — reads and redeems Grok billing reset coupons for xAI
+ * OAuth accounts through the management API (`GET /api/grok/reset-coupons`,
+ * `POST /api/grok/reset-coupons/consume`).
+ *
+ * Codex reset credits ride the quota payload, so its badge costs nothing. Grok
+ * coupons come from a separate billing RPC with no server cache, so this hook
+ * owns the reads and keeps at most three in flight.
+ *
+ * Two things here are load-bearing rather than stylistic:
+ *
+ * - The roster epoch and the per-account request token are separate. A single
+ *   counter would let one row's retry discard every sibling read still in
+ *   flight, stranding those badges on the placeholder with no way back.
+ * - Redemption reports the settled `code`, not HTTP 200. The route replays a
+ *   settled *failure* as 200 with `replayed: true` and the original code, so a
+ *   client that reads only `replayed` tells the user a failed redemption
+ *   succeeded.
+ */
+import { useCallback, useEffect, useRef, useState } from "react";
+import { createBoundedFetch } from "../bounded-fetch";
+
+export interface GrokResetCoupon {
+  tokenId: string;
+  /** ISO timestamp, or "" when upstream omitted the bound. */
+  validityStart: string;
+  validityEnd: string;
+}
+
+export type GrokCouponEntry =
+  | { status: "loading" }
+  | { status: "ready"; coupons: GrokResetCoupon[] }
+  | { status: "error"; reason: "auth" | "upstream" };
+
+export interface GrokRedeemOutcome {
+  ok: boolean;
+  /** Settled ledger code, or `aborted`/`network` when the request never settled. */
+  code: string;
+  replayed: boolean;
+}
+
+export interface GrokResetCouponController {
+  /** Absent id means "not read yet"; consumers render that as loading. */
+  entries: Record<string, GrokCouponEntry>;
+  refresh: (accountId: string) => Promise<void>;
+  redeem: (accountId: string, request: { tokenId: string; operationId: string }) => Promise<GrokRedeemOutcome>;
+}
+
+const READ_TIMEOUT_MS = 20_000;
+const REDEEM_TIMEOUT_MS = 30_000;
+const MAX_READS_IN_FLIGHT = 3;
+
+function parseCoupons(value: unknown): GrokResetCoupon[] | null {
+  if (!value || typeof value !== "object") return null;
+  const tokens = (value as { tokens?: unknown }).tokens;
+  if (!Array.isArray(tokens)) return null;
+  const coupons: GrokResetCoupon[] = [];
+  for (const token of tokens) {
+    if (!token || typeof token !== "object") return null;
+    const { tokenId, validityStart, validityEnd } = token as Record<string, unknown>;
+    // One malformed entry rejects the list: a partially parsed set of coupons is
+    // worse than an error badge, because the dialog would spend from it.
+    if (typeof tokenId !== "string" || tokenId === "") return null;
+    coupons.push({
+      tokenId,
+      validityStart: typeof validityStart === "string" ? validityStart : "",
+      validityEnd: typeof validityEnd === "string" ? validityEnd : "",
+    });
+  }
+  return coupons;
+}
+
+function errorCode(value: unknown): string {
+  if (value && typeof value === "object") {
+    const error = (value as { error?: unknown }).error;
+    if (error && typeof error === "object") {
+      const code = (error as { code?: unknown }).code;
+      if (typeof code === "string" && code !== "") return code;
+    }
+  }
+  return "redeem_failed";
+}
+
+function settledCode(value: unknown): string {
+  if (value && typeof value === "object") {
+    const code = (value as { code?: unknown }).code;
+    if (typeof code === "string" && code !== "") return code;
+  }
+  return "redeemed";
+}
+
+function expiryRank(coupon: GrokResetCoupon): number {
+  if (!coupon.validityEnd) return Number.POSITIVE_INFINITY;
+  const parsed = Date.parse(coupon.validityEnd);
+  // An unparsable bound sorts last rather than collapsing the comparator, so a
+  // malformed timestamp cannot present itself as the nearest expiry.
+  return Number.isNaN(parsed) ? Number.POSITIVE_INFINITY : parsed;
+}
+
+function byExpiry(coupons: GrokResetCoupon[]): GrokResetCoupon[] {
+  return coupons.toSorted((a, b) => expiryRank(a) - expiryRank(b));
+}
+
+function wasAborted(error: unknown, signal: AbortSignal): boolean {
+  if (signal.aborted) return true;
+  return Boolean(error && typeof error === "object" && (error as { name?: unknown }).name === "AbortError");
+}
+
+export function useGrokResetCoupons({ apiBase, accountIds, enabled }: {
+  apiBase: string;
+  accountIds: string[];
+  enabled: boolean;
+}): GrokResetCouponController {
+  const [entries, setEntries] = useState<Record<string, GrokCouponEntry>>({});
+  /** Roster epoch: bumped only by the effect and its cleanup. */
+  const epoch = useRef(0);
+  /** Per-account request token, so one row's retry cannot cancel another row's read. */
+  const tokens = useRef(new Map<string, number>());
+  const gate = useRef<{ active: number; waiting: Array<() => void> }>({ active: 0, waiting: [] });
+  const identity = accountIds.join("\u0000");
+
+  // No synchronous setState here: the effect below calls this directly, and a
+  // state write before the first await is what react-compiler's EffectSetState
+  // rule forbids. `refresh` owns the visible loading state instead.
+  const read = useCallback(async (accountId: string, rosterEpoch: number) => {
+    const token = (tokens.current.get(accountId) ?? 0) + 1;
+    tokens.current.set(accountId, token);
+
+    const queue = gate.current;
+    if (queue.active >= MAX_READS_IN_FLIGHT) {
+      await new Promise<void>(resolve => queue.waiting.push(resolve));
+    }
+    queue.active += 1;
+
+    const current = () => epoch.current === rosterEpoch && tokens.current.get(accountId) === token;
+    const bounded = createBoundedFetch(READ_TIMEOUT_MS);
+    try {
+      const response = await fetch(
+        `${apiBase}/api/grok/reset-coupons?accountId=${encodeURIComponent(accountId)}`,
+        { signal: bounded.signal },
+      );
+      const coupons = response.ok ? parseCoupons(await response.json().catch(() => null)) : null;
+      if (!current()) return;
+      setEntries(existing => ({
+        ...existing,
+        [accountId]: coupons
+          ? { status: "ready", coupons: byExpiry(coupons) }
+          : { status: "error", reason: response.status === 401 ? "auth" : "upstream" },
+      }));
+    } catch {
+      if (!current()) return;
+      setEntries(existing => ({ ...existing, [accountId]: { status: "error", reason: "upstream" } }));
+    } finally {
+      bounded.clear();
+      queue.active -= 1;
+      queue.waiting.shift()?.();
+    }
+  }, [apiBase]);
+
+  useEffect(() => {
+    if (!enabled || identity === "") return;
+    const rosterEpoch = ++epoch.current;
+    // Deferred to a microtask, the same shape the account-pool hook uses: the
+    // reads write state, and starting them inside the effect body is what the
+    // react-compiler lint refuses.
+    void Promise.resolve().then(() => {
+      for (const accountId of identity.split("\u0000")) void read(accountId, rosterEpoch);
+    });
+    // A later roster or unmount retires in-flight reads instead of writing stale
+    // coupon counts onto whatever account now occupies that row.
+    return () => { epoch.current += 1; };
+  }, [enabled, identity, read]);
+
+  const refresh = useCallback(async (accountId: string) => {
+    setEntries(current => ({ ...current, [accountId]: { status: "loading" } }));
+    await read(accountId, epoch.current);
+  }, [read]);
+
+  const redeem = useCallback(async (
+    accountId: string,
+    request: { tokenId: string; operationId: string },
+  ): Promise<GrokRedeemOutcome> => {
+    const bounded = createBoundedFetch(REDEEM_TIMEOUT_MS);
+    try {
+      const response = await fetch(`${apiBase}/api/grok/reset-coupons/consume`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ accountId, tokenId: request.tokenId, operationId: request.operationId }),
+        signal: bounded.signal,
+      });
+      if (!response.ok) {
+        return { ok: false, code: errorCode(await response.json().catch(() => null)), replayed: false };
+      }
+      const data = await response.json().catch(() => null) as unknown;
+      const replayed = Boolean(data && typeof data === "object" && (data as { replayed?: unknown }).replayed === true);
+      const code = settledCode(data);
+      await read(accountId, epoch.current);
+      return { ok: code === "redeemed", code, replayed };
+    } catch (error) {
+      // An aborted redemption is an unknown outcome, not a failure: the route may
+      // still be executing it. The caller must stop posting, not retry.
+      return { ok: false, code: wasAborted(error, bounded.signal) ? "aborted" : "network", replayed: false };
+    } finally {
+      bounded.clear();
+    }
+  }, [apiBase, read]);
+
+  return { entries, refresh, redeem };
+}
diff --git a/gui/src/i18n/de.ts b/gui/src/i18n/de.ts
index 68363152b5..db6b8c889f 100644
--- a/gui/src/i18n/de.ts
+++ b/gui/src/i18n/de.ts
@@ -1097,13 +1097,15 @@ export const de: Record<TKey, string> = {
   "integrations.tab.hermes": "Hermes",
   "integrations.tab.openclaw": "OpenClaw",
   "integrations.tab.kimi": "Kimi Code",
-  "integrations.tab.gajae": "Gajae Code",
+  "integrations.tab.gajae": "gjc",
   "integrations.tab.dsh": "DSH",
   "integrations.tab.mcode": "MiniMax Code",
   "integrations.tab.zcode": "ZCode",
   "integrations.tab.prime": "Prime Agent",
   "integrations.tab.aside": "Aside",
   "integrations.tab.raycast": "Raycast",
+  "integrations.tab.omo": "omo",
+  "integrations.tab.cline": "Cline CLI",
   "integrations.aside.profilesTitle": "Aside-Profile",
   "integrations.aside.profilesHint": "Wähle, welche Profile die ausgewählten Modelle erhalten. Das aktive Aside-Profil bleibt unverändert.",
   "integrations.aside.all": "Alle Profile synchronisieren",
@@ -1264,6 +1266,8 @@ export const de: Record<TKey, string> = {
   "integrations.semantics.prime": "Verwaltet nur providers.opencodex in der models.json von Prime Agent — ~/.prime/agent, sofern PRIME_AGENT_CODING_AGENT_DIR sie nicht umleitet. Andere Provider und Modell-Overrides bleiben unverändert. Gilt für neue Sitzungen.",
   "integrations.semantics.aside": "Verwaltet nur providers.opencodex in der ~/.aside/u/<id>/models.json dieses Profils. Andere Provider bleiben unverändert. Beende Aside nach dem Anwenden vollständig und öffne es erneut.",
   "integrations.semantics.raycast": "Fügt einen OpenCodex-Provider-Eintrag in die providers.yaml von Raycast ein, damit jedes geroutete Modell in der Modellauswahl von Raycast AI erscheint. Raycast Pro erforderlich.",
+  "integrations.semantics.omo": "Verwaltet ausschließlich providers.opencodex in der models.json von omo — ~/.omo/agent, sofern nicht OMO_CODING_AGENT_DIR, SENPI_CODING_AGENT_DIR oder PI_CODING_AGENT_DIR sie umleitet. Ihre übrigen Provider bleiben unverändert. Gilt ab neuen Sitzungen.",
+  "integrations.semantics.cline": "Verwaltet OpenCodex in providers.json und models.json der Cline CLI. Beenden Sie Cline vor Änderungen oder Synchronisierung und starten Sie es danach neu. Rückgängig stellt beide Originaldateien wieder her. Ihr Standardanbieter bleibt unverändert; wählen Sie OpenCodex in Cline.",
   "integrations.raycast.proRequired": "Custom Providers ist eine Funktion von Raycast Pro. Die Datei wird geschrieben, aber Raycast ignoriert sie, bis ein Pro-Abonnement aktiv ist.",
   "integrations.raycast.planUnknown": "Es konnte nicht festgestellt werden, ob Raycast Pro aktiv ist; Custom Providers erfordert Raycast Pro.",
   "integrations.raycast.revealConfig": "Öffnen Sie Raycast → Einstellungen → AI und klicken Sie einmal auf „Reveal Providers Config“, damit der Providers-Ordner existiert.",
@@ -1502,6 +1506,45 @@ export const de: Record<TKey, string> = {
   "codexAuth.creditNextBadge": "NÄCHSTE",
   "codexAuth.creditGranted": "Erhalten {date}",
   "codexAuth.creditExpires": "Läuft ab {date} ({days} Tage übrig)",
+
+  // grok reset coupons (xAI account rows)
+  "grokCoupon.badgeAria": "{count} Grok-Reset-Coupon(s)",
+  "grokCoupon.badgeErrorAria": "Grok-Reset-Coupons konnten nicht gelesen werden",
+  "grokCoupon.title": "Grok-Reset-Coupons",
+  "grokCoupon.available": "Dieses Konto hat {count} Reset-Coupon(s).",
+  "grokCoupon.desc": "Ein Coupon setzt das Grok-Nutzungsfenster dieses Kontos sofort zurück.",
+  "grokCoupon.none": "Dieses Konto hat keine Reset-Coupons.",
+  "grokCoupon.loadFailed": "Reset-Coupons für dieses Konto konnten nicht gelesen werden.",
+  "grokCoupon.loadFailedAuth": "Melde dich erneut bei diesem xAI-Konto an, um seine Coupons zu lesen.",
+  "grokCoupon.retry": "Erneut versuchen",
+  "grokCoupon.couponLabel": "Coupon #{n}",
+  "grokCoupon.couponNext": "Als nächstes",
+  "grokCoupon.couponNextBadge": "NÄCHSTE",
+  "grokCoupon.validFrom": "Gültig ab {date}",
+  "grokCoupon.expires": "Läuft ab {date} ({days} Tage übrig)",
+  "grokCoupon.useOne": "1 Coupon nutzen",
+  "grokCoupon.fifoNote": "Der Coupon, der als Nächstes abläuft, wird zuerst verwendet.",
+  "grokCoupon.confirmTitle": "Reset-Coupon nutzen?",
+  "grokCoupon.confirmDesc": "Dies setzt das Grok-Nutzungsfenster dieses Kontos jetzt zurück. Du hast {count} Coupon(s).",
+  "grokCoupon.confirmWhich": "Der Coupon, der {date} abläuft, wird verwendet.",
+  "grokCoupon.irreversible": "Diese Aktion kann nicht rückgängig gemacht werden.",
+  "grokCoupon.redeem": "Coupon nutzen",
+  "grokCoupon.redeeming": "Wird eingelöst…",
+  "grokCoupon.redeemSuccess": "Coupon eingelöst. {count} Coupon(s) übrig.",
+  "grokCoupon.redeemReplayed": "Diese Einlösung wurde bereits früher abgeschlossen. Es wurde nichts erneut verbraucht.",
+  "grokCoupon.redeemFailed": "Einlösung fehlgeschlagen. Prüfe die Coupon-Liste, bevor du es erneut versuchst.",
+  "grokCoupon.authFailed": "Melde dich erneut bei diesem xAI-Konto an, um seine Coupons zu nutzen.",
+  "grokCoupon.noAccount": "Für diese Einlösung ist kein xAI-Konto verfügbar.",
+  "grokCoupon.noneAvailable": "Keine Reset-Coupons zum Einlösen verfügbar.",
+  "grokCoupon.identityMismatch": "Diese Einlösung gehört zu einem anderen Konto. Schließe diesen Dialog und starte erneut.",
+  "grokCoupon.networkError": "Der Proxy war nicht erreichbar.",
+  "grokCoupon.capacity": "Das Einlösungsjournal ist gerade voll. Versuche es in einem Moment erneut.",
+  "grokCoupon.noOperationId": "Dieser Browser kann keine Einlösungs-ID erzeugen, daher ist das Einlösen hier deaktiviert.",
+  "grokCoupon.unknownOutcome": "Die Einlösung hat nicht rechtzeitig geantwortet, daher ist ihr Ergebnis unbekannt. Lies das Konto erneut, um zu sehen, ob der Coupon verbraucht wurde.",
+  "grokCoupon.checkResult": "Konto erneut lesen",
+  "grokCoupon.checking": "Wird erneut gelesen…",
+  "grokCoupon.consumedElsewhere": "Der Coupon ist in diesem Konto nicht mehr vorhanden, die Einlösung ist also durchgegangen.",
+  "grokCoupon.unresolved": "Der Coupon ist noch aufgeführt. Die Einlösung läuft möglicherweise noch upstream — lies in einer Minute erneut, bevor du einen weiteren Coupon einlöst.",
   "api.title": "API-Zugriff",
   "api.subtitle": "Mit generierten API-Schlüsseln greifen externe Apps auf den opencodex-Proxy zu. Die Authentifizierung läuft über den {authHeader}-Header; welche Header ein Endpunkt akzeptiert, steht in der Tabelle unten.",
   "api.baseUrl": "Basis-URL",
@@ -1589,13 +1632,17 @@ export const de: Record<TKey, string> = {
   "api.clientConfig.clientHermes": "Hermes",
   "api.clientConfig.clientOpenclaw": "OpenClaw",
   "api.clientConfig.clientKimi": "Kimi Code",
-  "api.clientConfig.clientGajae": "Gajae Code",
+  "api.clientConfig.clientGajae": "gjc",
   "api.clientConfig.clientDsh": "DeepSeek Harness (DSH)",
   "api.clientConfig.clientMcode": "MiniMax Code",
   "api.clientConfig.clientZcode": "ZCode",
   "api.clientConfig.clientPrime": "Prime Agent",
   "api.clientConfig.clientAside": "Aside",
   "api.clientConfig.clientRaycast": "Raycast",
+  "api.clientConfig.clientOmo": "omo",
+  "api.clientConfig.clientCline": "Cline CLI",
+  "api.clientConfig.clineBundle": "Dies ist ein Paket für zwei Dateien, keine Cline-Einstellungsdatei. Fügen Sie settings in providers.json und catalog in die benachbarte models.json ein. Der Integrationsschalter erstellt vor dem Schreiben ein Backup.",
+  "api.clientConfig.clineDownloaded": "{filename} heruntergeladen. Noch nichts geändert; settings und catalog gehören in zwei separate Cline-Dateien.",
   "api.clientConfig.copy": "Konfiguration kopieren",
   "api.clientConfig.download": "Herunterladen",
   "api.clientConfig.loading": "Client-Konfiguration wird erstellt…",
@@ -1896,7 +1943,10 @@ export const de: Record<TKey, string> = {
   "modal.freeTierDefault": "Kein API-Schlüssel nötig. Funktioniert sofort.",
   "modal.tab.accounts": "Konten",
   "modal.tab.free": "Kostenlos",
+  "modal.tab.local": "Lokal",
   "modal.tab.paid": "Bezahlt",
+  "modal.noteMore": "Vollständige Beschreibung anzeigen",
+  "modal.searchResults": "{count} Ergebnisse in {tiers}",
   "modal.accountsHint": "Hier ChatGPT/Codex, OAuth-Provider und API-Key-Konten anmelden. OpenAI ist eingebaut — anmelden statt erneut hinzufügen.",
   "modal.accountsCodexAuthLink": "Codex Auth",
   "modal.notListed": "Provider nicht dabei? Eigenen hinzufügen",
diff --git a/gui/src/i18n/en.ts b/gui/src/i18n/en.ts
index 89fc5ec0d7..74e4ded4d1 100644
--- a/gui/src/i18n/en.ts
+++ b/gui/src/i18n/en.ts
@@ -1155,7 +1155,10 @@ export const en = {
   "modal.freeTierDefault": "No API key required. Works out of the box.",
   "modal.tab.accounts": "Accounts",
   "modal.tab.free": "Free",
+  "modal.tab.local": "Local",
   "modal.tab.paid": "Paid",
+  "modal.noteMore": "Show full description",
+  "modal.searchResults": "{count} results across {tiers}",
   "modal.accountsHint": "Sign in to ChatGPT/Codex, OAuth providers, and API-key accounts here. OpenAI is built in — log in rather than adding it again.",
   "modal.accountsCodexAuthLink": "Codex Auth",
   "modal.notListed": "Provider not listed? Add a custom one",
@@ -1630,13 +1633,15 @@ export const en = {
   "integrations.tab.hermes": "Hermes",
   "integrations.tab.openclaw": "OpenClaw",
   "integrations.tab.kimi": "Kimi Code",
-  "integrations.tab.gajae": "Gajae Code",
+  "integrations.tab.gajae": "gjc",
   "integrations.tab.dsh": "DSH",
   "integrations.tab.mcode": "MiniMax Code",
   "integrations.tab.zcode": "ZCode",
   "integrations.tab.prime": "Prime Agent",
   "integrations.tab.aside": "Aside",
   "integrations.tab.raycast": "Raycast",
+  "integrations.tab.omo": "omo",
+  "integrations.tab.cline": "Cline CLI",
   "integrations.aside.profilesTitle": "Aside profiles",
   "integrations.aside.profilesHint": "Choose which profiles receive the selected models. Aside’s active profile stays unchanged.",
   "integrations.aside.all": "Sync all profiles",
@@ -1837,6 +1842,8 @@ export const en = {
   "integrations.semantics.prime": "Manages only providers.opencodex in Prime Agent's models.json — ~/.prime/agent unless PRIME_AGENT_CODING_AGENT_DIR redirects it. Your other providers and model overrides stay unchanged. Applies to new sessions.",
   "integrations.semantics.aside": "Manages only providers.opencodex in this profile’s ~/.aside/u/<id>/models.json. Your other providers stay unchanged. Fully quit and reopen Aside after applying.",
   "integrations.semantics.raycast": "Adds an OpenCodex provider entry to Raycast's providers.yaml so every routed model appears in the Raycast AI model picker. Raycast Pro required.",
+  "integrations.semantics.omo": "Manages only providers.opencodex in omo's models.json — ~/.omo/agent unless OMO_CODING_AGENT_DIR, SENPI_CODING_AGENT_DIR or PI_CODING_AGENT_DIR redirects it. Your other providers stay unchanged. Applies to new sessions.",
+  "integrations.semantics.cline": "Manages OpenCodex in Cline CLI providers.json and models.json. Stop Cline before changing or syncing these files, then restart. Undo restores both originals. Your default provider stays unchanged; select OpenCodex in Cline.",
   "integrations.raycast.proRequired": "Custom Providers is a Raycast Pro feature. The file will be written, but Raycast ignores it until a Pro subscription is active.",
   "integrations.raycast.planUnknown": "Could not determine whether Raycast Pro is active; Custom Providers requires Raycast Pro.",
   "integrations.raycast.revealConfig": "Open Raycast → Settings → AI and click Reveal Providers Config once so the providers folder exists.",
@@ -2085,6 +2092,45 @@ export const en = {
   "codexAuth.creditGranted": "Granted {date}",
   "codexAuth.creditExpires": "Expires {date} ({days}d left)",
 
+  // grok reset coupons (xAI account rows)
+  "grokCoupon.badgeAria": "{count} Grok reset coupon(s)",
+  "grokCoupon.badgeErrorAria": "Grok reset coupons could not be read",
+  "grokCoupon.title": "Grok reset coupons",
+  "grokCoupon.available": "This account has {count} reset coupon(s).",
+  "grokCoupon.desc": "A coupon resets this account's Grok usage window immediately.",
+  "grokCoupon.none": "This account has no reset coupons.",
+  "grokCoupon.loadFailed": "Could not read reset coupons for this account.",
+  "grokCoupon.loadFailedAuth": "Sign in to this xAI account again to read its coupons.",
+  "grokCoupon.retry": "Try again",
+  "grokCoupon.couponLabel": "Coupon #{n}",
+  "grokCoupon.couponNext": "Next to use",
+  "grokCoupon.couponNextBadge": "NEXT",
+  "grokCoupon.validFrom": "Valid from {date}",
+  "grokCoupon.expires": "Expires {date} ({days}d left)",
+  "grokCoupon.useOne": "Use 1 coupon",
+  "grokCoupon.fifoNote": "The coupon closest to expiry is used first.",
+  "grokCoupon.confirmTitle": "Use reset coupon?",
+  "grokCoupon.confirmDesc": "This resets this account's Grok usage window now. You have {count} coupon(s).",
+  "grokCoupon.confirmWhich": "The coupon expiring {date} will be used.",
+  "grokCoupon.irreversible": "This action cannot be undone.",
+  "grokCoupon.redeem": "Use coupon",
+  "grokCoupon.redeeming": "Redeeming…",
+  "grokCoupon.redeemSuccess": "Coupon redeemed. {count} coupon(s) left.",
+  "grokCoupon.redeemReplayed": "This redemption already settled earlier. Nothing was consumed again.",
+  "grokCoupon.redeemFailed": "Redemption failed. Check the coupon list before trying again.",
+  "grokCoupon.authFailed": "Sign in to this xAI account again to use its coupons.",
+  "grokCoupon.noAccount": "No xAI account is available for this redemption.",
+  "grokCoupon.noneAvailable": "No reset coupons are available to redeem.",
+  "grokCoupon.identityMismatch": "That redemption belongs to another account. Close this dialog and start again.",
+  "grokCoupon.networkError": "The proxy could not be reached.",
+  "grokCoupon.capacity": "The redemption journal is full right now. Try again in a moment.",
+  "grokCoupon.noOperationId": "This browser cannot generate a redemption ID, so redeeming is disabled here.",
+  "grokCoupon.unknownOutcome": "The redemption did not answer in time, so its outcome is unknown. Re-read the account to see whether the coupon was spent.",
+  "grokCoupon.checkResult": "Re-read account",
+  "grokCoupon.checking": "Re-reading…",
+  "grokCoupon.consumedElsewhere": "The coupon is gone from this account, so the redemption went through.",
+  "grokCoupon.unresolved": "The coupon is still listed. The redemption may still be running upstream — re-read in a minute before spending another coupon.",
+
   // api access page
   "api.title": "API Access",
   "api.subtitle": "Use generated API keys to access the opencodex proxy from external apps. Keys authenticate via the {authHeader} header; see the table below for what each endpoint accepts.",
@@ -2173,13 +2219,17 @@ export const en = {
   "api.clientConfig.clientHermes": "Hermes",
   "api.clientConfig.clientOpenclaw": "OpenClaw",
   "api.clientConfig.clientKimi": "Kimi Code",
-  "api.clientConfig.clientGajae": "Gajae Code",
+  "api.clientConfig.clientGajae": "gjc",
   "api.clientConfig.clientDsh": "DeepSeek Harness (DSH)",
   "api.clientConfig.clientMcode": "MiniMax Code",
   "api.clientConfig.clientZcode": "ZCode",
   "api.clientConfig.clientPrime": "Prime Agent",
   "api.clientConfig.clientAside": "Aside",
   "api.clientConfig.clientRaycast": "Raycast",
+  "api.clientConfig.clientOmo": "omo",
+  "api.clientConfig.clientCline": "Cline CLI",
+  "api.clientConfig.clineBundle": "This is a two-file bundle, not a Cline settings file. Merge settings into providers.json and catalog into sibling models.json. Use the integration switch for a backed-up write.",
+  "api.clientConfig.clineDownloaded": "Downloaded {filename}. Nothing changed yet; settings and catalog belong in two separate Cline files.",
   "api.clientConfig.copy": "Copy config",
   "api.clientConfig.download": "Download",
   "api.clientConfig.loading": "Building client config…",
diff --git a/gui/src/i18n/fr.ts b/gui/src/i18n/fr.ts
index 4cf6818072..2bc3d5ab51 100644
--- a/gui/src/i18n/fr.ts
+++ b/gui/src/i18n/fr.ts
@@ -1128,7 +1128,10 @@ export const fr: Record<TKey, string> = {
   "modal.freeTierDefault": "Aucune clé API requise. Fonctionne immédiatement.",
   "modal.tab.accounts": "Comptes",
   "modal.tab.free": "Gratuit",
+  "modal.tab.local": "Local",
   "modal.tab.paid": "Payant",
+  "modal.noteMore": "Afficher la description complète",
+  "modal.searchResults": "{count} résultats dans {tiers}",
   "modal.accountsHint": "Connectez-vous ici à ChatGPT/Codex, aux fournisseurs OAuth et aux comptes avec clé API. OpenAI est intégré : connectez-vous au lieu de l’ajouter de nouveau.",
   "modal.accountsCodexAuthLink": "Codex Auth",
   "modal.notListed": "Fournisseur absent de la liste ? Ajoutez-en un personnalisé",
@@ -1602,13 +1605,15 @@ export const fr: Record<TKey, string> = {
   "integrations.tab.hermes": "Hermes",
   "integrations.tab.openclaw": "OpenClaw",
   "integrations.tab.kimi": "Kimi Code",
-  "integrations.tab.gajae": "Gajae Code",
+  "integrations.tab.gajae": "gjc",
   "integrations.tab.dsh": "DSH",
   "integrations.tab.mcode": "MiniMax Code",
   "integrations.tab.zcode": "ZCode",
   "integrations.tab.prime": "Prime Agent",
   "integrations.tab.aside": "Aside",
   "integrations.tab.raycast": "Raycast",
+  "integrations.tab.omo": "omo",
+  "integrations.tab.cline": "Cline CLI",
   "integrations.aside.profilesTitle": "Profils Aside",
   "integrations.aside.profilesHint": "Choisissez les profils qui recevront les modèles sélectionnés. Le profil actif dans Aside reste inchangé.",
   "integrations.aside.all": "Synchroniser tous les profils",
@@ -1769,6 +1774,8 @@ export const fr: Record<TKey, string> = {
   "integrations.semantics.prime": "Gère uniquement providers.opencodex dans le models.json de Prime Agent — ~/.prime/agent, sauf si PRIME_AGENT_CODING_AGENT_DIR le redirige. Vos autres fournisseurs et surcharges de modèles restent inchangés. S'applique aux nouvelles sessions.",
   "integrations.semantics.aside": "Gère uniquement providers.opencodex dans le fichier ~/.aside/u/<id>/models.json de ce profil. Vos autres fournisseurs restent inchangés. Quittez complètement Aside et relancez-le après application.",
   "integrations.semantics.raycast": "Ajoute une entrée de fournisseur OpenCodex dans le providers.yaml de Raycast afin que chaque modèle routé apparaisse dans le sélecteur de modèles de Raycast AI. Raycast Pro requis.",
+  "integrations.semantics.omo": "Gère uniquement providers.opencodex dans le models.json d'omo — ~/.omo/agent, sauf redirection par OMO_CODING_AGENT_DIR, SENPI_CODING_AGENT_DIR ou PI_CODING_AGENT_DIR. Vos autres fournisseurs restent inchangés. S'applique aux nouvelles sessions.",
+  "integrations.semantics.cline": "Gère OpenCodex dans providers.json et models.json de Cline CLI. Quittez Cline avant toute modification ou synchronisation, puis redémarrez-le. Annuler restaure les deux fichiers originaux. Votre fournisseur par défaut reste inchangé ; sélectionnez OpenCodex dans Cline.",
   "integrations.raycast.proRequired": "Custom Providers est une fonctionnalité Raycast Pro. Le fichier sera écrit, mais Raycast l'ignore tant qu'un abonnement Pro n'est pas actif.",
   "integrations.raycast.planUnknown": "Impossible de déterminer si Raycast Pro est actif ; Custom Providers nécessite Raycast Pro.",
   "integrations.raycast.revealConfig": "Ouvrez Raycast → Réglages → AI et cliquez une fois sur « Reveal Providers Config » pour que le dossier des fournisseurs existe.",
@@ -2005,6 +2012,46 @@ export const fr: Record<TKey, string> = {
   "codexAuth.creditNextBadge": "PROCHAIN",
   "codexAuth.creditGranted": "Accordé le {date}",
   "codexAuth.creditExpires": "Expire le {date} ({days} j restants)",
+
+  // grok reset coupons (xAI account rows)
+  "grokCoupon.badgeAria": "{count} coupon(s) de réinitialisation Grok",
+  "grokCoupon.badgeErrorAria": "Impossible de lire les coupons de réinitialisation Grok",
+  "grokCoupon.title": "Coupons de réinitialisation Grok",
+  "grokCoupon.available": "Ce compte dispose de {count} coupon(s) de réinitialisation.",
+  "grokCoupon.desc": "Un coupon réinitialise immédiatement la fenêtre d’utilisation Grok de ce compte.",
+  "grokCoupon.none": "Ce compte ne dispose d’aucun coupon de réinitialisation.",
+  "grokCoupon.loadFailed": "Impossible de lire les coupons de réinitialisation de ce compte.",
+  "grokCoupon.loadFailedAuth": "Reconnectez-vous à ce compte xAI pour lire ses coupons.",
+  "grokCoupon.retry": "Réessayer",
+  "grokCoupon.couponLabel": "Coupon nº {n}",
+  "grokCoupon.couponNext": "Prochain à utiliser",
+  "grokCoupon.couponNextBadge": "PROCHAIN",
+  "grokCoupon.validFrom": "Valable à partir du {date}",
+  "grokCoupon.expires": "Expire le {date} ({days} j restants)",
+  "grokCoupon.useOne": "Utiliser 1 coupon",
+  "grokCoupon.fifoNote": "Le coupon le plus proche de l’expiration est utilisé en premier.",
+  "grokCoupon.confirmTitle": "Utiliser un coupon de réinitialisation?",
+  "grokCoupon.confirmDesc": "La fenêtre d’utilisation Grok de ce compte sera réinitialisée immédiatement. Vous disposez de {count} coupon(s).",
+  "grokCoupon.confirmWhich": "Le coupon expirant le {date} sera utilisé.",
+  "grokCoupon.irreversible": "Cette action est irréversible.",
+  "grokCoupon.redeem": "Utiliser le coupon",
+  "grokCoupon.redeeming": "Utilisation…",
+  "grokCoupon.redeemSuccess": "Coupon utilisé. {count} coupon(s) restant(s).",
+  "grokCoupon.redeemReplayed": "Cette utilisation a déjà été effectuée. Rien n’a été consommé de nouveau.",
+  "grokCoupon.redeemFailed": "Impossible d’utiliser le coupon. Vérifiez la liste des coupons avant de réessayer.",
+  "grokCoupon.authFailed": "Reconnectez-vous à ce compte xAI pour utiliser ses coupons.",
+  "grokCoupon.noAccount": "Aucun compte xAI n’est disponible pour cette utilisation.",
+  "grokCoupon.noneAvailable": "Aucun coupon de réinitialisation n’est disponible.",
+  "grokCoupon.identityMismatch": "Cette utilisation appartient à un autre compte. Fermez cette boîte de dialogue et recommencez.",
+  "grokCoupon.networkError": "Impossible de joindre le proxy.",
+  "grokCoupon.capacity": "Le journal d’utilisation est saturé pour le moment. Réessayez dans un instant.",
+  "grokCoupon.noOperationId": "Ce navigateur ne peut pas générer d’ID d’utilisation, l’utilisation est donc désactivée ici.",
+  "grokCoupon.unknownOutcome": "L’utilisation n’a pas répondu à temps, son résultat est donc inconnu. Relisez le compte pour voir si le coupon a été dépensé.",
+  "grokCoupon.checkResult": "Relire le compte",
+  "grokCoupon.checking": "Relecture…",
+  "grokCoupon.consumedElsewhere": "Le coupon a disparu de ce compte, l’utilisation a donc abouti.",
+  "grokCoupon.unresolved": "Le coupon figure encore dans la liste. L’utilisation est peut-être encore en cours en amont — relisez dans une minute avant d’utiliser un autre coupon.",
+
   "api.title": "Accès à l’API",
   "api.subtitle": "Utilisez les clés API générées pour accéder au proxy opencodex depuis des applications externes. Les clés s’authentifient au moyen de l’en-tête {authHeader}; consultez le tableau ci-dessous pour connaître les éléments acceptés par chaque point de terminaison.",
   "api.baseUrl": "URL de base",
@@ -2092,13 +2139,17 @@ export const fr: Record<TKey, string> = {
   "api.clientConfig.clientHermes": "Hermes",
   "api.clientConfig.clientOpenclaw": "OpenClaw",
   "api.clientConfig.clientKimi": "Kimi Code",
-  "api.clientConfig.clientGajae": "Gajae Code",
+  "api.clientConfig.clientGajae": "gjc",
   "api.clientConfig.clientDsh": "DeepSeek Harness (DSH)",
   "api.clientConfig.clientMcode": "MiniMax Code",
   "api.clientConfig.clientZcode": "ZCode",
   "api.clientConfig.clientPrime": "Prime Agent",
   "api.clientConfig.clientAside": "Aside",
   "api.clientConfig.clientRaycast": "Raycast",
+  "api.clientConfig.clientOmo": "omo",
+  "api.clientConfig.clientCline": "Cline CLI",
+  "api.clientConfig.clineBundle": "Ce paquet contient deux fichiers, pas un fichier de paramètres Cline. Fusionnez settings dans providers.json et catalog dans models.json du même dossier. Utilisez le commutateur d’intégration pour sauvegarder avant l’écriture.",
+  "api.clientConfig.clineDownloaded": "{filename} téléchargé. Rien n’a changé ; settings et catalog vont dans deux fichiers Cline distincts.",
   "api.clientConfig.copy": "Copier la configuration",
   "api.clientConfig.download": "Télécharger",
   "api.clientConfig.loading": "Génération de la configuration du client…",
diff --git a/gui/src/i18n/ja.ts b/gui/src/i18n/ja.ts
index c77edbe2c7..a787ab735b 100644
--- a/gui/src/i18n/ja.ts
+++ b/gui/src/i18n/ja.ts
@@ -1068,7 +1068,10 @@ export const ja: Record<TKey, string> = {
   "modal.freeTierDefault": "API キー不要です。そのまま利用できます。",
   "modal.tab.accounts": "アカウント",
   "modal.tab.free": "無料",
+  "modal.tab.local": "ローカル",
   "modal.tab.paid": "有料",
+  "modal.noteMore": "説明をすべて表示",
+  "modal.searchResults": "{tiers} で {count} 件",
   "modal.accountsHint": "ChatGPT/Codex、OAuth プロバイダー、API キーアカウントにここからサインインします。OpenAI は組み込み済み — 再度追加せずログインしてください。",
   "modal.accountsCodexAuthLink": "Codex 認証",
   "modal.notListed": "プロバイダーが載っていませんか? カスタムを追加",
@@ -1527,13 +1530,15 @@ export const ja: Record<TKey, string> = {
   "integrations.tab.hermes": "Hermes",
   "integrations.tab.openclaw": "OpenClaw",
   "integrations.tab.kimi": "Kimi Code",
-  "integrations.tab.gajae": "Gajae Code",
+  "integrations.tab.gajae": "gjc",
   "integrations.tab.dsh": "DSH",
   "integrations.tab.mcode": "MiniMax Code",
   "integrations.tab.zcode": "ZCode",
   "integrations.tab.prime": "Prime Agent",
   "integrations.tab.aside": "Aside",
   "integrations.tab.raycast": "Raycast",
+  "integrations.tab.omo": "omo",
+  "integrations.tab.cline": "Cline CLI",
   "integrations.aside.profilesTitle": "Asideのプロファイル",
   "integrations.aside.profilesHint": "選択したモデルを同期するプロファイルを選んでください。Asideで使用中のプロファイルは変わりません。",
   "integrations.aside.all": "すべてのプロファイルを同期",
@@ -1694,6 +1699,8 @@ export const ja: Record<TKey, string> = {
   "integrations.semantics.prime": "Prime Agent の models.json 内の providers.opencodex のみを管理します。場所は ~/.prime/agent ですが、PRIME_AGENT_CODING_AGENT_DIR が設定されている場合はそちらが優先されます。他のプロバイダーとモデルオーバーライドは変更しません。新しいセッションから適用されます。",
   "integrations.semantics.aside": "このプロファイルの ~/.aside/u/<id>/models.json 内の providers.opencodex のみを管理します。他のプロバイダーは変更しません。適用後は Aside を完全に終了してから開き直してください。",
   "integrations.semantics.raycast": "Raycast の providers.yaml に OpenCodex のプロバイダーエントリを追加し、ルーティングされたすべてのモデルを Raycast AI のモデル選択に表示します。Raycast Pro が必要です。",
+  "integrations.semantics.omo": "omo の models.json にある providers.opencodex のみを管理します。場所は ~/.omo/agent で、OMO_CODING_AGENT_DIR・SENPI_CODING_AGENT_DIR・PI_CODING_AGENT_DIR のいずれかが設定されている場合はそちらが優先されます。他のプロバイダーは変更しません。新しいセッションから適用されます。",
+  "integrations.semantics.cline": "Cline CLI の providers.json と models.json の OpenCodex 項目を管理します。変更・同期前に Cline を終了し、完了後に再起動してください。元に戻すと両方の元ファイルが復元されます。既定のプロバイダーは変わりません。Cline で OpenCodex を選択してください。",
   "integrations.raycast.proRequired": "Custom Providers は Raycast Pro の機能です。ファイルは書き込まれますが、Pro サブスクリプションが有効になるまで Raycast はこれを無視します。",
   "integrations.raycast.planUnknown": "Raycast Pro が有効かどうか確認できませんでした。Custom Providers には Raycast Pro が必要です。",
   "integrations.raycast.revealConfig": "Raycast → 設定 → AI を開き、「Reveal Providers Config」を一度クリックして providers フォルダを作成してください。",
@@ -1936,6 +1943,45 @@ export const ja: Record<TKey, string> = {
   "codexAuth.creditGranted": "付与 {date}",
   "codexAuth.creditExpires": "失効 {date} (残り {days}日)",
 
+  // grok reset coupons (xAI account rows)
+  "grokCoupon.badgeAria": "{count} 個の Grok リセットクーポン",
+  "grokCoupon.badgeErrorAria": "Grok リセットクーポンを読み取れませんでした",
+  "grokCoupon.title": "Grok リセットクーポン",
+  "grokCoupon.available": "このアカウントには {count} 個のリセットクーポンがあります。",
+  "grokCoupon.desc": "クーポンはこのアカウントの Grok 使用量枠を即座にリセットします。",
+  "grokCoupon.none": "このアカウントにはリセットクーポンはありません。",
+  "grokCoupon.loadFailed": "このアカウントのリセットクーポンを読み取れませんでした。",
+  "grokCoupon.loadFailedAuth": "クーポンを読み取るには、この xAI アカウントに再度サインインしてください。",
+  "grokCoupon.retry": "再試行",
+  "grokCoupon.couponLabel": "クーポン #{n}",
+  "grokCoupon.couponNext": "次に使用",
+  "grokCoupon.couponNextBadge": "次",
+  "grokCoupon.validFrom": "有効開始 {date}",
+  "grokCoupon.expires": "失効 {date} (残り {days}日)",
+  "grokCoupon.useOne": "1 クーポンを使用",
+  "grokCoupon.fifoNote": "最も失効が近いクーポンが先に使用されます。",
+  "grokCoupon.confirmTitle": "リセットクーポンを使用しますか?",
+  "grokCoupon.confirmDesc": "このアカウントの Grok 使用量枠を即座にリセットします。残り {count} クーポンです。",
+  "grokCoupon.confirmWhich": "{date} に失効するクーポンが使用されます。",
+  "grokCoupon.irreversible": "この操作は元に戻せません。",
+  "grokCoupon.redeem": "クーポンを使用",
+  "grokCoupon.redeeming": "引き換え中…",
+  "grokCoupon.redeemSuccess": "クーポンを引き換えました。残り {count} クーポンです。",
+  "grokCoupon.redeemReplayed": "この引き換えは既に完了しています。クーポンは再度消費されていません。",
+  "grokCoupon.redeemFailed": "引き換えに失敗しました。再試行する前にクーポン一覧を確認してください。",
+  "grokCoupon.authFailed": "クーポンを使用するには、この xAI アカウントに再度サインインしてください。",
+  "grokCoupon.noAccount": "この引き換えに使用できる xAI アカウントがありません。",
+  "grokCoupon.noneAvailable": "引き換え可能なリセットクーポンはありません。",
+  "grokCoupon.identityMismatch": "この引き換えは別のアカウントのものです。このダイアログを閉じてやり直してください。",
+  "grokCoupon.networkError": "プロキシに到達できませんでした。",
+  "grokCoupon.capacity": "引き換えジャーナルが現在満杯です。しばらくしてから再試行してください。",
+  "grokCoupon.noOperationId": "このブラウザでは引き換え ID を生成できないため、ここでは引き換えできません。",
+  "grokCoupon.unknownOutcome": "引き換えの応答が間に合わなかったため、結果は不明です。アカウントを再読み込みして、クーポンが消費されたかどうかを確認してください。",
+  "grokCoupon.checkResult": "アカウントを再読み込み",
+  "grokCoupon.checking": "再読み込み中…",
+  "grokCoupon.consumedElsewhere": "このアカウントからクーポンがなくなっているため、引き換えは完了しています。",
+  "grokCoupon.unresolved": "クーポンはまだ一覧にあります。上流で引き換えが進行中の可能性があります。別のクーポンを使う前に、しばらくしてから再読み込みしてください。",
+
   // api access page
   "api.title": "API アクセス",
   "api.subtitle": "生成した API キーで外部アプリから opencodex プロキシに接続します。認証は {authHeader} ヘッダーで行い、エンドポイントごとに受け付けるヘッダーは下の表のとおりです。",
@@ -2024,13 +2070,17 @@ export const ja: Record<TKey, string> = {
   "api.clientConfig.clientHermes": "Hermes",
   "api.clientConfig.clientOpenclaw": "OpenClaw",
   "api.clientConfig.clientKimi": "Kimi Code",
-  "api.clientConfig.clientGajae": "Gajae Code",
+  "api.clientConfig.clientGajae": "gjc",
   "api.clientConfig.clientDsh": "DeepSeek Harness (DSH)",
   "api.clientConfig.clientMcode": "MiniMax Code",
   "api.clientConfig.clientZcode": "ZCode",
   "api.clientConfig.clientPrime": "Prime Agent",
   "api.clientConfig.clientAside": "Aside",
   "api.clientConfig.clientRaycast": "Raycast",
+  "api.clientConfig.clientOmo": "omo",
+  "api.clientConfig.clientCline": "Cline CLI",
+  "api.clientConfig.clineBundle": "これは Cline 設定ファイルではなく、2 ファイル分のデータです。settings を providers.json に、catalog を隣の models.json にマージしてください。バックアップ付きの書き込みには統合スイッチを使ってください。",
+  "api.clientConfig.clineDownloaded": "{filename} をダウンロードしました。設定はまだ変わっていません。settings と catalog は別々の Cline ファイルに保存します。",
   "api.clientConfig.copy": "設定をコピー",
   "api.clientConfig.download": "ダウンロード",
   "api.clientConfig.loading": "クライアント設定を生成中…",
diff --git a/gui/src/i18n/ko.ts b/gui/src/i18n/ko.ts
index 34d5ceae87..ccd2b06735 100644
--- a/gui/src/i18n/ko.ts
+++ b/gui/src/i18n/ko.ts
@@ -1133,13 +1133,15 @@ export const ko: Record<TKey, string> = {
   "integrations.tab.hermes": "Hermes",
   "integrations.tab.openclaw": "OpenClaw",
   "integrations.tab.kimi": "Kimi Code",
-  "integrations.tab.gajae": "Gajae Code",
+  "integrations.tab.gajae": "gjc",
   "integrations.tab.dsh": "DSH",
   "integrations.tab.mcode": "MiniMax Code",
   "integrations.tab.zcode": "ZCode",
   "integrations.tab.prime": "Prime Agent",
   "integrations.tab.aside": "Aside",
   "integrations.tab.raycast": "Raycast",
+  "integrations.tab.omo": "omo",
+  "integrations.tab.cline": "Cline CLI",
   "integrations.aside.profilesTitle": "Aside 프로필",
   "integrations.aside.profilesHint": "선택한 모델을 동기화할 프로필을 고르세요. Aside에서 사용 중인 프로필은 바뀌지 않습니다.",
   "integrations.aside.all": "모든 프로필 동기화",
@@ -1300,6 +1302,8 @@ export const ko: Record<TKey, string> = {
   "integrations.semantics.prime": "Prime Agent의 models.json에서 providers.opencodex만 관리합니다. 위치는 ~/.prime/agent이며 PRIME_AGENT_CODING_AGENT_DIR가 설정되면 그쪽이 우선합니다. 다른 프로바이더와 모델 오버라이드는 변경하지 않습니다. 새 세션부터 적용됩니다.",
   "integrations.semantics.aside": "이 프로필의 ~/.aside/u/<id>/models.json에서 providers.opencodex만 관리합니다. 다른 프로바이더는 그대로 유지됩니다. 적용 후 Aside를 완전히 종료하고 다시 여세요.",
   "integrations.semantics.raycast": "Raycast의 providers.yaml에 OpenCodex 프로바이더 항목을 추가해 라우팅된 모든 모델이 Raycast AI 모델 선택기에 표시되도록 합니다. Raycast Pro가 필요합니다.",
+  "integrations.semantics.omo": "omo의 models.json에서 providers.opencodex만 관리합니다. 위치는 ~/.omo/agent이며 OMO_CODING_AGENT_DIR, SENPI_CODING_AGENT_DIR, PI_CODING_AGENT_DIR 중 설정된 값이 있으면 그쪽이 우선합니다. 다른 프로바이더는 그대로 유지됩니다. 새 세션부터 적용됩니다.",
+  "integrations.semantics.cline": "Cline CLI의 providers.json과 models.json에서 OpenCodex 항목을 관리합니다. 변경·동기화 전에 Cline을 종료하고 완료 후 다시 실행하세요. 되돌리기는 두 파일의 원본을 복원합니다. 기본 프로바이더는 유지되므로 Cline에서 OpenCodex를 선택하세요.",
   "integrations.raycast.proRequired": "Custom Providers는 Raycast Pro 기능입니다. 파일은 기록되지만 Pro 구독이 활성화될 때까지 Raycast는 이를 무시합니다.",
   "integrations.raycast.planUnknown": "Raycast Pro 활성 여부를 확인할 수 없습니다. Custom Providers에는 Raycast Pro가 필요합니다.",
   "integrations.raycast.revealConfig": "Raycast → 설정 → AI를 열고 「Reveal Providers Config」를 한 번 클릭해 providers 폴더를 만드세요.",
@@ -1540,6 +1544,45 @@ export const ko: Record<TKey, string> = {
   "codexAuth.creditGranted": "획득 {date}",
   "codexAuth.creditExpires": "만료 {date} ({days}일 남음)",
 
+  // grok reset coupons (xAI account rows)
+  "grokCoupon.badgeAria": "Grok 리셋 쿠폰 {count}개",
+  "grokCoupon.badgeErrorAria": "Grok 리셋 쿠폰을 읽지 못했습니다",
+  "grokCoupon.title": "Grok 리셋 쿠폰",
+  "grokCoupon.available": "이 계정에 리셋 쿠폰이 {count}개 있습니다.",
+  "grokCoupon.desc": "쿠폰 1개로 이 계정의 Grok 사용량 윈도우를 즉시 초기화합니다.",
+  "grokCoupon.none": "이 계정에는 리셋 쿠폰이 없습니다.",
+  "grokCoupon.loadFailed": "이 계정의 리셋 쿠폰을 읽지 못했습니다.",
+  "grokCoupon.loadFailedAuth": "쿠폰을 읽으려면 이 xAI 계정에 다시 로그인하세요.",
+  "grokCoupon.retry": "다시 시도",
+  "grokCoupon.couponLabel": "쿠폰 #{n}",
+  "grokCoupon.couponNext": "다음 사용 대상",
+  "grokCoupon.couponNextBadge": "NEXT",
+  "grokCoupon.validFrom": "유효 시작 {date}",
+  "grokCoupon.expires": "만료 {date} ({days}일 남음)",
+  "grokCoupon.useOne": "쿠폰 1개 사용",
+  "grokCoupon.fifoNote": "만료가 가장 가까운 쿠폰부터 사용됩니다.",
+  "grokCoupon.confirmTitle": "리셋 쿠폰을 사용하시겠습니까?",
+  "grokCoupon.confirmDesc": "이 계정의 Grok 사용량 윈도우가 즉시 초기화됩니다. 남은 쿠폰: {count}개.",
+  "grokCoupon.confirmWhich": "{date}에 만료되는 쿠폰이 사용됩니다.",
+  "grokCoupon.irreversible": "이 작업은 되돌릴 수 없습니다.",
+  "grokCoupon.redeem": "쿠폰 사용",
+  "grokCoupon.redeeming": "사용 중…",
+  "grokCoupon.redeemSuccess": "쿠폰을 사용했습니다. 남은 쿠폰: {count}개.",
+  "grokCoupon.redeemReplayed": "이 사용은 이전에 이미 완료되었습니다. 쿠폰이 다시 사용되지 않았습니다.",
+  "grokCoupon.redeemFailed": "쿠폰 사용에 실패했습니다. 다시 시도하기 전에 쿠폰 목록을 확인하세요.",
+  "grokCoupon.authFailed": "쿠폰을 사용하려면 이 xAI 계정에 다시 로그인하세요.",
+  "grokCoupon.noAccount": "이 사용에 쓸 수 있는 xAI 계정이 없습니다.",
+  "grokCoupon.noneAvailable": "사용 가능한 리셋 쿠폰이 없습니다.",
+  "grokCoupon.identityMismatch": "해당 사용은 다른 계정에 속합니다. 이 대화상자를 닫고 다시 시작하세요.",
+  "grokCoupon.networkError": "프록시에 연결할 수 없습니다.",
+  "grokCoupon.capacity": "지금은 사용 저널이 가득 찼습니다. 잠시 후 다시 시도하세요.",
+  "grokCoupon.noOperationId": "이 브라우저는 사용 ID를 생성할 수 없어 여기서는 쿠폰을 사용할 수 없습니다.",
+  "grokCoupon.unknownOutcome": "사용 요청이 제때 응답하지 않아 결과를 알 수 없습니다. 계정을 다시 읽어 쿠폰이 사용되었는지 확인하세요.",
+  "grokCoupon.checkResult": "계정 다시 읽기",
+  "grokCoupon.checking": "다시 읽는 중…",
+  "grokCoupon.consumedElsewhere": "이 계정에서 쿠폰이 없어졌으므로 사용이 완료되었습니다.",
+  "grokCoupon.unresolved": "쿠폰이 아직 목록에 있습니다. 업스트림에서 사용이 계속 진행 중일 수 있습니다 — 다른 쿠폰을 쓰기 전에 잠시 후 다시 읽으세요.",
+
   // api access page
   "api.title": "API 액세스",
   "api.subtitle": "생성한 API 키로 외부 앱에서 opencodex 프록시에 접속합니다. 인증은 {authHeader} 헤더로 하며, 엔드포인트별로 받는 헤더는 아래 표에 있습니다.",
@@ -1628,13 +1671,17 @@ export const ko: Record<TKey, string> = {
   "api.clientConfig.clientHermes": "Hermes",
   "api.clientConfig.clientOpenclaw": "OpenClaw",
   "api.clientConfig.clientKimi": "Kimi Code",
-  "api.clientConfig.clientGajae": "Gajae Code",
+  "api.clientConfig.clientGajae": "gjc",
   "api.clientConfig.clientDsh": "DeepSeek Harness (DSH)",
   "api.clientConfig.clientMcode": "MiniMax Code",
   "api.clientConfig.clientZcode": "ZCode",
   "api.clientConfig.clientPrime": "Prime Agent",
   "api.clientConfig.clientAside": "Aside",
   "api.clientConfig.clientRaycast": "Raycast",
+  "api.clientConfig.clientOmo": "omo",
+  "api.clientConfig.clientCline": "Cline CLI",
+  "api.clientConfig.clineBundle": "이 묶음은 Cline 설정 파일 자체가 아닙니다. settings는 providers.json에, catalog는 옆의 models.json에 병합하세요. 백업을 남기려면 통합 스위치를 사용하세요.",
+  "api.clientConfig.clineDownloaded": "{filename}을 다운로드했습니다. 아직 설정은 바뀌지 않았습니다. settings와 catalog는 서로 다른 Cline 파일에 넣어야 합니다.",
   "api.clientConfig.copy": "설정 복사",
   "api.clientConfig.download": "다운로드",
   "api.clientConfig.loading": "클라이언트 설정 생성 중…",
@@ -1935,7 +1982,10 @@ export const ko: Record<TKey, string> = {
   "modal.freeTierDefault": "API 키가 필요 없습니다. 바로 사용할 수 있습니다.",
   "modal.tab.accounts": "계정",
   "modal.tab.free": "무료",
+  "modal.tab.local": "로컬",
   "modal.tab.paid": "유료",
+  "modal.noteMore": "설명 전체 보기",
+  "modal.searchResults": "{tiers}에서 {count}개",
   "modal.accountsHint": "여기서 ChatGPT/Codex, OAuth, API 키 계정에 로그인하세요. OpenAI는 기본 제공 — 다시 추가하지 말고 로그인하세요.",
   "modal.accountsCodexAuthLink": "Codex 인증",
   "modal.notListed": "찾는 프로바이더가 없나요? 직접 추가",
diff --git a/gui/src/i18n/ru.ts b/gui/src/i18n/ru.ts
index 488f87d55b..ceb0c18a92 100644
--- a/gui/src/i18n/ru.ts
+++ b/gui/src/i18n/ru.ts
@@ -1123,7 +1123,10 @@ export const ru: Record<TKey, string> = {
   "modal.freeTierDefault": "API-ключ не нужен. Работает из коробки.",
   "modal.tab.accounts": "Аккаунты",
   "modal.tab.free": "Бесплатные",
+  "modal.tab.local": "Локальные",
   "modal.tab.paid": "Платные",
+  "modal.noteMore": "Показать полное описание",
+  "modal.searchResults": "{count} результатов в {tiers}",
   "modal.accountsHint": "Здесь можно войти в аккаунты ChatGPT/Codex и OAuth-провайдеров, а также в аккаунты с API-ключами. Провайдер OpenAI уже встроен — просто войдите, а не добавляйте его заново.",
   "modal.accountsCodexAuthLink": "Аутентификация Codex",
   "modal.notListed": "Нет нужного провайдера? Добавьте свой",
@@ -1597,13 +1600,15 @@ export const ru: Record<TKey, string> = {
   "integrations.tab.hermes": "Hermes",
   "integrations.tab.openclaw": "OpenClaw",
   "integrations.tab.kimi": "Kimi Code",
-  "integrations.tab.gajae": "Gajae Code",
+  "integrations.tab.gajae": "gjc",
   "integrations.tab.dsh": "DSH",
   "integrations.tab.mcode": "MiniMax Code",
   "integrations.tab.zcode": "ZCode",
   "integrations.tab.prime": "Prime Agent",
   "integrations.tab.aside": "Aside",
   "integrations.tab.raycast": "Raycast",
+  "integrations.tab.omo": "omo",
+  "integrations.tab.cline": "Cline CLI",
   "integrations.aside.profilesTitle": "Профили Aside",
   "integrations.aside.profilesHint": "Выберите профили, в которые будут добавлены выбранные модели. Активный профиль Aside не изменится.",
   "integrations.aside.all": "Синхронизировать все профили",
@@ -1764,6 +1769,8 @@ export const ru: Record<TKey, string> = {
   "integrations.semantics.prime": "Управляет только providers.opencodex в models.json Prime Agent — ~/.prime/agent, если PRIME_AGENT_CODING_AGENT_DIR не переопределяет путь. Другие провайдеры и переопределения моделей не меняются. Применяется к новым сессиям.",
   "integrations.semantics.aside": "Управляет только providers.opencodex в файле ~/.aside/u/<id>/models.json этого профиля. Другие провайдеры остаются без изменений. После применения полностью закройте и снова откройте Aside.",
   "integrations.semantics.raycast": "Добавляет запись провайдера OpenCodex в providers.yaml Raycast, чтобы каждая маршрутизируемая модель появилась в выборе моделей Raycast AI. Требуется Raycast Pro.",
+  "integrations.semantics.omo": "Управляет только providers.opencodex в models.json omo — ~/.omo/agent, если только OMO_CODING_AGENT_DIR, SENPI_CODING_AGENT_DIR или PI_CODING_AGENT_DIR не перенаправляет путь. Остальные провайдеры остаются без изменений. Применяется к новым сессиям.",
+  "integrations.semantics.cline": "Управляет OpenCodex в файлах providers.json и models.json Cline CLI. Закройте Cline перед изменением или синхронизацией и запустите снова после завершения. Отмена восстанавливает оба исходных файла. Провайдер по умолчанию не меняется; выберите OpenCodex в Cline.",
   "integrations.raycast.proRequired": "Custom Providers — функция Raycast Pro. Файл будет записан, но Raycast игнорирует его, пока не активна подписка Pro.",
   "integrations.raycast.planUnknown": "Не удалось определить, активен ли Raycast Pro; для Custom Providers требуется Raycast Pro.",
   "integrations.raycast.revealConfig": "Откройте Raycast → Настройки → AI и один раз нажмите «Reveal Providers Config», чтобы папка провайдеров появилась.",
@@ -2006,6 +2013,45 @@ export const ru: Record<TKey, string> = {
   "codexAuth.creditGranted": "Начислен {date}",
   "codexAuth.creditExpires": "Истекает {date} (осталось {days} дн.)",
 
+  // grok reset coupons (xAI account rows)
+  "grokCoupon.badgeAria": "Купонов сброса Grok: {count}",
+  "grokCoupon.badgeErrorAria": "Не удалось прочитать купоны сброса Grok",
+  "grokCoupon.title": "Купоны сброса Grok",
+  "grokCoupon.available": "У этого аккаунта доступно купонов сброса: {count}.",
+  "grokCoupon.desc": "Купон мгновенно сбрасывает окно использования Grok этого аккаунта.",
+  "grokCoupon.none": "У этого аккаунта нет купонов сброса.",
+  "grokCoupon.loadFailed": "Не удалось прочитать купоны сброса для этого аккаунта.",
+  "grokCoupon.loadFailedAuth": "Войдите в этот аккаунт xAI ещё раз, чтобы прочитать его купоны.",
+  "grokCoupon.retry": "Повторить",
+  "grokCoupon.couponLabel": "Купон №{n}",
+  "grokCoupon.couponNext": "Следующий к использованию",
+  "grokCoupon.couponNextBadge": "СЛЕД.",
+  "grokCoupon.validFrom": "Действует с {date}",
+  "grokCoupon.expires": "Истекает {date} (осталось {days} дн.)",
+  "grokCoupon.useOne": "Использовать 1 купон",
+  "grokCoupon.fifoNote": "Первым используется купон с ближайшим сроком истечения.",
+  "grokCoupon.confirmTitle": "Использовать купон сброса?",
+  "grokCoupon.confirmDesc": "Окно использования Grok этого аккаунта будет сброшено сейчас. У вас купонов: {count}.",
+  "grokCoupon.confirmWhich": "Будет использован купон, истекающий {date}.",
+  "grokCoupon.irreversible": "Это действие нельзя отменить.",
+  "grokCoupon.redeem": "Использовать купон",
+  "grokCoupon.redeeming": "Использование…",
+  "grokCoupon.redeemSuccess": "Купон использован. Осталось купонов: {count}.",
+  "grokCoupon.redeemReplayed": "Это использование уже было учтено ранее. Повторно ничего не списано.",
+  "grokCoupon.redeemFailed": "Не удалось использовать купон. Перед повторной попыткой проверьте список купонов.",
+  "grokCoupon.authFailed": "Войдите в этот аккаунт xAI ещё раз, чтобы использовать его купоны.",
+  "grokCoupon.noAccount": "Для этого использования нет доступного аккаунта xAI.",
+  "grokCoupon.noneAvailable": "Нет доступных купонов сброса.",
+  "grokCoupon.identityMismatch": "Это использование относится к другому аккаунту. Закройте это окно и начните заново.",
+  "grokCoupon.networkError": "Не удалось связаться с прокси.",
+  "grokCoupon.capacity": "Журнал использования сейчас заполнен. Попробуйте ещё раз чуть позже.",
+  "grokCoupon.noOperationId": "Этот браузер не может создать идентификатор использования, поэтому здесь использование купонов отключено.",
+  "grokCoupon.unknownOutcome": "Ответ по использованию не пришёл вовремя, поэтому результат неизвестен. Перечитайте аккаунт, чтобы узнать, был ли купон потрачен.",
+  "grokCoupon.checkResult": "Перечитать аккаунт",
+  "grokCoupon.checking": "Перечитывание…",
+  "grokCoupon.consumedElsewhere": "Купона больше нет в этом аккаунте — значит, использование прошло успешно.",
+  "grokCoupon.unresolved": "Купон всё ещё в списке. Использование, возможно, ещё выполняется на стороне вышестоящего сервиса — через минуту перечитайте аккаунт, прежде чем тратить другой купон.",
+
   // api access page
   "api.title": "Доступ по API",
   "api.subtitle": "Сгенерированные API-ключи дают внешним приложениям доступ к прокси opencodex. Аутентификация — через заголовок {authHeader}; какие заголовки принимает каждый эндпоинт, смотрите в таблице ниже.",
@@ -2094,13 +2140,17 @@ export const ru: Record<TKey, string> = {
   "api.clientConfig.clientHermes": "Hermes",
   "api.clientConfig.clientOpenclaw": "OpenClaw",
   "api.clientConfig.clientKimi": "Kimi Code",
-  "api.clientConfig.clientGajae": "Gajae Code",
+  "api.clientConfig.clientGajae": "gjc",
   "api.clientConfig.clientDsh": "DeepSeek Harness (DSH)",
   "api.clientConfig.clientMcode": "MiniMax Code",
   "api.clientConfig.clientZcode": "ZCode",
   "api.clientConfig.clientPrime": "Prime Agent",
   "api.clientConfig.clientAside": "Aside",
   "api.clientConfig.clientRaycast": "Raycast",
+  "api.clientConfig.clientOmo": "omo",
+  "api.clientConfig.clientCline": "Cline CLI",
+  "api.clientConfig.clineBundle": "Это пакет для двух файлов, а не файл настроек Cline. Объедините settings с providers.json, а catalog — с models.json в той же папке. Переключатель интеграции создаёт резервную копию перед записью.",
+  "api.clientConfig.clineDownloaded": "Файл {filename} загружен. Настройки ещё не изменены; settings и catalog предназначены для двух отдельных файлов Cline.",
   "api.clientConfig.copy": "Копировать конфигурацию",
   "api.clientConfig.download": "Скачать",
   "api.clientConfig.loading": "Формируется конфигурация клиента…",
diff --git a/gui/src/i18n/tr.ts b/gui/src/i18n/tr.ts
index 2e46e2792f..26a8f93d09 100644
--- a/gui/src/i18n/tr.ts
+++ b/gui/src/i18n/tr.ts
@@ -1142,7 +1142,10 @@ export const tr: Record<TKey, string> = {
   "modal.freeTierDefault": "API anahtarı gerekmez. Doğrudan çalışır.",
   "modal.tab.accounts": "Hesaplar",
   "modal.tab.free": "Ücretsiz",
+  "modal.tab.local": "Yerel",
   "modal.tab.paid": "Ücretli",
+  "modal.noteMore": "Açıklamanın tamamını göster",
+  "modal.searchResults": "{tiers} içinde {count} sonuç",
   "modal.accountsHint": "ChatGPT/Codex ve OAuth hesaplarına buradan giriş yapın.",
   "modal.accountsCodexAuthLink": "Codex Kimlik Doğrulaması",
   "modal.notListed": "Sağlayıcı listede yok mu? Özel sağlayıcı ekleyin",
@@ -1616,13 +1619,15 @@ export const tr: Record<TKey, string> = {
   "integrations.tab.hermes": "Hermes",
   "integrations.tab.openclaw": "OpenClaw",
   "integrations.tab.kimi": "Kimi Code",
-  "integrations.tab.gajae": "Gajae Code",
+  "integrations.tab.gajae": "gjc",
   "integrations.tab.dsh": "DSH",
   "integrations.tab.mcode": "MiniMax Code",
   "integrations.tab.zcode": "ZCode",
   "integrations.tab.prime": "Prime Agent",
   "integrations.tab.aside": "Aside",
   "integrations.tab.raycast": "Raycast",
+  "integrations.tab.omo": "omo",
+  "integrations.tab.cline": "Cline CLI",
   "integrations.aside.profilesTitle": "Aside profilleri",
   "integrations.aside.profilesHint": "Seçili modellerin hangi profillere aktarılacağını seçin. Aside’ın etkin profili değişmez.",
   "integrations.aside.all": "Tüm profilleri eşitle",
@@ -1782,6 +1787,8 @@ export const tr: Record<TKey, string> = {
   "integrations.semantics.prime": "Yalnızca Prime Agent'ın models.json dosyasındaki providers.opencodex bölümünü yönetir — PRIME_AGENT_CODING_AGENT_DIR ayarlı değilse ~/.prime/agent. Diğer sağlayıcılar ve model geçersiz kılmaları değişmez. Yeni oturumlarda geçerli olur.",
   "integrations.semantics.aside": "Yalnızca bu profilin ~/.aside/u/<id>/models.json dosyasındaki providers.opencodex bölümünü yönetir. Diğer sağlayıcılarınız değişmez. Uyguladıktan sonra Aside’ı tamamen kapatıp yeniden açın.",
   "integrations.semantics.raycast": "Raycast'in providers.yaml dosyasına bir OpenCodex sağlayıcı girdisi ekler; böylece yönlendirilen her model Raycast AI model seçicisinde görünür. Raycast Pro gerekir.",
+  "integrations.semantics.omo": "Yalnızca omo'nun models.json dosyasındaki providers.opencodex girdisini yönetir — OMO_CODING_AGENT_DIR, SENPI_CODING_AGENT_DIR veya PI_CODING_AGENT_DIR yönlendirmediği sürece ~/.omo/agent. Diğer sağlayıcılarınız değişmeden kalır. Yeni oturumlardan itibaren geçerlidir.",
+  "integrations.semantics.cline": "Cline CLI providers.json ve models.json dosyalarındaki OpenCodex girdilerini yönetir. Değişiklik veya eşitleme öncesinde Cline’ı kapatın, ardından yeniden başlatın. Geri al iki özgün dosyayı da geri yükler. Varsayılan sağlayıcınız değişmez; Cline içinde OpenCodex’i seçin.",
   "integrations.raycast.proRequired": "Custom Providers bir Raycast Pro özelliğidir. Dosya yazılır, ancak bir Pro aboneliği etkin olana kadar Raycast bunu yok sayar.",
   "integrations.raycast.planUnknown": "Raycast Pro’nun etkin olup olmadığı belirlenemedi; Custom Providers için Raycast Pro gerekir.",
   "integrations.raycast.revealConfig": "Raycast → Ayarlar → AI bölümünü açıp sağlayıcı klasörünün oluşması için „Reveal Providers Config“ seçeneğine bir kez tıklayın.",
@@ -2026,6 +2033,45 @@ export const tr: Record<TKey, string> = {
   "codexAuth.creditGranted": "Verildiği tarih {date}",
   "codexAuth.creditExpires": "Son kullanma {date} ({days}gün kaldı)",
 
+  // grok reset coupons (xAI account rows)
+  "grokCoupon.badgeAria": "{count} Grok sıfırlama kuponu",
+  "grokCoupon.badgeErrorAria": "Grok sıfırlama kuponları okunamadı",
+  "grokCoupon.title": "Grok Sıfırlama Kuponları",
+  "grokCoupon.available": "Bu hesapta {count} sıfırlama kuponu var.",
+  "grokCoupon.desc": "Bir kupon, bu hesabın Grok kullanım penceresini anında sıfırlar.",
+  "grokCoupon.none": "Bu hesapta sıfırlama kuponu yok.",
+  "grokCoupon.loadFailed": "Bu hesabın sıfırlama kuponları okunamadı.",
+  "grokCoupon.loadFailedAuth": "Kuponlarını okumak için bu xAI hesabına tekrar giriş yapın.",
+  "grokCoupon.retry": "Tekrar Dene",
+  "grokCoupon.couponLabel": "Kupon #{n}",
+  "grokCoupon.couponNext": "Sonraki kullanılacak",
+  "grokCoupon.couponNextBadge": "SONRAKİ",
+  "grokCoupon.validFrom": "Geçerlilik başlangıcı {date}",
+  "grokCoupon.expires": "Son kullanma {date} ({days}gün kaldı)",
+  "grokCoupon.useOne": "1 Kupon Kullan",
+  "grokCoupon.fifoNote": "Süresi en yakın dolacak kupon ilk önce kullanılır.",
+  "grokCoupon.confirmTitle": "Sıfırlama Kuponu Kullanılsın mı?",
+  "grokCoupon.confirmDesc": "Bu işlem bu hesabın Grok kullanım penceresini şimdi sıfırlar. {count} kuponunuz var.",
+  "grokCoupon.confirmWhich": "{date} tarihinde süresi dolacak kupon kullanılacak.",
+  "grokCoupon.irreversible": "Bu işlem geri alınamaz.",
+  "grokCoupon.redeem": "Kupon Kullan",
+  "grokCoupon.redeeming": "Kullanılıyor…",
+  "grokCoupon.redeemSuccess": "Kupon kullanıldı. {count} kupon kaldı.",
+  "grokCoupon.redeemReplayed": "Bu kullanım daha önce tamamlanmış. Yeniden bir şey tüketilmedi.",
+  "grokCoupon.redeemFailed": "Kullanım başarısız oldu. Tekrar denemeden önce kupon listesini kontrol edin.",
+  "grokCoupon.authFailed": "Kuponlarını kullanmak için bu xAI hesabına tekrar giriş yapın.",
+  "grokCoupon.noAccount": "Bu kullanım için uygun bir xAI hesabı yok.",
+  "grokCoupon.noneAvailable": "Kullanılabilir sıfırlama kuponu yok.",
+  "grokCoupon.identityMismatch": "Bu kullanım başka bir hesaba ait. Bu iletişim kutusunu kapatıp yeniden başlayın.",
+  "grokCoupon.networkError": "Proxy'ye ulaşılamadı.",
+  "grokCoupon.capacity": "Kullanım günlüğü şu anda dolu. Biraz sonra tekrar deneyin.",
+  "grokCoupon.noOperationId": "Bu tarayıcı bir kullanım kimliği üretemiyor, bu yüzden kupon kullanma burada devre dışı.",
+  "grokCoupon.unknownOutcome": "Kullanım zamanında yanıt vermedi, bu yüzden sonucu bilinmiyor. Kuponun harcanıp harcanmadığını görmek için hesabı yeniden okuyun.",
+  "grokCoupon.checkResult": "Hesabı yeniden oku",
+  "grokCoupon.checking": "Yeniden okunuyor…",
+  "grokCoupon.consumedElsewhere": "Kupon bu hesapta artık yok, yani kullanım gerçekleşmiş.",
+  "grokCoupon.unresolved": "Kupon hâlâ listede. Kullanım üst akışta hâlâ sürüyor olabilir — başka bir kupon harcamadan önce bir dakika sonra yeniden okuyun.",
+
   // api access page
   "api.title": "API Erişimi",
   "api.subtitle": "Harici uygulamalardan opencodex proxy'sine erişmek için üretilen API anahtarlarını kullanın. Anahtarlar {authHeader} başlığı üzerinden kimlik doğrulaması yapar; her bir uç noktanın neleri kabul ettiğini görmek için aşağıdaki tabloya bakın.",
@@ -2113,13 +2159,17 @@ export const tr: Record<TKey, string> = {
   "api.clientConfig.clientHermes": "Hermes",
   "api.clientConfig.clientOpenclaw": "OpenClaw",
   "api.clientConfig.clientKimi": "Kimi Code",
-  "api.clientConfig.clientGajae": "Gajae Code",
+  "api.clientConfig.clientGajae": "gjc",
   "api.clientConfig.clientDsh": "DeepSeek Harness (DSH)",
   "api.clientConfig.clientMcode": "MiniMax Code",
   "api.clientConfig.clientZcode": "ZCode",
   "api.clientConfig.clientPrime": "Prime Agent",
   "api.clientConfig.clientAside": "Aside",
   "api.clientConfig.clientRaycast": "Raycast",
+  "api.clientConfig.clientOmo": "omo",
+  "api.clientConfig.clientCline": "Cline CLI",
+  "api.clientConfig.clineBundle": "Bu, bir Cline ayar dosyası değil, iki dosyalık bir pakettir. settings içeriğini providers.json, catalog içeriğini aynı klasördeki models.json ile birleştirin. Yazmadan önce yedek almak için entegrasyon anahtarını kullanın.",
+  "api.clientConfig.clineDownloaded": "{filename} indirildi. Henüz değişiklik yapılmadı; settings ve catalog ayrı Cline dosyalarına aittir.",
   "api.clientConfig.copy": "JSON Kopyala",
   "api.clientConfig.download": "İndir",
   "api.clientConfig.loading": "İstemci konfigürasyonu oluşturuluyor…",
diff --git a/gui/src/i18n/zh-TW.ts b/gui/src/i18n/zh-TW.ts
index b9a26da41c..1fb8387f4d 100644
--- a/gui/src/i18n/zh-TW.ts
+++ b/gui/src/i18n/zh-TW.ts
@@ -921,7 +921,10 @@ export const zhTW: Record<TKey, string> = {
   "modal.freeTierDefault": "無需 API 金鑰，開箱即用。",
   "modal.tab.accounts": "帳號",
   "modal.tab.free": "免費",
+  "modal.tab.local": "本地",
   "modal.tab.paid": "付費",
+  "modal.noteMore": "查看完整說明",
+  "modal.searchResults": "在 {tiers} 中找到 {count} 個",
   "modal.accountsHint": "在此登入 ChatGPT/Codex、OAuth 與 API 金鑰帳號。OpenAI 為內建供應商 — 請登入，無需再次新增。",
   "modal.accountsCodexAuthLink": "Codex 認證",
   "modal.notListed": "沒有你要的供應商？新增自訂",
@@ -1548,6 +1551,46 @@ export const zhTW: Record<TKey, string> = {
   "codexAuth.creditNextBadge": "NEXT",
   "codexAuth.creditGranted": "獲得 {date}",
   "codexAuth.creditExpires": "過期 {date}（剩餘 {days} 天）",
+
+  // grok reset coupons (xAI account rows)
+  "grokCoupon.badgeAria": "{count} 張 Grok 重設券",
+  "grokCoupon.badgeErrorAria": "無法讀取 Grok 重設券",
+  "grokCoupon.title": "Grok 重設券",
+  "grokCoupon.available": "此帳號有 {count} 張重設券。",
+  "grokCoupon.desc": "每張券可立即重設此帳號的 Grok 使用視窗。",
+  "grokCoupon.none": "此帳號沒有重設券。",
+  "grokCoupon.loadFailed": "無法讀取此帳號的重設券。",
+  "grokCoupon.loadFailedAuth": "請重新登入此 xAI 帳號以讀取其重設券。",
+  "grokCoupon.retry": "重試",
+  "grokCoupon.couponLabel": "券 #{n}",
+  "grokCoupon.couponNext": "即將使用",
+  "grokCoupon.couponNextBadge": "即將",
+  "grokCoupon.validFrom": "自 {date} 起有效",
+  "grokCoupon.expires": "過期 {date}（剩餘 {days} 天）",
+  "grokCoupon.useOne": "使用 1 張券",
+  "grokCoupon.fifoNote": "最接近過期的券優先使用。",
+  "grokCoupon.confirmTitle": "使用重設券？",
+  "grokCoupon.confirmDesc": "這將立即重設此帳號的 Grok 使用視窗。您有 {count} 張券。",
+  "grokCoupon.confirmWhich": "將使用 {date} 過期的券。",
+  "grokCoupon.irreversible": "此操作無法復原。",
+  "grokCoupon.redeem": "使用券",
+  "grokCoupon.redeeming": "兌換中…",
+  "grokCoupon.redeemSuccess": "券已兌換。剩餘 {count} 張。",
+  "grokCoupon.redeemReplayed": "此兌換稍早已完成，未再次消耗任何券。",
+  "grokCoupon.redeemFailed": "兌換失敗。再次嘗試前請先檢查券列表。",
+  "grokCoupon.authFailed": "請重新登入此 xAI 帳號以使用其重設券。",
+  "grokCoupon.noAccount": "沒有可用於此兌換的 xAI 帳號。",
+  "grokCoupon.noneAvailable": "沒有可兌換的重設券。",
+  "grokCoupon.identityMismatch": "該兌換屬於其他帳號。請關閉此對話框後重新開始。",
+  "grokCoupon.networkError": "無法連線到代理。",
+  "grokCoupon.capacity": "兌換日誌目前已滿。請稍後再試。",
+  "grokCoupon.noOperationId": "此瀏覽器無法產生兌換 ID，因此此處無法兌換。",
+  "grokCoupon.unknownOutcome": "兌換未及時回應，結果未知。請重新讀取帳號以確認券是否已被消耗。",
+  "grokCoupon.checkResult": "重新讀取帳號",
+  "grokCoupon.checking": "正在重新讀取…",
+  "grokCoupon.consumedElsewhere": "此帳號已沒有該券，表示兌換已成功。",
+  "grokCoupon.unresolved": "該券仍在列表中。上游兌換可能仍在進行 — 請等一分鐘後再重新讀取，再使用另一張券。",
+
   "api.title": "API 存取",
   "api.subtitle": "使用生成的 API 金鑰從外部應用存取 opencodex 代理。金鑰透過 {authHeader} 標頭認證；下表顯示每個端點接受什麼。",
   "api.baseUrl": "基礎 URL",
@@ -2204,13 +2247,15 @@ export const zhTW: Record<TKey, string> = {
   "integrations.tab.hermes": "Hermes",
   "integrations.tab.openclaw": "OpenClaw",
   "integrations.tab.kimi": "Kimi Code",
-  "integrations.tab.gajae": "Gajae Code",
+  "integrations.tab.gajae": "gjc",
   "integrations.tab.dsh": "DSH",
   "integrations.tab.mcode": "MiniMax Code",
   "integrations.tab.zcode": "ZCode",
   "integrations.tab.prime": "Prime Agent",
   "integrations.tab.aside": "Aside",
   "integrations.tab.raycast": "Raycast",
+  "integrations.tab.omo": "omo",
+  "integrations.tab.cline": "Cline CLI",
   "integrations.aside.profilesTitle": "Aside 設定檔",
   "integrations.aside.profilesHint": "選擇要接收所選模型的設定檔。Aside 目前使用的設定檔不會改變。",
   "integrations.aside.all": "同步所有設定檔",
@@ -2371,6 +2416,8 @@ export const zhTW: Record<TKey, string> = {
   "integrations.semantics.prime": "僅管理 Prime Agent 的 models.json 中的 providers.opencodex；預設位於 ~/.prime/agent，若設定 PRIME_AGENT_CODING_AGENT_DIR 則以其為準。不會變更其他供應商或模型覆寫設定。對新工作階段生效。",
   "integrations.semantics.aside": "僅管理此設定檔的 ~/.aside/u/<id>/models.json 中的 providers.opencodex。其他供應商維持不變。套用後請完全結束並重新開啟 Aside。",
   "integrations.semantics.raycast": "在 Raycast 的 providers.yaml 中新增一個 OpenCodex 供應商項目，讓所有已路由的模型出現在 Raycast AI 模型選擇器中。需要 Raycast Pro。",
+  "integrations.semantics.omo": "僅管理 omo 的 models.json 中的 providers.opencodex，路徑為 ~/.omo/agent，若設定了 OMO_CODING_AGENT_DIR、SENPI_CODING_AGENT_DIR 或 PI_CODING_AGENT_DIR 則以其為準。你的其他供應商維持不變。對新工作階段生效。",
+  "integrations.semantics.cline": "管理 Cline CLI 的 providers.json 和 models.json 中的 OpenCodex 項目。修改或同步前請結束 Cline，完成後重新啟動。復原會還原兩個檔案的原始內容。預設供應商保持不變，請在 Cline 中選擇 OpenCodex。",
   "integrations.raycast.proRequired": "Custom Providers 是 Raycast Pro 功能。檔案會被寫入，但在 Pro 訂閱生效之前 Raycast 會忽略它。",
   "integrations.raycast.planUnknown": "無法確認 Raycast Pro 是否已啟用；Custom Providers 需要 Raycast Pro。",
   "integrations.raycast.revealConfig": "開啟 Raycast → 設定 → AI，點一次「Reveal Providers Config」，以便建立 providers 資料夾。",
@@ -2409,13 +2456,17 @@ export const zhTW: Record<TKey, string> = {
   "api.clientConfig.clientHermes": "Hermes",
   "api.clientConfig.clientOpenclaw": "OpenClaw",
   "api.clientConfig.clientKimi": "Kimi Code",
-  "api.clientConfig.clientGajae": "Gajae Code",
+  "api.clientConfig.clientGajae": "gjc",
   "api.clientConfig.clientDsh": "DeepSeek Harness (DSH)",
   "api.clientConfig.clientMcode": "MiniMax Code",
   "api.clientConfig.clientZcode": "ZCode",
   "api.clientConfig.clientPrime": "Prime Agent",
   "api.clientConfig.clientAside": "Aside",
   "api.clientConfig.clientRaycast": "Raycast",
+  "api.clientConfig.clientOmo": "omo",
+  "api.clientConfig.clientCline": "Cline CLI",
+  "api.clientConfig.clineBundle": "這是兩個檔案的資料包，不是 Cline 設定檔。將 settings 合併至 providers.json，將 catalog 合併至同目錄的 models.json。使用整合開關可在寫入前備份。",
+  "api.clientConfig.clineDownloaded": "已下載 {filename}，設定尚未變更。settings 與 catalog 應分別儲存至兩個 Cline 檔案。",
   "cws.tabsLabel": "Combo 詳細區段",
   "cws.field.nativeAlias": "原生 OpenAI 別名",
   "cws.field.nativeAliasHint": "讓此 combo 擁有受支援的未限定原生 OpenAI 模型 ID。帶有帳號或供應商限定的 OpenAI 路由仍保持獨立。",
diff --git a/gui/src/i18n/zh.ts b/gui/src/i18n/zh.ts
index 46866680b0..4e2cd831cc 100644
--- a/gui/src/i18n/zh.ts
+++ b/gui/src/i18n/zh.ts
@@ -1114,13 +1114,15 @@ export const zh: Record<TKey, string> = {
   "integrations.tab.hermes": "Hermes",
   "integrations.tab.openclaw": "OpenClaw",
   "integrations.tab.kimi": "Kimi Code",
-  "integrations.tab.gajae": "Gajae Code",
+  "integrations.tab.gajae": "gjc",
   "integrations.tab.dsh": "DSH",
   "integrations.tab.mcode": "MiniMax Code",
   "integrations.tab.zcode": "ZCode",
   "integrations.tab.prime": "Prime Agent",
   "integrations.tab.aside": "Aside",
   "integrations.tab.raycast": "Raycast",
+  "integrations.tab.omo": "omo",
+  "integrations.tab.cline": "Cline CLI",
   "integrations.aside.profilesTitle": "Aside 配置文件",
   "integrations.aside.profilesHint": "选择要接收所选模型的配置文件。Aside 当前使用的配置文件不会改变。",
   "integrations.aside.all": "同步所有配置文件",
@@ -1281,6 +1283,8 @@ export const zh: Record<TKey, string> = {
   "integrations.semantics.prime": "仅管理 Prime Agent 的 models.json 中的 providers.opencodex；默认位于 ~/.prime/agent，若设置 PRIME_AGENT_CODING_AGENT_DIR 则以其为准。不会更改其他提供商或模型覆盖设置。对新会话生效。",
   "integrations.semantics.aside": "仅管理此配置文件的 ~/.aside/u/<id>/models.json 中的 providers.opencodex。其他提供商保持不变。应用后请完全退出并重新打开 Aside。",
   "integrations.semantics.raycast": "在 Raycast 的 providers.yaml 中添加一个 OpenCodex 提供商条目，让所有已路由的模型出现在 Raycast AI 模型选择器中。需要 Raycast Pro。",
+  "integrations.semantics.omo": "仅管理 omo 的 models.json 中的 providers.opencodex，路径为 ~/.omo/agent，若设置了 OMO_CODING_AGENT_DIR、SENPI_CODING_AGENT_DIR 或 PI_CODING_AGENT_DIR 则以其为准。你的其他提供商保持不变。对新会话生效。",
+  "integrations.semantics.cline": "管理 Cline CLI 的 providers.json 和 models.json 中的 OpenCodex 项目。修改或同步前请退出 Cline，完成后重新启动。撤销会恢复两个文件的原始内容。默认提供商保持不变，请在 Cline 中选择 OpenCodex。",
   "integrations.raycast.proRequired": "Custom Providers 是 Raycast Pro 功能。文件会被写入，但在 Pro 订阅生效之前 Raycast 会忽略它。",
   "integrations.raycast.planUnknown": "无法确定 Raycast Pro 是否已激活；Custom Providers 需要 Raycast Pro。",
   "integrations.raycast.revealConfig": "打开 Raycast → 设置 → AI，点击一次“Reveal Providers Config”，以便创建 providers 文件夹。",
@@ -1521,6 +1525,45 @@ export const zh: Record<TKey, string> = {
   "codexAuth.creditGranted": "获得 {date}",
   "codexAuth.creditExpires": "过期 {date}（剩余 {days} 天）",
 
+  // grok reset coupons (xAI account rows)
+  "grokCoupon.badgeAria": "{count} 张 Grok 重置券",
+  "grokCoupon.badgeErrorAria": "无法读取 Grok 重置券",
+  "grokCoupon.title": "Grok 重置券",
+  "grokCoupon.available": "此账号有 {count} 张重置券。",
+  "grokCoupon.desc": "每张券可立即重置此账号的 Grok 使用窗口。",
+  "grokCoupon.none": "此账号没有重置券。",
+  "grokCoupon.loadFailed": "无法读取此账号的重置券。",
+  "grokCoupon.loadFailedAuth": "请重新登录此 xAI 账号以读取其重置券。",
+  "grokCoupon.retry": "重试",
+  "grokCoupon.couponLabel": "券 #{n}",
+  "grokCoupon.couponNext": "即将使用",
+  "grokCoupon.couponNextBadge": "NEXT",
+  "grokCoupon.validFrom": "自 {date} 起有效",
+  "grokCoupon.expires": "过期 {date}（剩余 {days} 天）",
+  "grokCoupon.useOne": "使用 1 张券",
+  "grokCoupon.fifoNote": "最接近过期的券优先使用。",
+  "grokCoupon.confirmTitle": "使用重置券？",
+  "grokCoupon.confirmDesc": "这将立即重置此账号的 Grok 使用窗口。您有 {count} 张券。",
+  "grokCoupon.confirmWhich": "将使用 {date} 过期的券。",
+  "grokCoupon.irreversible": "此操作不可撤销。",
+  "grokCoupon.redeem": "使用券",
+  "grokCoupon.redeeming": "兑换中…",
+  "grokCoupon.redeemSuccess": "券已兑换。剩余 {count} 张。",
+  "grokCoupon.redeemReplayed": "该兑换此前已完成，未再次消耗。",
+  "grokCoupon.redeemFailed": "兑换失败。请先核对券列表再重试。",
+  "grokCoupon.authFailed": "请重新登录此 xAI 账号以使用其重置券。",
+  "grokCoupon.noAccount": "没有可用于此次兑换的 xAI 账号。",
+  "grokCoupon.noneAvailable": "没有可兑换的重置券。",
+  "grokCoupon.identityMismatch": "该兑换属于其他账号。请关闭此对话框后重新开始。",
+  "grokCoupon.networkError": "无法连接到代理。",
+  "grokCoupon.capacity": "兑换日志目前已满。请稍后再试。",
+  "grokCoupon.noOperationId": "此浏览器无法生成兑换 ID，因此无法在此兑换。",
+  "grokCoupon.unknownOutcome": "兑换未及时返回结果，因此结果未知。请重新读取账号，确认该券是否已被使用。",
+  "grokCoupon.checkResult": "重新读取账号",
+  "grokCoupon.checking": "正在重新读取…",
+  "grokCoupon.consumedElsewhere": "此账号中已没有该券，说明兑换已成功。",
+  "grokCoupon.unresolved": "该券仍在列表中。上游兑换可能仍在进行 — 请一分钟后再重新读取，再使用另一张券。",
+
   // api access page
   "api.title": "API 访问",
   "api.subtitle": "用生成的 API 密钥从外部应用访问 opencodex 代理。认证使用 {authHeader} 请求头；各端点接受哪些请求头见下表。",
@@ -1609,13 +1652,17 @@ export const zh: Record<TKey, string> = {
   "api.clientConfig.clientHermes": "Hermes",
   "api.clientConfig.clientOpenclaw": "OpenClaw",
   "api.clientConfig.clientKimi": "Kimi Code",
-  "api.clientConfig.clientGajae": "Gajae Code",
+  "api.clientConfig.clientGajae": "gjc",
   "api.clientConfig.clientDsh": "DeepSeek Harness (DSH)",
   "api.clientConfig.clientMcode": "MiniMax Code",
   "api.clientConfig.clientZcode": "ZCode",
   "api.clientConfig.clientPrime": "Prime Agent",
   "api.clientConfig.clientAside": "Aside",
   "api.clientConfig.clientRaycast": "Raycast",
+  "api.clientConfig.clientOmo": "omo",
+  "api.clientConfig.clientCline": "Cline CLI",
+  "api.clientConfig.clineBundle": "这是两个文件的数据包，不是 Cline 设置文件。将 settings 合并到 providers.json，将 catalog 合并到同目录的 models.json。使用集成开关可在写入前备份。",
+  "api.clientConfig.clineDownloaded": "已下载 {filename}，设置尚未更改。settings 和 catalog 应分别保存到两个 Cline 文件。",
   "api.clientConfig.copy": "复制配置",
   "api.clientConfig.download": "下载",
   "api.clientConfig.loading": "正在生成客户端配置…",
@@ -1916,7 +1963,10 @@ export const zh: Record<TKey, string> = {
   "modal.freeTierDefault": "无需 API 密钥，开箱即用。",
   "modal.tab.accounts": "账户",
   "modal.tab.free": "免费",
+  "modal.tab.local": "本地",
   "modal.tab.paid": "付费",
+  "modal.noteMore": "查看完整说明",
+  "modal.searchResults": "在 {tiers} 中找到 {count} 个",
   "modal.accountsHint": "在此登录 ChatGPT/Codex、OAuth 与 API 密钥账户。OpenAI 为内置提供商 — 请登录，无需再次添加。",
   "modal.accountsCodexAuthLink": "Codex 认证",
   "modal.notListed": "没有你要的提供商？添加自定义",
diff --git a/gui/src/pages/Combos.tsx b/gui/src/pages/Combos.tsx
index ca05ca8fd5..18b997a4b5 100644
--- a/gui/src/pages/Combos.tsx
+++ b/gui/src/pages/Combos.tsx
@@ -5,6 +5,7 @@ import {
   comboModelId,
   parseComboList,
   providerQuotaStatesFromReports,
+  nextProviderQuotaStateExpiration,
   toPutBody,
 } from "../combo-workspace-data";
 import { hideRedundantChatGptForwardProviders } from "../provider-workspace/catalog";
@@ -220,10 +221,12 @@ export default function Combos({
   );
   const { state } = resource;
 
+  const [quotaNow, setQuotaClock] = useState(() => Date.now());
   const loadProviderQuotas = useCallback(async (signal?: AbortSignal): Promise<ProviderQuotasDto> => {
     const response = await fetch(`${apiBase}/api/provider-quotas`, { signal });
     if (!response.ok) throw new Error("combo quota load failed");
     const payload = await response.json() as unknown;
+    if (!signal?.aborted) setQuotaClock(Date.now());
     return payload && typeof payload === "object" && !Array.isArray(payload)
       ? payload as ProviderQuotasDto
       : {};
@@ -239,12 +242,23 @@ export default function Combos({
       enabled: active,
     },
   );
-  const providerQuotaStates = useMemo(
-    () => quotaResource.lastAttemptOk
-      ? providerQuotaStatesFromReports(quotaResource.data?.reports)
-      : {},
-    [quotaResource.data, quotaResource.lastAttemptOk],
-  );
+  const quotaReports = active && quotaResource.lastAttemptOk ? quotaResource.data?.reports : undefined;
+  const providerQuotaStates = providerQuotaStatesFromReports(quotaReports, quotaNow);
+  const quotaExpiry = nextProviderQuotaStateExpiration(quotaReports, quotaNow);
+  useEffect(() => {
+    if (!active) return;
+    const recheck = () => setQuotaClock(Date.now());
+    // The render may cross this boundary before effects run. Keep its deadline and wake now.
+    // A new snapshot may be newer than this clock, so unknown state also gets one immediate check.
+    const timer = window.setTimeout(recheck,
+      quotaExpiry === undefined ? 0 : Math.max(0, quotaExpiry - Date.now()));
+    const onVisible = () => { if (document.visibilityState === "visible") recheck(); };
+    document.addEventListener("visibilitychange", onVisible);
+    return () => {
+      window.clearTimeout(timer);
+      document.removeEventListener("visibilitychange", onVisible);
+    };
+  }, [active, apiBase, quotaResource.data, quotaResource.lastAttemptOk, quotaExpiry]);
 
   const data = state.data ?? retainedData ?? undefined;
   const combos = data?.combos ?? [];
@@ -361,7 +375,7 @@ export default function Combos({
           models={models}
           cataloguedComboIds={cataloguedComboIds}
           loading={false}
-          onRefresh={() => resource.refresh()}
+          onRefresh={() => { resource.refresh(); quotaResource.refresh(); }}
           onSave={saveCombo}
           onRemove={removeCombo}
           onAdd={() => setAdding(true)}
diff --git a/gui/src/pages/api-keys-panels.tsx b/gui/src/pages/api-keys-panels.tsx
index 54dce72098..661dd006e4 100644
--- a/gui/src/pages/api-keys-panels.tsx
+++ b/gui/src/pages/api-keys-panels.tsx
@@ -319,7 +319,7 @@ export function ApiKeysUsagePanel({
   -H "x-opencodex-api-key: ocx_YOUR_KEY_HERE" \\
   -H "Content-Type: application/json" \\
   -d '{
-    "model": "gpt-5.4",
+    "model": "gpt-5.6-luna",
     "messages": [{"role": "user", "content": ${sampleInput}}]
   }'`;
 
@@ -327,7 +327,7 @@ export function ApiKeysUsagePanel({
   -H "x-opencodex-api-key: ocx_YOUR_KEY_HERE" \\
   -H "Content-Type: application/json" \\
   -d '{
-    "model": "gpt-5.4",
+    "model": "gpt-5.6-luna",
     "input": ${sampleInput}
   }'`;
 
diff --git a/gui/src/pages/dashboard-overview-sections.tsx b/gui/src/pages/dashboard-overview-sections.tsx
index c71687acb9..a62bc47eea 100644
--- a/gui/src/pages/dashboard-overview-sections.tsx
+++ b/gui/src/pages/dashboard-overview-sections.tsx
@@ -444,7 +444,7 @@ export function DashboardSidecarPanels({ d }: { d: Dash }) {
     shadowCall, shadowCallSaving, shadowCallHelpTriggerRef, shadowCallHelpOpen, setShadowCallHelpOpen, saveShadowCall,
   } = d;
   const visionEnabled = sidecar?.vision.enabled !== false;
-  const visionModel = visionEnabled ? (sidecar?.vision.model ?? "gpt-5.4-mini") : "";
+  const visionModel = visionEnabled ? (sidecar?.vision.model ?? "gpt-5.6-luna") : "";
   const persistedVisionReasoning = sidecar?.vision.reasoning ?? "low";
   const visionLadder = visionReasoningLadder(models, visionModel);
   const visionReasoning = clampVisionReasoningToLadder(visionLadder, persistedVisionReasoning);
diff --git a/gui/src/pages/integrations/FileIntegrationPage.tsx b/gui/src/pages/integrations/FileIntegrationPage.tsx
index 2eef2c5cf0..b1f8ec3737 100644
--- a/gui/src/pages/integrations/FileIntegrationPage.tsx
+++ b/gui/src/pages/integrations/FileIntegrationPage.tsx
@@ -59,6 +59,8 @@ const SEMANTICS_KEY: Record<FileIntegrationClientId, TKey> = {
   prime: "integrations.semantics.prime",
   aside: "integrations.semantics.aside",
   raycast: "integrations.semantics.raycast",
+  omo: "integrations.semantics.omo",
+  cline: "integrations.semantics.cline",
 };
 
 const TAB_LABEL_KEY: Record<FileIntegrationClientId, TKey> = {
@@ -75,6 +77,8 @@ const TAB_LABEL_KEY: Record<FileIntegrationClientId, TKey> = {
   prime: "integrations.tab.prime",
   aside: "integrations.tab.aside",
   raycast: "integrations.tab.raycast",
+  omo: "integrations.tab.omo",
+  cline: "integrations.tab.cline",
 };
 
 export default function FileIntegrationPage({
diff --git a/gui/src/pages/integrations/integration-api.ts b/gui/src/pages/integrations/integration-api.ts
index 85ffdc7be4..ad50a781fd 100644
--- a/gui/src/pages/integrations/integration-api.ts
+++ b/gui/src/pages/integrations/integration-api.ts
@@ -15,6 +15,8 @@ export const FILE_INTEGRATION_CLIENTS = [
   "prime",
   "aside",
   "raycast",
+  "omo",
+  "cline",
 ] as const;
 
 export type FileIntegrationClientId = (typeof FILE_INTEGRATION_CLIENTS)[number];
diff --git a/gui/src/pages/integrations/integration-tabs.ts b/gui/src/pages/integrations/integration-tabs.ts
index 99502bde87..a1810763dd 100644
--- a/gui/src/pages/integrations/integration-tabs.ts
+++ b/gui/src/pages/integrations/integration-tabs.ts
@@ -47,6 +47,8 @@ export const TABS: readonly TabDefinition[] = [
   { id: "prime", hash: "integrations/prime", labelKey: "integrations.tab.prime" },
   { id: "aside", hash: "integrations/aside", labelKey: "integrations.tab.aside" },
   { id: "raycast", hash: "integrations/raycast", labelKey: "integrations.tab.raycast" },
+  { id: "omo", hash: "integrations/omo", labelKey: "integrations.tab.omo" },
+  { id: "cline", hash: "integrations/cline", labelKey: "integrations.tab.cline" },
 ] as const;
 
 export const FILE_CLIENTS = new Set<FileIntegrationClientId>([
@@ -63,4 +65,6 @@ export const FILE_CLIENTS = new Set<FileIntegrationClientId>([
   "prime",
   "aside",
   "raycast",
+  "omo",
+  "cline",
 ]);
diff --git a/gui/src/pages/integrations/overview-clients.ts b/gui/src/pages/integrations/overview-clients.ts
index 7932cf5648..d54d99d005 100644
--- a/gui/src/pages/integrations/overview-clients.ts
+++ b/gui/src/pages/integrations/overview-clients.ts
@@ -153,6 +153,8 @@ const FILE_LABEL_KEY: Record<FileIntegrationClientId, TKey> = {
   prime: "integrations.tab.prime",
   aside: "integrations.tab.aside",
   raycast: "integrations.tab.raycast",
+  omo: "integrations.tab.omo",
+  cline: "integrations.tab.cline",
 };
 
 /** A file client's block is in the file for both `current` and `stale`. */
diff --git a/gui/src/pages/providers-shared.ts b/gui/src/pages/providers-shared.ts
index 231305c14d..536e95091e 100644
--- a/gui/src/pages/providers-shared.ts
+++ b/gui/src/pages/providers-shared.ts
@@ -54,6 +54,10 @@ const OAUTH_LABELS: Record<string, string> = {
   "google-antigravity": "Google Antigravity",
   "github-copilot": "GitHub Copilot",
   cursor: "Cursor",
+  // Accounts rows title through this map, not `formatProviderDisplayName`.
+  // Without an entry the row reads its raw id.
+  devin: "Devin",
+  "devin-cli": "Devin CLI",
 };
 
 export const oauthLabel = (id: string) => OAUTH_LABELS[id] ?? id;
diff --git a/gui/src/pool-settings.ts b/gui/src/pool-settings.ts
new file mode 100644
index 0000000000..dff50736a8
--- /dev/null
+++ b/gui/src/pool-settings.ts
@@ -0,0 +1,148 @@
+/**
+ * One GUI client for the unified pool-settings contract.
+ *
+ * Before this, three fetchers spoke three shapes for the same two fields: the Codex threshold
+ * write, the Codex strategy write with `accountPool`-prefixed response keys, and the Anthropic
+ * pool read/write. `/api/pool/settings` answers identically for every kind, so the transport
+ * collapses to this module and the components above keep their own presentation.
+ */
+import {
+  normalizeAccountPoolQuotaWindow,
+  normalizeAccountPoolStickyLimit,
+  normalizeAccountPoolStrategy,
+  type AccountPoolQuotaWindow,
+  type AccountPoolStrategy,
+} from "./account-pool-strategy";
+
+/** The Codex pool is addressed by its provider id like any other kind. */
+export const CODEX_POOL_PROVIDER = "openai";
+
+export type PoolSettingsFetch = (input: string, init?: RequestInit) => Promise<Response>;
+
+export interface PoolSettings {
+  provider: string;
+  kind: "codex" | "anthropic" | "generic";
+  supported: string[];
+  enabled: boolean | null;
+  enabledEffective: boolean;
+  strategy: AccountPoolStrategy;
+  stickyLimit: number;
+  autoSwitchThreshold: number | null;
+  quotaWindow: AccountPoolQuotaWindow | null;
+}
+
+/** Fields a caller may write. Named in GUI terms; mapped to the wire below. */
+export interface PoolSettingsWrite {
+  enabled?: boolean;
+  strategy?: AccountPoolStrategy;
+  stickyLimit?: number;
+  /** GUI callers say "threshold"; the contract says autoSwitchThreshold. */
+  threshold?: number;
+  quotaWindow?: AccountPoolQuotaWindow;
+}
+
+function toDto(json: unknown, provider: string, fallback?: PoolSettingsWrite): PoolSettings {
+  const raw = (json ?? {}) as Record<string, unknown>;
+  const threshold = raw.autoSwitchThreshold ?? fallback?.threshold;
+  return {
+    provider,
+    kind: raw.kind === "codex" || raw.kind === "anthropic" ? raw.kind : "generic",
+    supported: Array.isArray(raw.supported) ? raw.supported.filter((f): f is string => typeof f === "string") : [],
+    enabled: typeof raw.enabled === "boolean" ? raw.enabled : null,
+    enabledEffective: raw.enabledEffective === true,
+    // Fall back to what was asked for when the response omits a field. A management write may
+    // answer 204, and reporting the normalizer default there would silently show the operator
+    // a different value than the one they just saved.
+    strategy: normalizeAccountPoolStrategy(raw.strategy ?? fallback?.strategy),
+    stickyLimit: normalizeAccountPoolStickyLimit(raw.stickyLimit ?? fallback?.stickyLimit),
+    autoSwitchThreshold: typeof threshold === "number" ? threshold : null,
+    quotaWindow: (raw.quotaWindow ?? fallback?.quotaWindow) === undefined || raw.quotaWindow === null
+      ? null
+      : normalizeAccountPoolQuotaWindow(raw.quotaWindow ?? fallback?.quotaWindow),
+  };
+}
+
+/**
+ * Map GUI field names onto the wire, and ALWAYS send `provider`.
+ *
+ * This is not ceremony. The route ignores a field it does not know, so a body that still said
+ * `threshold` would return 200 and write nothing -- and `putAutoSwitchThreshold` only inspects
+ * `response.ok`, so every save would report success while changing no setting. Silent success
+ * is worse than a visible failure, which is why the mapping lives here rather than at each
+ * call site where one of three could forget it.
+ */
+export function poolSettingsRequestBody(provider: string, fields: PoolSettingsWrite): Record<string, unknown> {
+  return {
+    provider,
+    ...(fields.enabled !== undefined ? { enabled: fields.enabled } : {}),
+    ...(fields.strategy !== undefined ? { strategy: fields.strategy } : {}),
+    ...(fields.stickyLimit !== undefined ? { stickyLimit: fields.stickyLimit } : {}),
+    ...(fields.threshold !== undefined ? { autoSwitchThreshold: fields.threshold } : {}),
+    ...(fields.quotaWindow !== undefined ? { quotaWindow: fields.quotaWindow } : {}),
+  };
+}
+
+export async function getPoolSettings(
+  apiBase: string,
+  provider: string,
+  fetchImpl: PoolSettingsFetch = (input, init) => fetch(input, init),
+  init?: RequestInit,
+): Promise<PoolSettings | null> {
+  try {
+    const response = await fetchImpl(`${apiBase}/api/pool/settings?provider=${encodeURIComponent(provider)}`, init);
+    if (!response.ok) return null;
+    // No empty-body tolerance on the READ. `toDto` fills defaults, so `{}` would render as a
+    // disabled pool with default values and the panel would treat that as a loaded state --
+    // letting the next save overwrite the real configuration from fabricated input. A read
+    // with no parseable body is a failed read. The write below is the opposite case: there,
+    // an empty 2xx is a real success and the fallback is the settings just sent.
+    return toDto(await response.json(), provider);
+  } catch {
+    return null;
+  }
+}
+
+export async function putPoolSettings(
+  apiBase: string,
+  provider: string,
+  fields: PoolSettingsWrite,
+  fetchImpl: PoolSettingsFetch = (input, init) => fetch(input, init),
+  init?: RequestInit,
+): Promise<PoolSettings | null> {
+  try {
+    const response = await fetchImpl(`${apiBase}/api/pool/settings`, {
+      ...init,
+      method: "PUT",
+      headers: { "Content-Type": "application/json", ...(init?.headers ?? {}) },
+      body: JSON.stringify(poolSettingsRequestBody(provider, fields)),
+    });
+    if (!response.ok) return null;
+    // A 2xx with no parseable body is still a successful write; the old per-route clients
+    // only inspected response.ok and a management PUT may answer 204.
+    return toDto(await response.json().catch(() => ({})), provider, fields);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Codex strategy/sticky write, kept as a named helper because three call sites use it.
+ *
+ * It lives HERE rather than in `account-pool-strategy.ts` for a structural reason: that module
+ * owns the value normalizers this one imports, so putting the transport there too would make the
+ * two modules import each other. The first draft papered over that with a dynamic import and the
+ * bundler called it out as ineffective, which was the cycle telling on itself.
+ */
+export async function putCodexPoolStrategy(
+  apiBase: string,
+  body: { strategy?: AccountPoolStrategy; stickyLimit?: number },
+  fetchImpl: PoolSettingsFetch = (input, init) => fetch(input, init),
+): Promise<{ ok: true; strategy: AccountPoolStrategy; stickyLimit: number } | { ok: false }> {
+  if (body.strategy === undefined && body.stickyLimit === undefined) return { ok: false };
+  const settings = await putPoolSettings(apiBase, CODEX_POOL_PROVIDER, {
+    strategy: body.strategy,
+    stickyLimit: body.stickyLimit,
+  }, fetchImpl);
+  if (!settings) return { ok: false };
+  return { ok: true, strategy: settings.strategy, stickyLimit: settings.stickyLimit };
+}
diff --git a/gui/src/provider-icons.ts b/gui/src/provider-icons.ts
index 99f46a93c4..606723a368 100644
--- a/gui/src/provider-icons.ts
+++ b/gui/src/provider-icons.ts
@@ -13,6 +13,15 @@ const PROVIDER_ICON_ALIASES: Record<string, string> = {
   commandcode: "commandcode-color.svg",
   cursor: "cursor-color.svg",
   deepseek: "deepseek-color.svg",
+  /*
+   * One mark for both Devin providers. `devin` is Cognition's cloud, reached
+   * through the Windsurf sign-in, and `devin-cli` drives the installed Devin
+   * CLI; they are two transports into the same product, the meta-model/meta-muse
+   * shape. Windsurf still publishes its own `W` app icon, but showing it next
+   * to a row labelled Cognition would name the retired brand.
+   */
+  devin: "devin.svg",
+  "devin-cli": "devin.svg",
   firepass: "firepass-color.svg",
   fireworks: "fireworks-color.svg",
   github: "github-copilot-color.svg",
@@ -124,6 +133,12 @@ const PROVIDER_DISPLAY_NAMES: Record<string, string> = {
   xiaomi: "Xiaomi",
   cursor: "Cursor",
   deepseek: "DeepSeek",
+  // "Devin", not the registry's "Cognition (Devin/Windsurf)". This label sits in
+  // a narrow provider rail beside one-word names like Cursor and Kimi, and the
+  // long form is the registry's disambiguation for an add-provider list, not a
+  // name to read at a glance.
+  devin: "Devin",
+  "devin-cli": "Devin CLI",
   github: "GitHub",
   "github-copilot": "GitHub Copilot",
   "gitlab-duo": "GitLab Duo",
diff --git a/gui/src/styles/provider-catalog.css b/gui/src/styles/provider-catalog.css
index 6d87c59c5b..53460445f6 100644
--- a/gui/src/styles/provider-catalog.css
+++ b/gui/src/styles/provider-catalog.css
@@ -8,6 +8,7 @@
 
 .provider-catalog-tabs {
   display: flex;
+  flex-wrap: wrap;
   gap: 4px;
   border-bottom: 1px solid var(--border);
 }
@@ -28,6 +29,85 @@
   border-bottom-color: var(--accent);
 }
 
+/* Search mode: the strip stops being a tablist and becomes jump chips with counts, so
+   it loses the selected-underline vocabulary and gains a count badge. A chip with no
+   matches is disabled rather than hidden, so the strip does not reflow under the
+   pointer on every keystroke. */
+.provider-catalog-tabs--chips {
+  border-bottom: none;
+  flex-wrap: wrap;
+}
+
+.provider-catalog-chip {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding: 5px 10px;
+  border: 1px solid var(--border);
+  border-radius: 999px;
+}
+
+.provider-catalog-chip:not(:disabled):hover {
+  color: var(--text);
+  border-color: var(--accent-ring);
+}
+
+.provider-catalog-chip:disabled {
+  opacity: 0.45;
+  cursor: default;
+}
+
+.provider-catalog-chip-count {
+  font-variant-numeric: tabular-nums;
+  font-size: var(--text-label);
+  color: var(--muted);
+}
+
+/* Group heading inside the result list: a small caps label with a hairline running out
+   to the right, the way a dense list separates sections without adding another slab of
+   chrome. It scrolls with the content rather than sticking — `.modal-card` is a
+   translucent glass panel, so any opaque sticky bar shows a seam against it, and with
+   four short groups in a 360px list the chips above are the index anyway. */
+.provider-catalog-group-head {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin: 0;
+  padding: 12px 2px 2px;
+  color: var(--muted);
+  font-size: 11px;
+  font-weight: var(--weight-semibold);
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.provider-catalog-group-head:first-child {
+  padding-top: 2px;
+}
+
+.provider-catalog-group-head::after {
+  content: "";
+  flex: 1 1 auto;
+  height: 1px;
+  background: var(--border);
+}
+
+.provider-catalog-group-head:focus-visible {
+  outline: 2px solid var(--accent-ring);
+  outline-offset: 3px;
+  border-radius: var(--radius-xs);
+}
+
+/* The count is data, not a label: tabular figures, no small caps, and it sits before
+   the rule so the eye reads "FREE 1 ————" as one unit. */
+.provider-catalog-group-count {
+  font-variant-numeric: tabular-nums;
+  font-weight: var(--weight-normal, 400);
+  letter-spacing: 0;
+  text-transform: none;
+  opacity: 0.75;
+}
+
 .provider-catalog-accounts-hint {
   padding: 2px 2px 0;
 }
@@ -55,6 +135,107 @@
   padding: 8px;
 }
 
+/* A preset row and its note-reveal control. The control has to be a SIBLING of the row
+   button rather than a child, because the row is itself a <button> and nesting one is
+   invalid HTML the parser is free to hoist out. The wrapper is what holds the two
+   together as one list item. */
+.provider-catalog-row-wrap {
+  display: flex;
+  flex-direction: column;
+  align-items: stretch;
+}
+
+/* Merge the two children into one visual row: the row button loses its bottom corners
+   and border, the reveal strip grows the matching bottom corners, and they share the
+   raised surface. Without this the control floats on the modal background between two
+   rows and reads as though it belongs to the next provider. */
+.provider-catalog-row-wrap:has(.provider-catalog-note-more) .list-row {
+  border-bottom-left-radius: 0;
+  border-bottom-right-radius: 0;
+  border-bottom: none;
+  padding-bottom: 8px;
+}
+
+/* Two-line clamp on the note. A handful of catalog notes are paragraphs — opencode-free
+   is ~1100 characters — and unclamped, one of them fills the whole 360px scroller and
+   the row it belongs to becomes the only row anyone can see. Scoped through the wrapper
+   so account rows keep their existing single-line ellipsis instead. */
+.provider-catalog-row-wrap .list-row .sub {
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+
+/* Qualified with `.link-btn` on purpose, and it is not redundant: this file is
+   @imported at the TOP of styles.css while `.link-btn` is declared far below it, so a
+   bare `.provider-catalog-note-more` loses background, border, padding and font-size to
+   the later equal-specificity rule and the control renders as a full-width underlined
+   link floating between two rows instead of the bottom edge of its own row. Same trap
+   already documented above for `.list-row.provider-catalog-account-row--waiting`. */
+.link-btn.provider-catalog-note-more {
+  align-self: stretch;
+  text-align: right;
+  padding: 0 13px 9px;
+  font-size: var(--text-label);
+  color: var(--muted);
+  text-decoration: none;
+  border: 1px solid var(--border);
+  border-top: none;
+  border-bottom-left-radius: var(--radius-sm);
+  border-bottom-right-radius: var(--radius-sm);
+  background: var(--raised);
+}
+
+.link-btn.provider-catalog-note-more:hover {
+  color: var(--text);
+  text-decoration: underline;
+}
+
+/* The row and its reveal strip highlight together, because they are one row. */
+.provider-catalog-row-wrap:hover .link-btn.provider-catalog-note-more,
+.provider-catalog-row-wrap:hover .list-row {
+  background: var(--raised-hover);
+}
+
+.provider-catalog-row-wrap:hover .list-row {
+  border-color: var(--accent-ring);
+}
+
+.provider-catalog-row-wrap:hover .link-btn.provider-catalog-note-more {
+  border-color: var(--accent-ring);
+}
+
+/* The full-note popup: a native <dialog> sibling of the add-provider overlay. */
+.provider-note-card {
+  max-width: 560px;
+}
+
+.provider-note-title {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  min-width: 0;
+}
+
+.provider-note-body {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 8px;
+  margin-top: 12px;
+}
+
+/* The note is the reason this popup exists, so it scrolls here rather than being
+   truncated a second time. */
+.provider-note-text {
+  margin: 0;
+  white-space: pre-wrap;
+  max-height: 55vh;
+  overflow-y: auto;
+}
+
 .provider-catalog-account-row .sub {
   overflow: hidden;
   text-overflow: ellipsis;
diff --git a/gui/tests/account-pool-strategy.test.tsx b/gui/tests/account-pool-strategy.test.tsx
index 856c44af8c..5f98969f99 100644
--- a/gui/tests/account-pool-strategy.test.tsx
+++ b/gui/tests/account-pool-strategy.test.tsx
@@ -1,3 +1,4 @@
+import { putCodexPoolStrategy } from "../src/pool-settings";
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { Window } from "happy-dom";
 import { act } from "react";
@@ -9,7 +10,7 @@ import {
   normalizeAccountPoolStickyLimit,
   normalizeAccountPoolStrategy,
   parseAccountPoolStickyLimitDraft,
-  putCodexPoolStrategy,
+  
 } from "../src/account-pool-strategy";
 import AccountPoolStrategyControls from "../src/components/AccountPoolStrategyControls";
 import CodexPoolStrategySetting from "../src/components/CodexPoolStrategySetting";
@@ -133,9 +134,11 @@ describe("account pool strategy helpers", () => {
     );
     expect(result).toEqual({ ok: true, strategy: "round-robin", stickyLimit: 3 });
     expect(calls).toHaveLength(1);
-    expect(calls[0]!.url).toBe("http://proxy/api/codex-auth/pool-strategy");
+    expect(calls[0]!.url).toBe("http://proxy/api/pool/settings");
     expect(calls[0]!.init.method).toBe("PUT");
     expect(JSON.parse(String(calls[0]!.init.body))).toEqual({
+      // The Codex pool is addressed by provider id like every other kind now.
+      provider: "openai",
       strategy: "round-robin",
       stickyLimit: 3,
     });
@@ -281,12 +284,12 @@ describe("CodexPoolStrategySetting optimistic strategy select", () => {
       if (url.endsWith("/api/codex-auth/active") && (!init || init.method === undefined)) {
         return active.promise;
       }
-      if (url.endsWith("/api/codex-auth/pool-strategy") && init?.method === "PUT") {
+      if (url.endsWith("/api/pool/settings") && init?.method === "PUT") {
         puts.push(init.body ? JSON.parse(String(init.body)) : null);
         return new Response(JSON.stringify({
           ok: true,
-          accountPoolStrategy: "round-robin",
-          accountPoolStickyLimit: 1,
+          strategy: "round-robin",
+          stickyLimit: 1,
         }), { status: 200 });
       }
       throw new Error(`unexpected fetch: ${url} ${init?.method ?? "GET"}`);
@@ -331,7 +334,7 @@ describe("CodexPoolStrategySetting optimistic strategy select", () => {
           accountPoolStickyLimit: 1,
         }), { status: 200 });
       }
-      if (url.endsWith("/api/codex-auth/pool-strategy") && init?.method === "PUT") {
+      if (url.endsWith("/api/pool/settings") && init?.method === "PUT") {
         return put.promise;
       }
       throw new Error(`unexpected fetch: ${url} ${init?.method ?? "GET"}`);
@@ -380,7 +383,7 @@ describe("CodexPoolStrategySetting optimistic strategy select", () => {
           accountPoolStickyLimit: 1,
         }), { status: 200 });
       }
-      if (url.endsWith("/api/codex-auth/pool-strategy") && init?.method === "PUT") {
+      if (url.endsWith("/api/pool/settings") && init?.method === "PUT") {
         return new Response("fail", { status: 500 });
       }
       throw new Error(`unexpected fetch: ${url} ${init?.method ?? "GET"}`);
@@ -416,7 +419,7 @@ describe("CodexPoolStrategySetting optimistic strategy select", () => {
 
     globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
       const url = String(input);
-      if (url.endsWith("/api/codex-auth/pool-strategy") && init?.method === "PUT") {
+      if (url.endsWith("/api/pool/settings") && init?.method === "PUT") {
         return put.promise;
       }
       throw new Error(`unexpected fetch: ${url} ${init?.method ?? "GET"}`);
diff --git a/gui/tests/anthropic-pool-quota-window.test.tsx b/gui/tests/anthropic-pool-quota-window.test.tsx
index 03043813d8..c8b2a86c8f 100644
--- a/gui/tests/anthropic-pool-quota-window.test.tsx
+++ b/gui/tests/anthropic-pool-quota-window.test.tsx
@@ -62,7 +62,7 @@ function stubPool(initial: PoolPayload): Record<string, unknown>[] {
   const puts: Record<string, unknown>[] = [];
   globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
     const url = String(input);
-    if (url.includes("/api/oauth/accounts/pool") && init?.method === "PUT") {
+    if (url.includes("/api/pool/settings") && init?.method === "PUT") {
       const body = init.body ? JSON.parse(String(init.body)) as Record<string, unknown> : {};
       puts.push(body);
       return new Response(JSON.stringify({
@@ -71,7 +71,7 @@ function stubPool(initial: PoolPayload): Record<string, unknown>[] {
         quotaWindow: body.quotaWindow,
       }), { status: 200 });
     }
-    if (url.includes("/api/oauth/accounts/pool")) {
+    if (url.includes("/api/pool/settings")) {
       return new Response(JSON.stringify(initial), { status: 200 });
     }
     throw new Error(`unexpected fetch: ${url} ${init?.method ?? "GET"}`);
diff --git a/gui/tests/api-access-models.test.ts b/gui/tests/api-access-models.test.ts
index 8fb404ebcb..8fe582a117 100644
--- a/gui/tests/api-access-models.test.ts
+++ b/gui/tests/api-access-models.test.ts
@@ -6,9 +6,9 @@ import {
 
 describe("classifyExternalModel", () => {
   test("keeps bare native OpenAI ids and marks them native via owned_by", () => {
-    expect(classifyExternalModel({ id: "gpt-5.4", owned_by: "openai" })).toEqual({
-      id: "gpt-5.4",
-      displayName: "gpt-5.4",
+    expect(classifyExternalModel({ id: "gpt-5.5", owned_by: "openai" })).toEqual({
+      id: "gpt-5.5",
+      displayName: "gpt-5.5",
       provider: "openai",
       native: true,
       custom: false,
diff --git a/gui/tests/apikeys-actions.test.tsx b/gui/tests/apikeys-actions.test.tsx
index ae3bffecef..02015a3b1d 100644
--- a/gui/tests/apikeys-actions.test.tsx
+++ b/gui/tests/apikeys-actions.test.tsx
@@ -237,7 +237,7 @@ test("a failed delete keeps the detail pane open", async () => {
 
 test("without a fresh key the protocol chips are disabled, not silently passing", async () => {
   const container = await mount({
-    filteredModels: [{ id: "gpt-5.4", displayName: "gpt-5.4", provider: "openai", native: true }],
+    filteredModels: [{ id: "gpt-5.5", displayName: "gpt-5.5", provider: "openai", native: true }],
     modelCount: 1,
     canTestModels: false,
   });
@@ -286,10 +286,10 @@ test("rotation start, one-time secret, commit, and abort stay explicit", async (
 
 test("a protocol result belongs to its own chip", async () => {
   const container = await mount({
-    filteredModels: [{ id: "gpt-5.4", displayName: "gpt-5.4", provider: "openai", native: true }],
+    filteredModels: [{ id: "gpt-5.5", displayName: "gpt-5.5", provider: "openai", native: true }],
     modelCount: 1,
     canTestModels: true,
-    modelTests: { "gpt-5.4": { chat: { state: "error", detail: "boom" } } },
+    modelTests: { "gpt-5.5": { chat: { state: "error", detail: "boom" } } },
   });
   const notes = [...container.querySelectorAll(".api-test-note")];
   // Exactly one result rendered, announced, and attached to the chat chip only.
diff --git a/gui/tests/apikeys-model-test-wire.test.tsx b/gui/tests/apikeys-model-test-wire.test.tsx
index 943d4d6f3d..c62cca7e20 100644
--- a/gui/tests/apikeys-model-test-wire.test.tsx
+++ b/gui/tests/apikeys-model-test-wire.test.tsx
@@ -89,7 +89,7 @@ function installFetch(sent: SentRequest[], dataPlaneStatus = 200): void {
     const url = String(input);
     const method = (init?.method ?? "GET").toUpperCase();
     if (url.endsWith("/v1/models") && method === "GET") {
-      return Response.json({ data: [{ id: "gpt-5.4", owned_by: "openai" }] });
+      return Response.json({ data: [{ id: "gpt-5.5", owned_by: "openai" }] });
     }
     if (url.endsWith("/api/keys") && method === "GET") return Response.json(KEYS_OK);
     if (url.endsWith("/api/keys") && method === "POST") return Response.json({ key: ONE_TIME_KEY });
@@ -163,11 +163,11 @@ test("each protocol chip posts its own endpoint and body, carrying the one-time
     // Each protocol speaks its own wire. A chat body posted at /v1/responses
     // would be rejected for its shape, not for the key, and the green chip
     // would then be lying about what it proved.
-    expect(sent[0]!.body).toMatchObject({ model: "gpt-5.4", input: "ping", stream: false });
+    expect(sent[0]!.body).toMatchObject({ model: "gpt-5.5", input: "ping", stream: false });
     expect(sent[0]!.body).not.toHaveProperty("messages");
-    expect(sent[1]!.body).toMatchObject({ model: "gpt-5.4", max_tokens: 1, stream: false });
+    expect(sent[1]!.body).toMatchObject({ model: "gpt-5.5", max_tokens: 1, stream: false });
     expect(sent[1]!.body).toHaveProperty("messages");
-    expect(sent[2]!.body).toMatchObject({ model: "gpt-5.4", max_tokens: 1 });
+    expect(sent[2]!.body).toMatchObject({ model: "gpt-5.5", max_tokens: 1 });
     expect(sent[2]!.body).not.toHaveProperty("stream");
 
     // The dedicated header is the only one every data-plane endpoint accepts;
diff --git a/gui/tests/apikeys-models-states.test.tsx b/gui/tests/apikeys-models-states.test.tsx
index ef98e24fa6..017dba1a71 100644
--- a/gui/tests/apikeys-models-states.test.tsx
+++ b/gui/tests/apikeys-models-states.test.tsx
@@ -135,11 +135,11 @@ test("an empty catalog says the catalog is empty, with no query in the sentence"
 test("a query matching nothing names the query, and does not claim the catalog is empty", async () => {
   const counter = { gets: 0 };
   installFetch(() => Response.json({
-    data: [{ id: "gpt-5.4", owned_by: "openai" }, { id: "claude/opus-4-6", owned_by: "anthropic" }],
+    data: [{ id: "gpt-5.5", owned_by: "openai" }, { id: "claude/opus-4-6", owned_by: "anthropic" }],
   }), counter);
   const { container, root } = await mountPage();
   try {
-    expect(container.textContent).toContain("gpt-5.4");
+    expect(container.textContent).toContain("gpt-5.5");
     await typeQuery(container, "nothing-matches-this");
     await tick();
 
@@ -158,7 +158,7 @@ test("a failed cold load offers a retry that really refetches, and no false empt
   installFetch(
     () => (fail
       ? new Response("upstream unavailable", { status: 503 })
-      : Response.json({ data: [{ id: "gpt-5.4", owned_by: "openai" }] })),
+      : Response.json({ data: [{ id: "gpt-5.5", owned_by: "openai" }] })),
     counter,
   );
   const { container, root } = await mountPage();
@@ -176,7 +176,7 @@ test("a failed cold load offers a retry that really refetches, and no false empt
     await tick();
 
     expect(counter.gets).toBe(2);
-    expect(container.textContent).toContain("gpt-5.4");
+    expect(container.textContent).toContain("gpt-5.5");
     expect(container.textContent).not.toContain("Could not load the external model catalog.");
   } finally {
     await act(async () => { root.unmount(); });
diff --git a/gui/tests/client-config-panel.test.tsx b/gui/tests/client-config-panel.test.tsx
index ea8210e7e4..45f60d1207 100644
--- a/gui/tests/client-config-panel.test.tsx
+++ b/gui/tests/client-config-panel.test.tsx
@@ -40,7 +40,7 @@ const OPENCODE_ENVELOPE_BASE = {
         npm: "@ai-sdk/openai-compatible",
         name: "OpenCodex",
         options: { baseURL: "http://127.0.0.1:10100/v1", apiKey: "{env:OPENCODEX_OPENCODE_API_KEY}" },
-        models: { "gpt-5.4": { name: "gpt-5.4 (native)" } },
+        models: { "gpt-5.5": { name: "gpt-5.5 (native)" } },
       },
     },
   },
@@ -57,7 +57,7 @@ const PI_ENVELOPE_BASE = {
   format: "json",
   mediaType: "application/json",
   // Pi keys its models as an ARRAY — the shape swap is what proves a real refetch.
-  config: { providers: { opencodex: { models: [{ id: "gpt-5.4" }, { id: "claude-sonnet-4-6" }] } } },
+  config: { providers: { opencodex: { models: [{ id: "gpt-5.5" }, { id: "claude-sonnet-4-6" }] } } },
 };
 
 /**
@@ -170,12 +170,13 @@ function rowButton(container: HTMLElement, name: string, label: string): HTMLBut
     .find(el => el.textContent?.trim() === label)!;
 }
 
-test("the API download surface includes DSH, MiniMax Code, Aside and Raycast as clients", () => {
-  expect(CLIENTS).toEqual(["opencode", "pi", "omp", "hermes", "openclaw", "kimi", "gajae", "dsh", "mcode", "zcode", "prime", "aside", "raycast"]);
+test("the API download surface includes DSH, MiniMax Code, Aside, Raycast and omo as clients", () => {
+  expect(CLIENTS).toEqual(["opencode", "pi", "omp", "hermes", "openclaw", "kimi", "gajae", "dsh", "mcode", "zcode", "prime", "aside", "raycast", "omo", "cline"]);
   expect(CLIENT_LABEL_KEYS.dsh).toBe("api.clientConfig.clientDsh");
   expect(CLIENT_LABEL_KEYS.mcode).toBe("api.clientConfig.clientMcode");
   expect(CLIENT_LABEL_KEYS.zcode).toBe("api.clientConfig.clientZcode");
   expect(CLIENT_LABEL_KEYS.aside).toBe("api.clientConfig.clientAside");
+  expect(CLIENT_LABEL_KEYS.omo).toBe("api.clientConfig.clientOmo");
 });
 
 test("each row fetches its own client and its dialog renders that client's exact bytes", async () => {
@@ -219,6 +220,27 @@ test("the config bytes are not rendered at rest", async () => {
   await act(async () => { root.unmount(); });
 });
 
+test("Cline details explain the two-file bundle instead of a single-file merge", async () => {
+  const config = { settings: { version: 1, providers: {} }, catalog: { version: 1, providers: {} } };
+  const envelope = {
+    ...OPENCODE_ENVELOPE,
+    client: "cline", filename: "cline-config-bundle.json",
+    destination: "/home/dev/.cline/data/settings/providers.json", apiKeyEnv: "",
+    exportHint: "Cline CLI bundle", config, text: JSON.stringify(config),
+  };
+  stubRoute(client => Response.json(client === "cline" ? envelope : OPENCODE_ENVELOPE));
+  const { root, container } = await mountPanel({ hasKeys: false });
+  await act(async () => { rowButton(container, "Cline CLI", "Details").click(); });
+  const dialog = container.querySelector("dialog")!;
+  expect(dialog.textContent).toContain("two-file bundle");
+  expect(dialog.textContent).toContain("Stop Cline");
+  expect(dialog.textContent).not.toContain("Merge this into the destination file.");
+  expect(dialog.textContent).not.toContain("Set the key before launching");
+  expect(dialog.querySelector(".awi-clientconfig-nokey")).toBeNull();
+  expect(JSON.parse(dialog.querySelector("pre")!.textContent!)).toEqual(config);
+  await act(async () => { root.unmount(); });
+});
+
 test("clients render as rows, not a switch", async () => {
   stubRoute(client => Response.json(client === "pi" ? PI_ENVELOPE : OPENCODE_ENVELOPE));
   const { root, container } = await mountPanel();
diff --git a/gui/tests/codex-account-auto-switch.test.tsx b/gui/tests/codex-account-auto-switch.test.tsx
index c9b4f19dca..695f62bd62 100644
--- a/gui/tests/codex-account-auto-switch.test.tsx
+++ b/gui/tests/codex-account-auto-switch.test.tsx
@@ -245,9 +245,12 @@ describe("Codex account auto-switch threshold", () => {
     };
 
     expect(await putAutoSwitchThreshold("http://localhost:10100", 95, fetchImpl)).toBe(true);
-    expect(request?.input).toBe("http://localhost:10100/api/codex-auth/auto-switch");
+    expect(request?.input).toBe("http://localhost:10100/api/pool/settings");
     expect(request?.init.method).toBe("PUT");
-    expect(request?.init.body).toBe(JSON.stringify({ threshold: 95 }));
+    // Mapped, not forwarded: the contract field is autoSwitchThreshold and the provider is
+    // always sent. A body that still said `threshold` would be ignored and the save would
+    // report success while changing nothing.
+    expect(request?.init.body).toBe(JSON.stringify({ provider: "openai", autoSwitchThreshold: 95 }));
   });
 
   test("reports HTTP and network failures without accepting the write", async () => {
diff --git a/gui/tests/codex-auto-switch-controller.test.tsx b/gui/tests/codex-auto-switch-controller.test.tsx
index 287ceffdaf..126510a9a2 100644
--- a/gui/tests/codex-auto-switch-controller.test.tsx
+++ b/gui/tests/codex-auto-switch-controller.test.tsx
@@ -156,9 +156,11 @@ async function mountHarness(): Promise<Harness> {
         accountPoolStickyLimit: 1,
       });
     }
-    if (url.endsWith("/api/codex-auth/auto-switch") && method === "PUT") {
-      const body = JSON.parse(String(init?.body)) as { threshold: number };
-      writes.push(body.threshold);
+    if (url.endsWith("/api/pool/settings") && method === "PUT") {
+      // The unified contract field, not the GUI one: the client maps it, and a harness
+      // still reading `threshold` would record undefined for every save.
+      const body = JSON.parse(String(init?.body)) as { autoSwitchThreshold: number };
+      writes.push(body.autoSwitchThreshold);
       const response = putResponses.shift();
       if (!response) throw new Error("unexpected auto-switch write");
       return await response;
@@ -321,9 +323,9 @@ describe("Codex auto-switch controller interactions", () => {
           accountPoolStickyLimit: 1,
         });
       }
-      if (url.endsWith("/api/codex-auth/auto-switch") && method === "PUT") {
-        const body = JSON.parse(String(init?.body)) as { threshold: number };
-        writes.push(body.threshold);
+      if (url.endsWith("/api/pool/settings") && method === "PUT") {
+        const body = JSON.parse(String(init?.body)) as { autoSwitchThreshold: number };
+        writes.push(body.autoSwitchThreshold);
         const response = putResponses.shift();
         if (!response) throw new Error("unexpected auto-switch write");
         return await response;
diff --git a/gui/tests/combo-workspace-dirty.test.tsx b/gui/tests/combo-workspace-dirty.test.tsx
index 1f3566dbbe..c82ac799d4 100644
--- a/gui/tests/combo-workspace-dirty.test.tsx
+++ b/gui/tests/combo-workspace-dirty.test.tsx
@@ -2,7 +2,7 @@ import { afterEach, beforeEach, expect, test } from "bun:test";
 import { Window } from "happy-dom";
 import { act, StrictMode } from "react";
 import type { Root } from "react-dom/client";
-import type { ComboItem } from "../src/combo-workspace-data";
+import { type ComboItem, providerQuotaStatesFromReports } from "../src/combo-workspace-data";
 import ComboWorkspace from "../src/components/ComboWorkspace";
 import { LanguageProvider } from "../src/i18n/provider";
 
@@ -178,11 +178,14 @@ test("dirty Save disables for exhausted targets and re-enables on quota recovery
   document.body.append(container);
   const root = createRoot(container);
 
-  const render = (quotaState: "available" | "exhausted") => (
+  const now = Date.now();
+  const display = { provider: "openai", updatedAt: now,
+    quota: { updatedAt: now, customWindows: [{ label: "Search", percent: 100 }] } };
+  const render = (routingQuota?: Record<string, unknown>) => (
     <LanguageProvider>
       <ComboWorkspace
         combos={combos}
-        providerQuotaStates={{ openai: quotaState }}
+        providerQuotaStates={providerQuotaStatesFromReports([{ ...display, routingQuota }], now)}
         providers={[{ name: "openai" }]}
         models={[{ provider: "openai", id: "gpt-5" }]}
         loading={false}
@@ -197,7 +200,7 @@ test("dirty Save disables for exhausted targets and re-enables on quota recovery
     </LanguageProvider>
   );
 
-  await act(async () => { root.render(render("exhausted")); });
+  await act(async () => { root.render(render({ state: "exhausted", updatedAt: now, validUntil: now + 60_000 })); });
   await flushTimers();
   await act(async () => { railButton(container, "combo/alpha").click(); });
   await flushTimers();
@@ -208,7 +211,11 @@ test("dirty Save disables for exhausted targets and re-enables on quota recovery
   expect(container.querySelector<HTMLButtonElement>("#cwi-edit-save")!.disabled).toBe(true);
   expect(container.textContent).toContain("All enabled targets are out of quota");
 
-  await act(async () => { root.render(render("available")); });
+  await act(async () => { root.render(render()); });
+  expect(container.querySelector<HTMLButtonElement>("#cwi-edit-save")!.disabled).toBe(false);
+  expect(container.textContent).not.toContain("All enabled targets are out of quota");
+
+  await act(async () => { root.render(render({ state: "available", updatedAt: now, validUntil: now + 60_000 })); });
   expect(container.querySelector<HTMLButtonElement>("#cwi-edit-save")!.disabled).toBe(false);
   expect(container.textContent).not.toContain("All enabled targets are out of quota");
 
diff --git a/gui/tests/combo-workspace-empty.test.tsx b/gui/tests/combo-workspace-empty.test.tsx
index 4fb8416067..ba6efc49d7 100644
--- a/gui/tests/combo-workspace-empty.test.tsx
+++ b/gui/tests/combo-workspace-empty.test.tsx
@@ -5,6 +5,7 @@ import type { Root } from "react-dom/client";
 import { renderToStaticMarkup } from "react-dom/server";
 import ComboWorkspace from "../src/components/ComboWorkspace";
 import { LanguageProvider } from "../src/i18n/provider";
+import { providerQuotaStatesFromReports } from "../src/combo-workspace-data";
 
 const globals = ["document", "window", "navigator", "localStorage", "IS_REACT_ACT_ENVIRONMENT"] as const;
 let previousGlobals: Record<(typeof globals)[number], unknown>;
@@ -134,11 +135,14 @@ test("first-combo Create disables only while every usable target is known exhaus
   document.body.append(container);
   const root = createRoot(container);
 
-  const render = (quotaState: "available" | "exhausted") => (
+  const now = Date.now();
+  const display = { provider: "openai", updatedAt: now,
+    quota: { updatedAt: now, customWindows: [{ label: "Search", percent: 100 }] } };
+  const render = (routingQuota?: Record<string, unknown>) => (
     <LanguageProvider>
       <ComboWorkspace
         combos={[]}
-        providerQuotaStates={{ openai: quotaState }}
+        providerQuotaStates={providerQuotaStatesFromReports([{ ...display, routingQuota }], now)}
         providers={[{ name: "openai" }]}
         models={[{ provider: "openai", id: "gpt-5" }]}
         loading={false}
@@ -153,7 +157,7 @@ test("first-combo Create disables only while every usable target is known exhaus
     </LanguageProvider>
   );
 
-  await act(async () => { root.render(render("exhausted")); });
+  await act(async () => { root.render(render({ state: "exhausted", updatedAt: now, validUntil: now + 60_000 })); });
   await act(async () => { await new Promise((resolve) => window.setTimeout(resolve, 0)); });
 
   const providerSelect = container.querySelector<HTMLSelectElement>('select[aria-label="Provider"]')!;
@@ -167,7 +171,11 @@ test("first-combo Create disables only while every usable target is known exhaus
   expect(createButton.disabled).toBe(true);
   expect(container.textContent).toContain("All enabled targets are out of quota");
 
-  await act(async () => { root.render(render("available")); });
+  await act(async () => { root.render(render()); });
+  expect(container.querySelector<HTMLButtonElement>("#cwi-edit-create")!.disabled).toBe(false);
+  expect(container.textContent).not.toContain("All enabled targets are out of quota");
+
+  await act(async () => { root.render(render({ state: "available", updatedAt: now, validUntil: now + 60_000 })); });
   expect(container.querySelector<HTMLButtonElement>("#cwi-edit-create")!.disabled).toBe(false);
   expect(container.textContent).not.toContain("All enabled targets are out of quota");
 
diff --git a/gui/tests/fr-localization.test.ts b/gui/tests/fr-localization.test.ts
index 87250bb74b..89786fac49 100644
--- a/gui/tests/fr-localization.test.ts
+++ b/gui/tests/fr-localization.test.ts
@@ -121,6 +121,11 @@ const INTENTIONAL_ENGLISH = new Set<TKey>([
   "api.clientConfig.clientAside",
   "integrations.tab.raycast",
   "api.clientConfig.clientRaycast",
+  "integrations.tab.omo",
+  "api.clientConfig.clientOmo",
+  // Cline product name and CLI acronym are intentionally preserved.
+  "integrations.tab.cline",
+  "api.clientConfig.clientCline",
   "models.reasoningEffort.minimal",
   "models.reasoningEffort.max",
   "pws.pacingRpmUnit",
@@ -145,6 +150,9 @@ const INTENTIONAL_ENGLISH = new Set<TKey>([
   "debug.streamInjection",
   "storage.trash.col.mode",
   "modal.badge.local",
+  // The catalog tab beside the badge, and the same word in French for the same reason:
+  // a Local tab labelled anything else would not match the Local badge on its own rows.
+  "modal.tab.local",
   "modal.badge.direct",
   "pws.rail.suffixLocal",
   "pws.filterType",
diff --git a/gui/tests/grok-reset-coupons.test.tsx b/gui/tests/grok-reset-coupons.test.tsx
new file mode 100644
index 0000000000..606c184081
--- /dev/null
+++ b/gui/tests/grok-reset-coupons.test.tsx
@@ -0,0 +1,318 @@
+/**
+ * The Grok reset-coupon surface on xAI account rows.
+ *
+ * These cases exist because the dangerous paths here are the quiet ones: a
+ * replayed *failure* arrives as HTTP 200, an aborted redemption may still be
+ * executing upstream, and a per-row retry used to cancel every sibling read.
+ */
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { Window } from "happy-dom";
+import { act } from "react";
+import type { Root } from "react-dom/client";
+import ProviderAuthPanel from "../src/components/provider-workspace/ProviderAuthPanel";
+import { LanguageProvider } from "../src/i18n/provider";
+import type { WorkspaceItem } from "../src/provider-workspace/catalog";
+
+const domGlobals = ["document", "window", "navigator", "fetch", "IS_REACT_ACT_ENVIRONMENT"] as const;
+let previousDomGlobals: Record<(typeof domGlobals)[number], unknown>;
+let testWindow: Window;
+let mountedRoots: Root[];
+
+const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+const ITEM: WorkspaceItem = {
+  name: "xai",
+  adapter: "xai",
+  baseUrl: "https://api.x.ai",
+  authMode: "oauth",
+};
+
+type CouponRow = { tokenId: string; validityStart: string; validityEnd: string };
+
+type Harness = {
+  coupons: Map<string, CouponRow[]>;
+  readStatus: Map<string, number>;
+  reads: string[];
+  consumes: Array<{ accountId: string; tokenId: string; operationId: string }>;
+  consumeReply: () => Promise<Response>;
+  holdReads: boolean;
+  releaseRead: Array<() => void>;
+  inFlight: number;
+  peakInFlight: number;
+};
+
+let harness: Harness;
+
+async function flush(): Promise<void> {
+  await Promise.resolve();
+  await new Promise<void>((resolve) => testWindow.setTimeout(resolve, 0));
+  await Promise.resolve();
+}
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), { status, headers: { "Content-Type": "application/json" } });
+}
+
+function installFetch(): void {
+  globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = String(typeof input === "string" ? input : input instanceof URL ? input.href : input.url);
+    if (url.includes("/api/grok/reset-coupons/consume")) {
+      const body = JSON.parse(String(init?.body ?? "{}")) as { accountId: string; tokenId: string; operationId: string };
+      harness.consumes.push(body);
+      return harness.consumeReply();
+    }
+    if (url.includes("/api/grok/reset-coupons")) {
+      const accountId = new URL(url, "http://proxy").searchParams.get("accountId") ?? "";
+      harness.reads.push(accountId);
+      harness.inFlight += 1;
+      harness.peakInFlight = Math.max(harness.peakInFlight, harness.inFlight);
+      if (harness.holdReads) {
+        await new Promise<void>(resolve => harness.releaseRead.push(resolve));
+      }
+      harness.inFlight -= 1;
+      const status = harness.readStatus.get(accountId) ?? 200;
+      if (status !== 200) return json({ error: { code: status === 401 ? "auth_failed" : "upstream_error" } }, status);
+      return json({ accountId, tokens: harness.coupons.get(accountId) ?? [], remaining: 0 });
+    }
+    return json({});
+  }) as typeof fetch;
+}
+
+async function mountPanel(accounts: Array<Record<string, unknown>>): Promise<HTMLElement> {
+  const host = testWindow.document.createElement("div");
+  testWindow.document.body.appendChild(host as never);
+  const { createRoot } = await import("react-dom/client");
+  const handlers = {
+    onLogin: async () => {},
+    onLogout: async () => {},
+    onReauth: async () => {},
+    onSwitchAccount: async () => {},
+    onSwitchApiKey: async () => {},
+    onRemoveAccount: async () => {},
+    onRemoveApiKey: async () => {},
+    onAddApiKey: async () => {},
+    onEditAlias: async () => {},
+  } as unknown as Parameters<typeof ProviderAuthPanel>[0]["authHandlers"];
+  await act(async () => {
+    const root = createRoot(host);
+    mountedRoots.push(root);
+    root.render(
+      <LanguageProvider>
+        <ProviderAuthPanel
+          item={ITEM}
+          apiBase="http://proxy"
+          oauth={{ loggedIn: true }}
+          accounts={accounts as never}
+          authHandlers={handlers}
+        />
+      </LanguageProvider>,
+    );
+  });
+  await act(async () => { await flush(); });
+  return host as unknown as HTMLElement;
+}
+
+function badges(host: ParentNode): HTMLElement[] {
+  return [...host.querySelectorAll<HTMLElement>("[data-grok-coupon-badge]")];
+}
+
+function dialogText(host: ParentNode): string {
+  return host.querySelector(".modal-card")?.textContent ?? "";
+}
+
+function buttonWithText(host: ParentNode, text: string): HTMLButtonElement {
+  const found = [...host.querySelectorAll<HTMLButtonElement>(".modal-card button")]
+    .find(button => (button.textContent ?? "").includes(text));
+  if (!found) throw new Error(`no dialog button matching ${text}; saw: ${dialogText(host)}`);
+  return found;
+}
+
+async function openDialog(host: HTMLElement, index = 0): Promise<void> {
+  await act(async () => { badges(host)[index].click(); await flush(); });
+}
+
+const ACCOUNT = (id: string, extra: Record<string, unknown> = {}) => ({
+  id, email: `${id}@example.com`, active: false, ...extra,
+});
+
+const COUPON = (tokenId: string, endDays: number): CouponRow => ({
+  tokenId,
+  validityStart: new Date(Date.now() - 86_400_000).toISOString(),
+  validityEnd: new Date(Date.now() + endDays * 86_400_000).toISOString(),
+});
+
+beforeEach(() => {
+  previousDomGlobals = Object.fromEntries(
+    domGlobals.map((key) => [key, Reflect.get(globalThis, key)]),
+  ) as typeof previousDomGlobals;
+  testWindow = new Window({ url: "http://localhost/" });
+  Object.defineProperty(testWindow.navigator, "language", { configurable: true, value: "en-US" });
+  Object.defineProperties(globalThis, {
+    document: { configurable: true, value: testWindow.document },
+    window: { configurable: true, value: testWindow },
+    navigator: { configurable: true, value: testWindow.navigator },
+  });
+  harness = {
+    coupons: new Map(),
+    readStatus: new Map(),
+    reads: [],
+    consumes: [],
+    consumeReply: async () => json({ success: true, code: "redeemed", replayed: false }),
+    holdReads: false,
+    releaseRead: [],
+    inFlight: 0,
+    peakInFlight: 0,
+  };
+  installFetch();
+  (globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+  mountedRoots = [];
+});
+
+afterEach(async () => {
+  for (const release of harness.releaseRead) release();
+  for (const root of mountedRoots) {
+    await act(async () => { root.unmount(); });
+  }
+  mountedRoots = [];
+  for (const key of domGlobals) {
+    Object.defineProperty(globalThis, key, { configurable: true, value: previousDomGlobals[key] });
+  }
+  await testWindow.happyDOM?.close?.();
+});
+
+test("each signed-in xAI row badges its own coupon count, and a reauth row is never read", async () => {
+  harness.coupons.set("acct-a", [COUPON("restok_a1", 20), COUPON("restok_a2", 5)]);
+  harness.coupons.set("acct-b", []);
+  const host = await mountPanel([ACCOUNT("acct-a"), ACCOUNT("acct-b"), ACCOUNT("acct-c", { needsReauth: true })]);
+
+  expect(badges(host).map(badge => badge.dataset.grokCouponBadge)).toEqual(["2", "0"]);
+  expect(harness.reads.sort()).toEqual(["acct-a", "acct-b"]);
+});
+
+test("a failed read badges the row as an error and the dialog separates auth from upstream", async () => {
+  harness.readStatus.set("acct-a", 502);
+  harness.readStatus.set("acct-b", 401);
+  const host = await mountPanel([ACCOUNT("acct-a"), ACCOUNT("acct-b")]);
+
+  expect(badges(host).map(badge => badge.dataset.grokCouponBadge)).toEqual(["error", "error"]);
+
+  await openDialog(host, 0);
+  expect(dialogText(host)).toContain("Could not read reset coupons");
+  await act(async () => { buttonWithText(host, "Try again").click(); await flush(); });
+  expect(harness.reads.filter(id => id === "acct-a").length).toBe(2);
+});
+
+test("redeeming spends the nearest-expiry coupon with a client-minted UUIDv4", async () => {
+  harness.coupons.set("acct-a", [COUPON("restok_far", 30), COUPON("restok_near", 2)]);
+  const host = await mountPanel([ACCOUNT("acct-a")]);
+
+  await openDialog(host);
+  await act(async () => { buttonWithText(host, "Use 1 coupon").click(); await flush(); });
+  await act(async () => { buttonWithText(host, "Use coupon").click(); await flush(); });
+
+  expect(harness.consumes.length).toBe(1);
+  expect(harness.consumes[0].tokenId).toBe("restok_near");
+  expect(harness.consumes[0].accountId).toBe("acct-a");
+  expect(harness.consumes[0].operationId).toMatch(UUID_V4);
+  expect(dialogText(host)).toContain("Coupon redeemed");
+});
+
+test("a replayed failure is reported as a failure, never as a completed reset", async () => {
+  harness.coupons.set("acct-a", [COUPON("restok_a1", 10)]);
+  harness.consumeReply = async () => json({ code: "redeem_failed", replayed: true, tokenId: "restok_a1" });
+  const host = await mountPanel([ACCOUNT("acct-a")]);
+
+  await openDialog(host);
+  await act(async () => { buttonWithText(host, "Use 1 coupon").click(); await flush(); });
+  await act(async () => { buttonWithText(host, "Use coupon").click(); await flush(); });
+
+  const alert = host.querySelector('.modal-card [role="alert"]')?.textContent ?? "";
+  expect(alert).toContain("Redemption failed");
+  expect(dialogText(host)).not.toContain("Coupon redeemed");
+});
+
+test("a 409 identity mismatch clears the held operation id", async () => {
+  harness.coupons.set("acct-a", [COUPON("restok_a1", 10)]);
+  harness.consumeReply = async () => json({ error: { code: "operation_id_owned_by_another_account" } }, 409);
+  const host = await mountPanel([ACCOUNT("acct-a")]);
+
+  await openDialog(host);
+  await act(async () => { buttonWithText(host, "Use 1 coupon").click(); await flush(); });
+  await act(async () => { buttonWithText(host, "Use coupon").click(); await flush(); });
+  expect(dialogText(host)).toContain("belongs to another account");
+
+  await act(async () => { buttonWithText(host, "Cancel").click(); await flush(); });
+  await act(async () => { buttonWithText(host, "Use 1 coupon").click(); await flush(); });
+  await act(async () => { buttonWithText(host, "Use coupon").click(); await flush(); });
+
+  expect(harness.consumes.length).toBe(2);
+  expect(harness.consumes[1].operationId).not.toBe(harness.consumes[0].operationId);
+  expect(harness.consumes[1].operationId).toMatch(UUID_V4);
+});
+
+test("ledger capacity gets its own retryable message", async () => {
+  harness.coupons.set("acct-a", [COUPON("restok_a1", 10)]);
+  harness.consumeReply = async () => json({ error: { code: "capacity" } }, 503);
+  const host = await mountPanel([ACCOUNT("acct-a")]);
+
+  await openDialog(host);
+  await act(async () => { buttonWithText(host, "Use 1 coupon").click(); await flush(); });
+  await act(async () => { buttonWithText(host, "Use coupon").click(); await flush(); });
+
+  expect(dialogText(host)).toContain("journal is full");
+});
+
+test("an aborted redemption stops posting, re-reads the account, and offers no retry", async () => {
+  harness.coupons.set("acct-a", [COUPON("restok_a1", 10)]);
+  harness.consumeReply = async () => { throw Object.assign(new Error("aborted"), { name: "AbortError" }); };
+  const host = await mountPanel([ACCOUNT("acct-a")]);
+
+  await openDialog(host);
+  await act(async () => { buttonWithText(host, "Use 1 coupon").click(); await flush(); });
+  await act(async () => { buttonWithText(host, "Use coupon").click(); await flush(); });
+
+  expect(dialogText(host)).toContain("outcome is unknown");
+  expect(harness.reads.filter(id => id === "acct-a").length).toBe(2);
+  expect([...host.querySelectorAll(".modal-card button")].some(b => (b.textContent ?? "").includes("Use coupon"))).toBe(false);
+
+  await act(async () => { buttonWithText(host, "Re-read account").click(); await flush(); });
+  expect(harness.consumes.length).toBe(1);
+});
+
+test("one row's retry does not cancel another row's in-flight read", async () => {
+  harness.coupons.set("acct-a", [COUPON("restok_a1", 10)]);
+  harness.coupons.set("acct-b", [COUPON("restok_b1", 10), COUPON("restok_b2", 12)]);
+  harness.holdReads = true;
+  const host = await mountPanel([ACCOUNT("acct-a"), ACCOUNT("acct-b")]);
+
+  // Row A settles first, then retries while row B is still in flight.
+  await act(async () => { harness.releaseRead.shift()?.(); await flush(); });
+  await openDialog(host, 0);
+  const retry = [...host.querySelectorAll<HTMLButtonElement>(".modal-card button")]
+    .find(button => (button.textContent ?? "").includes("Try again"));
+  if (retry) await act(async () => { retry.click(); await flush(); });
+
+  harness.holdReads = false;
+  await act(async () => { for (const release of harness.releaseRead.splice(0)) release(); await flush(); });
+
+  const bBadge = badges(host)[1];
+  expect(bBadge.dataset.grokCouponBadge).toBe("2");
+});
+
+test("no more than three coupon reads are in flight at once", async () => {
+  harness.holdReads = true;
+  for (const id of ["a", "b", "c", "d", "e"]) harness.coupons.set(`acct-${id}`, [COUPON(`restok_${id}`, 9)]);
+  const host = await mountPanel(["a", "b", "c", "d", "e"].map(id => ACCOUNT(`acct-${id}`)));
+
+  expect(harness.peakInFlight).toBeLessThanOrEqual(3);
+
+  harness.holdReads = false;
+  await act(async () => {
+    for (let round = 0; round < 5; round += 1) {
+      for (const release of harness.releaseRead.splice(0)) release();
+      await flush();
+    }
+  });
+  expect(badges(host).map(badge => badge.dataset.grokCouponBadge)).toEqual(["1", "1", "1", "1", "1"]);
+  expect(harness.peakInFlight).toBeLessThanOrEqual(3);
+});
diff --git a/gui/tests/integrations-api.test.ts b/gui/tests/integrations-api.test.ts
index eea7dcfa0c..8a647943df 100644
--- a/gui/tests/integrations-api.test.ts
+++ b/gui/tests/integrations-api.test.ts
@@ -16,9 +16,9 @@ import {
 
 const originalFetch = globalThis.fetch;
 
-test("DSH, Aside and Raycast are file integration clients", () => {
+test("all registered export clients include Cline in file integrations", () => {
   expect(FILE_INTEGRATION_CLIENTS).toEqual([
-    "opencode", "pi", "omp", "hermes", "openclaw", "kimi", "gajae", "dsh", "mcode", "zcode", "prime", "aside", "raycast",
+    "opencode", "pi", "omp", "hermes", "openclaw", "kimi", "gajae", "dsh", "mcode", "zcode", "prime", "aside", "raycast", "omo", "cline",
   ]);
 });
 
diff --git a/gui/tests/integrations-overview-rows.test.ts b/gui/tests/integrations-overview-rows.test.ts
index 54809a4422..4e44e8d674 100644
--- a/gui/tests/integrations-overview-rows.test.ts
+++ b/gui/tests/integrations-overview-rows.test.ts
@@ -290,7 +290,8 @@ test("every client counts toward the summary, not just the file clients", () =>
 
 test("an unsettled file list renders unknown rows instead of dropping them", () => {
   const built = buildOverviewRows(sources({ clients: [], clientsSettled: false }));
-  expect(built.rows).toHaveLength(18);
+  expect(built.rows).toHaveLength(20);
+  expect(rowById(built, "cline")).toMatchObject({ hash: "integrations/cline", labelKey: "integrations.tab.cline", state: "unknown" });
   expect(rowById(built, "omp").state).toBe("unknown");
   expect(rowById(built, "mcode").state).toBe("unknown");
   expect(rowById(built, "zcode").state).toBe("unknown");
diff --git a/gui/tests/locale-parity.test.ts b/gui/tests/locale-parity.test.ts
index 9754b98051..3e05bb632f 100644
--- a/gui/tests/locale-parity.test.ts
+++ b/gui/tests/locale-parity.test.ts
@@ -132,6 +132,12 @@ const ZH_TW_KEEP_ENGLISH: ReadonlySet<string> = new Set([
   "api.clientConfig.clientAside",
   "integrations.tab.raycast",
   "api.clientConfig.clientRaycast",
+  // "omo" is the product's own lowercase spelling, identical in every locale.
+  "integrations.tab.omo",
+  "api.clientConfig.clientOmo",
+  // Cline product name and CLI acronym are intentionally preserved.
+  "integrations.tab.cline",
+  "api.clientConfig.clientCline",
   "integrations.codex.title",
   // Provider proper nouns kept in English
   "provider.name.commandCodeAuth",
diff --git a/gui/tests/page-loading-contract.test.tsx b/gui/tests/page-loading-contract.test.tsx
index 2ab6b88385..d12d9b589c 100644
--- a/gui/tests/page-loading-contract.test.tsx
+++ b/gui/tests/page-loading-contract.test.tsx
@@ -1,6 +1,6 @@
-import { afterEach, beforeEach, expect, test } from "bun:test";
+import { afterEach, beforeEach, expect, spyOn, test } from "bun:test";
 import { Window } from "happy-dom";
-import { act } from "react";
+import { act, useLayoutEffect } from "react";
 import type { Root } from "react-dom/client";
 import Combos from "../src/pages/Combos";
 import { LanguageProvider } from "../src/i18n/provider";
@@ -204,3 +204,198 @@ test("Combos announces silent revalidation over cached content via aria-busy", a
   await act(async () => { root.unmount(); });
   container.remove();
 });
+
+
+test.each(["timer", "visible", "active", "commit-boundary"])("Combos expires a quota block before a new response: %s", async wake => {
+  const { createRoot } = await import("react-dom/client");
+  const startedAt = Date.now();
+  let now = startedAt;
+  const clock = spyOn(Date, "now").mockImplementation(() => now);
+  const schedule = testWindow.setTimeout.bind(testWindow);
+  const cancel = testWindow.clearTimeout.bind(testWindow);
+  const expiryTimers = new Set<number>();
+  let expire: (() => void) | undefined;
+  let controlImmediate = false;
+  let nextControlledTimer = -1;
+  const immediateTimers = new Map<number, () => void>();
+  const scheduleSpy = spyOn(testWindow, "setTimeout").mockImplementation((callback, delay, ...args) => {
+    if (controlImmediate && delay === 0 && typeof callback === "function") {
+      const timer = nextControlledTimer--;
+      immediateTimers.set(timer, () => callback(...args));
+      return timer;
+    }
+    const timer = schedule(callback, delay, ...args);
+    if (delay === 123_456 && typeof callback === "function") {
+      expiryTimers.add(timer);
+      expire = () => callback(...args);
+    }
+    return timer;
+  });
+  const cancelSpy = spyOn(testWindow, "clearTimeout").mockImplementation(timer => {
+    expiryTimers.delete(timer);
+    if (immediateTimers.delete(timer)) return;
+    cancel(timer);
+  });
+  const item = { id: "alpha", model: "combo/alpha", strategy: "failover", stickyLimit: 1,
+    targets: [{ provider: "keyed", model: "m1" }] };
+  let quotaFetches = 0;
+  const workspaceFetches = new Map<string, number>();
+  const waitForAbort = (signal: AbortSignal | null | undefined) => new Promise<Response>((_resolve, reject) => {
+    if (signal?.aborted) reject(signal.reason);
+    else signal?.addEventListener("abort", () => reject(signal.reason), { once: true });
+  });
+  globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = String(input);
+    if (url.includes("/api/provider-quotas")) {
+      quotaFetches += 1;
+      if (quotaFetches > 1) return waitForAbort(init?.signal);
+      return Response.json({ reports: [{ provider: "keyed", updatedAt: startedAt,
+        quota: { updatedAt: startedAt, fiveHourPercent: 100 },
+        routingQuota: { state: "exhausted", updatedAt: startedAt, validUntil: startedAt + 123_456 },
+      }] });
+    }
+    const count = (workspaceFetches.get(url) ?? 0) + 1;
+    workspaceFetches.set(url, count);
+    if (count > 1) return waitForAbort(init?.signal);
+    if (url.includes("/api/combos")) return Response.json({ combos: [item] });
+    if (url.includes("/api/config")) return Response.json({ providers: {
+      keyed: { adapter: "openai-chat", authMode: "key", baseUrl: "https://provider.example/v1", defaultModel: "m1" },
+    } });
+    if (url.includes("/api/models")) return Response.json([
+      { provider: "keyed", id: "m1" }, { provider: "combo", id: "alpha" },
+    ]);
+    return new Response(null, { status: 404 });
+  }) as typeof fetch;
+  const container = document.createElement("div");
+  document.body.append(container);
+  const root = createRoot(container);
+  function ClockBoundary({ active, expireDuringCommit }: { active: boolean; expireDuringCommit: boolean }) {
+    useLayoutEffect(() => {
+      if (expireDuringCommit) now = startedAt + 123_456;
+    }, [expireDuringCommit]);
+    return <LanguageProvider><Combos apiBase={API_BASE} active={active} /></LanguageProvider>;
+  }
+  const render = (active = true, expireDuringCommit = false) =>
+    <ClockBoundary active={active} expireDuringCommit={expireDuringCommit} />;
+  try {
+    await act(async () => { root.render(render()); });
+    await act(async () => { await new Promise<void>(resolve => schedule(resolve, 0)); });
+    const rail = [...container.querySelectorAll<HTMLButtonElement>(".combos-workspace-rail-row")]
+      .find(row => row.querySelector(".combos-workspace-rail-name")?.textContent === "combo/alpha");
+    expect(rail).toBeDefined();
+    await act(async () => { rail!.click(); });
+    await act(async () => { await new Promise<void>(resolve => schedule(resolve, 0)); });
+    const alias = container.querySelector<HTMLInputElement>("#cwi-edit-alias")!;
+    await act(async () => {
+      Object.getOwnPropertyDescriptor(testWindow.HTMLInputElement.prototype, "value")!.set!.call(alias, "kept-draft");
+      alias.dispatchEvent(new testWindow.Event("input", { bubbles: true }));
+    });
+    expect(container.querySelector<HTMLButtonElement>("#cwi-edit-save")!.disabled).toBe(true);
+    expect(expire).toBeDefined();
+    if (wake === "visible") {
+      Object.defineProperty(testWindow.document, "visibilityState", { configurable: true, value: "hidden" });
+      await act(async () => { testWindow.document.dispatchEvent(new testWindow.Event("visibilitychange")); });
+    }
+    if (wake === "active" || wake === "commit-boundary") {
+      controlImmediate = true;
+      // Do not yield to global resource eviction between the two activation commits.
+      act(() => { root.render(render(false)); });
+      expect(expiryTimers.size).toBe(0);
+      now = startedAt + 123_456 - (wake === "commit-boundary" ? 1 : 0);
+      act(() => { root.render(render(true, wake === "commit-boundary")); });
+      expect(immediateTimers.size).toBe(1);
+      const [timer, recheck] = [...immediateTimers.entries()][0]!;
+      immediateTimers.delete(timer);
+      act(() => { recheck(); });
+    } else {
+      now = startedAt + 123_456;
+      await act(async () => {
+        if (wake === "timer") expire!();
+        else {
+          Object.defineProperty(testWindow.document, "visibilityState", { configurable: true, value: "visible" });
+          testWindow.document.dispatchEvent(new testWindow.Event("visibilitychange"));
+        }
+      });
+    }
+    expect(container.querySelector<HTMLInputElement>("#cwi-edit-alias")!.value).toBe("kept-draft");
+    expect(container.querySelector<HTMLButtonElement>("#cwi-edit-save")!.disabled).toBe(false);
+    if (wake === "timer") expect(quotaFetches).toBe(1);
+  } finally {
+    await act(async () => { root.unmount(); });
+    container.remove();
+    scheduleSpy.mockRestore();
+    cancelSpy.mockRestore();
+    clock.mockRestore();
+  }
+  expect(expiryTimers.size).toBe(0);
+  expect(immediateTimers.size).toBe(0);
+});
+
+
+test("Combos evaluates fresh exhaustion beside a retained older quota row without losing drafts", async () => {
+  const { createRoot } = await import("react-dom/client");
+  const startedAt = 1_800_000_000_000;
+  let now = startedAt;
+  const clock = spyOn(Date, "now").mockImplementation(() => now);
+  const interval = globalThis.setInterval;
+  let pollQuota: (() => void) | undefined;
+  const intervalSpy = spyOn(globalThis, "setInterval").mockImplementation((callback, delay, ...args) => {
+    if (delay === 60_000 && typeof callback === "function") pollQuota = () => callback(...args);
+    return interval(callback, delay, ...args);
+  });
+  let quotaFetches = 0;
+  let completeRefresh: ((response: Response) => void) | undefined;
+  const snapshot = (fresh: boolean) => Response.json({ reports: [
+    { provider: "older", routingQuota: { state: "available", updatedAt: startedAt, validUntil: startedAt + 600_000 } },
+    { provider: "keyed", routingQuota: { state: fresh ? "exhausted" : "available",
+      updatedAt: fresh ? now : startedAt, validUntil: startedAt + 600_000 } },
+  ] });
+  globalThis.fetch = (async (input: RequestInfo | URL) => {
+    const url = String(input);
+    if (url.includes("/api/provider-quotas")) {
+      quotaFetches += 1;
+      if (quotaFetches === 1) return snapshot(false);
+      return new Promise<Response>(resolve => { completeRefresh = resolve; });
+    }
+    if (url.includes("/api/combos")) return Response.json({ combos: [{
+      id: "alpha", model: "combo/alpha", strategy: "failover", stickyLimit: 1,
+      targets: [{ provider: "keyed", model: "m1" }],
+    }] });
+    if (url.includes("/api/config")) return Response.json({ providers: {
+      keyed: { adapter: "openai-chat", authMode: "key", baseUrl: "https://provider.example/v1", defaultModel: "m1" },
+    } });
+    if (url.includes("/api/models")) return Response.json([
+      { provider: "keyed", id: "m1" }, { provider: "combo", id: "alpha" },
+    ]);
+    return new Response(null, { status: 404 });
+  }) as typeof fetch;
+  const container = document.createElement("div");
+  document.body.append(container);
+  const root = createRoot(container);
+  try {
+    await act(async () => { root.render(<LanguageProvider><Combos apiBase={API_BASE} /></LanguageProvider>); });
+    const rail = [...container.querySelectorAll<HTMLButtonElement>(".combos-workspace-rail-row")]
+      .find(row => row.querySelector(".combos-workspace-rail-name")?.textContent === "combo/alpha");
+    expect(rail).toBeDefined();
+    await act(async () => { rail!.click(); });
+    await act(async () => { await new Promise<void>(resolve => testWindow.setTimeout(resolve, 0)); });
+    const alias = container.querySelector<HTMLInputElement>("#cwi-edit-alias")!;
+    await act(async () => {
+      Object.getOwnPropertyDescriptor(testWindow.HTMLInputElement.prototype, "value")!.set!.call(alias, "kept-draft");
+      alias.dispatchEvent(new testWindow.Event("input", { bubbles: true }));
+    });
+    expect(container.querySelector<HTMLButtonElement>("#cwi-edit-save")!.disabled).toBe(false);
+    expect(pollQuota).toBeDefined();
+    now = startedAt + 60_000;
+    await act(async () => { pollQuota!(); });
+    expect(completeRefresh).toBeDefined();
+    await act(async () => { completeRefresh!(snapshot(true)); });
+    expect(container.querySelector<HTMLInputElement>("#cwi-edit-alias")!.value).toBe("kept-draft");
+    expect(container.querySelector<HTMLButtonElement>("#cwi-edit-save")!.disabled).toBe(true);
+  } finally {
+    await act(async () => { root.unmount(); });
+    container.remove();
+    intervalSpy.mockRestore();
+    clock.mockRestore();
+  }
+});
diff --git a/gui/tests/provider-catalog-note-popup.test.tsx b/gui/tests/provider-catalog-note-popup.test.tsx
new file mode 100644
index 0000000000..069699735b
--- /dev/null
+++ b/gui/tests/provider-catalog-note-popup.test.tsx
@@ -0,0 +1,143 @@
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { Window } from "happy-dom";
+import { act } from "react";
+import type { Root } from "react-dom/client";
+import { LanguageProvider } from "../src/i18n/provider";
+import AddProviderModal from "../src/components/AddProviderModal";
+
+/**
+ * A few catalog notes are paragraphs — `opencode-free` is ~1100 characters — and an
+ * unclamped one fills the entire 360px scroll viewport, so the row it belongs to becomes
+ * the only row a user can see. The row is clamped to two lines and the rest moves into a
+ * popup.
+ *
+ * These pin the two properties that make the reveal correct rather than merely present:
+ * clicking it must NOT select the provider (the row is a button, and the reveal is its
+ * sibling precisely so a nested button cannot be hoisted out), and the popup must carry
+ * the whole note rather than the clamped text.
+ */
+
+const LONG_NOTE = "No key needed, but this provider gates the tier to its own client and refuses any request that arrives without a session header, so the proxy cannot present itself as that client. Use the keyed provider instead.";
+
+const PRESETS = [
+  { id: "cerebras", label: "Cerebras", adapter: "openai-completions", baseUrl: "https://api.cerebras.ai/v1", auth: "key", note: LONG_NOTE },
+  { id: "together", label: "Together", adapter: "openai-completions", baseUrl: "https://api.together.xyz/v1", auth: "key", note: "Short note." },
+];
+
+const globals = ["document", "window", "navigator", "localStorage", "IS_REACT_ACT_ENVIRONMENT"] as const;
+let previous: Record<(typeof globals)[number], unknown>;
+let win: Window;
+let host: HTMLElement;
+let root: Root | null = null;
+let originalFetch: typeof globalThis.fetch;
+let selected: string[] = [];
+
+beforeEach(() => {
+  previous = Object.fromEntries(globals.map(k => [k, Reflect.get(globalThis, k)])) as typeof previous;
+  originalFetch = globalThis.fetch;
+  selected = [];
+  win = new Window({ url: "http://localhost/" });
+  Object.defineProperty(win.navigator, "language", { configurable: true, value: "en-US" });
+  Object.defineProperties(globalThis, {
+    document: { configurable: true, value: win.document },
+    window: { configurable: true, value: win },
+    navigator: { configurable: true, value: win.navigator },
+    localStorage: { configurable: true, value: win.localStorage },
+  });
+  (globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+  // happy-dom has no native <dialog> behaviour; the popup calls showModal() on mount.
+  const proto = win.HTMLDialogElement?.prototype as unknown as { showModal?: () => void; close?: () => void } | undefined;
+  if (proto && typeof proto.showModal !== "function") {
+    proto.showModal = function showModal(this: HTMLElement) { this.setAttribute("open", ""); };
+    proto.close = function close(this: HTMLElement) { this.removeAttribute("open"); };
+  }
+
+  Object.defineProperty(globalThis, "fetch", {
+    configurable: true,
+    value: async (input: RequestInfo | URL) => {
+      const url = new URL(String(input), "http://localhost");
+      if (url.pathname === "/api/provider-presets") return Response.json({ providers: PRESETS });
+      if (url.pathname === "/api/oauth/providers") return Response.json({ providers: [] });
+      if (url.pathname === "/api/usage") return Response.json({ providers: [] });
+      return Response.json({});
+    },
+  });
+
+  host = win.document.createElement("div") as unknown as HTMLElement;
+  win.document.body.appendChild(host as never);
+});
+
+afterEach(async () => {
+  if (root) {
+    const current = root;
+    await act(async () => { current.unmount(); });
+    root = null;
+  }
+  for (const key of globals) {
+    Object.defineProperty(globalThis, key, { configurable: true, value: previous[key] });
+  }
+  Object.defineProperty(globalThis, "fetch", { configurable: true, value: originalFetch });
+  await win.happyDOM?.close?.();
+});
+
+async function mountCatalog() {
+  const { createRoot } = await import("react-dom/client");
+  await act(async () => {
+    root = createRoot(host);
+    root.render(
+      <LanguageProvider>
+        {/* `paid` is where an API-key preset buckets; the default tab would render an
+            empty list and make these assertions vacuous. */}
+        <AddProviderModal
+          apiBase=""
+          existingNames={[]}
+          initialTier="paid"
+          onClose={() => {}}
+          onAdded={name => { selected.push(name); }}
+        />
+      </LanguageProvider>,
+    );
+  });
+  await act(async () => { await new Promise(r => setTimeout(r, 60)); });
+}
+
+function reveals(): HTMLElement[] {
+  return [...win.document.querySelectorAll<HTMLElement>(".provider-catalog-note-more")] as unknown as HTMLElement[];
+}
+
+test("every nonempty note has a reveal even when a narrow row clips short text", async () => {
+  await mountCatalog();
+  expect(reveals()).toHaveLength(2);
+  // The control is a sibling of the row button, never a child of it: a button nested in
+  // a button is invalid HTML the parser may hoist out of the row.
+  const wrap = reveals()[0]!.parentElement!;
+  expect(wrap.className).toContain("provider-catalog-row-wrap");
+  expect(reveals()[0]!.closest(".list-row")).toBeNull();
+});
+
+test("the reveal opens the full note and does not select the provider", async () => {
+  await mountCatalog();
+  const heading = () => win.document.querySelector(".modal-head h3")?.textContent ?? "";
+  expect(heading()).toBe("Add provider");
+
+  await act(async () => { reveals()[0]!.click(); });
+
+  // Still the catalog, not the per-provider add form: the row was not selected.
+  expect(win.document.querySelector(".provider-catalog")).not.toBeNull();
+  expect(selected).toEqual([]);
+
+  const noteText = win.document.querySelector(".provider-note-text")?.textContent ?? "";
+  expect(noteText).toBe(LONG_NOTE);
+});
+
+test("closing the popup returns keyboard focus to its reveal button", async () => {
+  await mountCatalog();
+  const trigger = reveals()[0]!;
+  trigger.focus();
+  await act(async () => { trigger.click(); });
+  const close = win.document.querySelector(".provider-note-card .btn-icon") as unknown as HTMLElement;
+  await act(async () => { close.click(); });
+  expect(win.document.querySelector(".provider-note-card")).toBeNull();
+  expect(win.document.activeElement).toBe(trigger);
+});
diff --git a/gui/tests/provider-catalog-search.test.tsx b/gui/tests/provider-catalog-search.test.tsx
new file mode 100644
index 0000000000..8d1199218e
--- /dev/null
+++ b/gui/tests/provider-catalog-search.test.tsx
@@ -0,0 +1,210 @@
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { Window } from "happy-dom";
+import { act } from "react";
+import type { Root } from "react-dom/client";
+import { LanguageProvider } from "../src/i18n/provider";
+import AddProviderModal from "../src/components/AddProviderModal";
+
+/**
+ * Unified search replaces browse mode instead of filtering inside one tab, and the tab
+ * strip becomes jump chips rather than moving the selection. These pin the three things
+ * that make that safe rather than merely different: the selected tab survives a search
+ * that matches nothing in it, a strip click does not throw the query away, and a login
+ * already in flight is never unmounted by a query that does not happen to match it.
+ */
+
+const PRESETS = [
+  { id: "cerebras", label: "Cerebras", adapter: "openai-completions", baseUrl: "https://api.cerebras.ai/v1", auth: "key" },
+  { id: "nvidia", label: "NVIDIA NIM", adapter: "openai-chat", baseUrl: "https://integrate.api.nvidia.com/v1", auth: "key", freeTier: true },
+];
+
+const ACCOUNT_ROWS = [
+  { id: "cursor", label: "Cursor", kind: "oauth" as const },
+  { id: "anthropic", label: "Anthropic (Claude)", kind: "oauth" as const },
+];
+
+const globals = ["document", "window", "navigator", "localStorage", "IS_REACT_ACT_ENVIRONMENT"] as const;
+let previous: Record<(typeof globals)[number], unknown>;
+let win: Window;
+let host: HTMLElement;
+let root: Root | null = null;
+let originalFetch: typeof globalThis.fetch;
+
+beforeEach(() => {
+  previous = Object.fromEntries(globals.map(k => [k, Reflect.get(globalThis, k)])) as typeof previous;
+  originalFetch = globalThis.fetch;
+  win = new Window({ url: "http://localhost/" });
+  Object.defineProperty(win.navigator, "language", { configurable: true, value: "en-US" });
+  Object.defineProperties(globalThis, {
+    document: { configurable: true, value: win.document },
+    window: { configurable: true, value: win },
+    navigator: { configurable: true, value: win.navigator },
+    localStorage: { configurable: true, value: win.localStorage },
+  });
+  (globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+  Object.defineProperty(globalThis, "fetch", {
+    configurable: true,
+    value: async (input: RequestInfo | URL) => {
+      const url = new URL(String(input), "http://localhost");
+      if (url.pathname === "/api/provider-presets") return Response.json({ providers: PRESETS });
+      if (url.pathname === "/api/oauth/providers") return Response.json({ providers: [] });
+      if (url.pathname === "/api/usage") return Response.json({ providers: [] });
+      return Response.json({});
+    },
+  });
+  host = win.document.createElement("div") as unknown as HTMLElement;
+  win.document.body.appendChild(host as never);
+});
+
+afterEach(async () => {
+  if (root) {
+    const current = root;
+    await act(async () => { current.unmount(); });
+    root = null;
+  }
+  for (const key of globals) {
+    Object.defineProperty(globalThis, key, { configurable: true, value: previous[key] });
+  }
+  Object.defineProperty(globalThis, "fetch", { configurable: true, value: originalFetch });
+  await win.happyDOM?.close?.();
+});
+
+type ModalExtras = Partial<Parameters<typeof AddProviderModal>[0]>;
+
+async function mount(extras: ModalExtras = {}) {
+  const { createRoot } = await import("react-dom/client");
+  await act(async () => {
+    root = createRoot(host);
+    root.render(
+      <LanguageProvider>
+        <AddProviderModal apiBase="" existingNames={[]} initialTier="paid" onClose={() => {}} onAdded={() => {}} {...extras} />
+      </LanguageProvider>,
+    );
+  });
+  await act(async () => { await new Promise(r => setTimeout(r, 60)); });
+}
+
+function search(): HTMLInputElement {
+  return win.document.querySelector(".provider-catalog-search") as unknown as HTMLInputElement;
+}
+
+async function type(value: string) {
+  const input = search();
+  await act(async () => {
+    const setter = Object.getOwnPropertyDescriptor(win.HTMLInputElement.prototype, "value")?.set;
+    setter?.call(input, value);
+    input.dispatchEvent(new win.Event("input", { bubbles: true }) as never);
+  });
+}
+
+function chips(): HTMLButtonElement[] {
+  return [...win.document.querySelectorAll<HTMLButtonElement>(".provider-catalog-chip")] as unknown as HTMLButtonElement[];
+}
+
+function selectedTabs(): string[] {
+  return [...win.document.querySelectorAll('[role="tab"][aria-selected="true"]')].map(el => el.textContent ?? "");
+}
+
+test("a query that matches nothing on the selected tab does not move the tab", async () => {
+  await mount();
+  expect(selectedTabs()).toEqual(["Paid"]);
+
+  // NVIDIA is a Free row; Paid has no hit at all.
+  await type("nvidia");
+
+  // Search mode: the strip is chips, so nothing is announced as a selected tab, and the
+  // Free group is on screen without the Paid tab having been stolen.
+  expect(selectedTabs()).toEqual([]);
+  expect(chips().length).toBe(4);
+  expect(win.document.querySelector(".provider-catalog-rows")?.textContent).toContain("NVIDIA NIM");
+
+  // Clearing restores the tab the user actually chose.
+  await type("");
+  expect(selectedTabs()).toEqual(["Paid"]);
+});
+
+test("clicking the strip during a search does not throw the query away", async () => {
+  await mount();
+  await type("nvidia");
+  const free = chips().find(chip => (chip.textContent ?? "").startsWith("Free"));
+  expect(free?.disabled).toBe(false);
+  await act(async () => { free?.click(); });
+  expect(search().value).toBe("nvidia");
+});
+
+test("a login in flight survives a query that does not match its row", async () => {
+  await mount({
+    accountRows: ACCOUNT_ROWS,
+    accountBusy: "cursor",
+    accountLoginHint: { provider: "cursor", url: "https://example.com/authorize" },
+  });
+  await type("nvidia");
+  const rows = win.document.querySelector(".provider-catalog-rows")?.textContent ?? "";
+  // Cursor does not match "nvidia". It stays because it owns the authorization URL and
+  // the paste field, and unmounting it mid-login throws away the login in progress.
+  expect(rows).toContain("Cursor");
+  expect(rows).not.toContain("Anthropic");
+});
+
+test("ArrowDown skips a disabled account action before an enabled preset result", async () => {
+  await mount({
+    accountRows: [{ id: "openai", label: "OpenAI", kind: "codex" }],
+    accountBusy: "openai",
+    onAccountLogin: () => {},
+  });
+  await type("nvidia");
+  const firstButton = win.document.querySelector<HTMLButtonElement>(".provider-catalog-rows button");
+  expect(firstButton?.disabled).toBe(true);
+  const target = win.document.querySelector(".provider-catalog-row-wrap > button");
+  expect(target?.textContent).toContain("NVIDIA NIM");
+  const input = search();
+  input.focus();
+  const event = new win.KeyboardEvent("keydown", { key: "ArrowDown", bubbles: true, cancelable: true });
+  await act(async () => { input.dispatchEvent(event as never); });
+  expect(win.document.activeElement).toBe(target);
+  expect(event.defaultPrevented).toBe(true);
+});
+
+test("ArrowDown leaves search focused when the only result action is disabled", async () => {
+  await mount({
+    accountRows: [{ id: "openai", label: "OpenAI", kind: "codex" }],
+    accountBusy: "openai",
+    onAccountLogin: () => {},
+  });
+  await type("no-provider-matches");
+  const buttons = win.document.querySelectorAll<HTMLButtonElement>(".provider-catalog-rows button");
+  expect(buttons).toHaveLength(1);
+  expect(buttons[0]?.disabled).toBe(true);
+  expect(win.document.querySelector(".provider-catalog-rows a[href]")).toBeNull();
+  const input = search();
+  input.focus();
+  const event = new win.KeyboardEvent("keydown", { key: "ArrowDown", bubbles: true, cancelable: true });
+  await act(async () => { input.dispatchEvent(event as never); });
+  expect(win.document.activeElement).toBe(input);
+  expect(event.defaultPrevented).toBe(false);
+});
+
+test("ArrowDown leaves search focused when there are no results", async () => {
+  await mount();
+  await type("no-provider-matches");
+  expect(win.document.querySelector(".provider-catalog-rows button, .provider-catalog-rows a[href]")).toBeNull();
+  const input = search();
+  input.focus();
+  const event = new win.KeyboardEvent("keydown", { key: "ArrowDown", bubbles: true, cancelable: true });
+  await act(async () => { input.dispatchEvent(event as never); });
+  expect(win.document.activeElement).toBe(input);
+  expect(event.defaultPrevented).toBe(false);
+});
+
+test("ArrowDown moves directly to the first preset result", async () => {
+  await mount();
+  await type("nvidia");
+  const target = win.document.querySelector(".provider-catalog-row-wrap > button");
+  expect(target?.textContent).toContain("NVIDIA NIM");
+  const input = search();
+  input.focus();
+  const event = new win.KeyboardEvent("keydown", { key: "ArrowDown", bubbles: true, cancelable: true });
+  await act(async () => { input.dispatchEvent(event as never); });
+  expect(win.document.activeElement).toBe(target);
+  expect(event.defaultPrevented).toBe(true);
+});
diff --git a/gui/tests/subagents-fallback.test.tsx b/gui/tests/subagents-fallback.test.tsx
index bf838d63ca..71001416ed 100644
--- a/gui/tests/subagents-fallback.test.tsx
+++ b/gui/tests/subagents-fallback.test.tsx
@@ -99,7 +99,7 @@ beforeEach(() => {
           model: preferredModel,
           effort: null,
           available: [
-            { provider: "openai", model: "gpt-5.4", namespaced: "gpt-5.4" },
+            { provider: "openai", model: "gpt-5.5", namespaced: "gpt-5.5" },
             { provider: "anthropic", model: "claude-sonnet-4-6", namespaced: "anthropic/claude-sonnet-4-6" },
           ],
           efforts: [],
@@ -735,7 +735,7 @@ const compatibilityCases: Array<{
   keepNative: boolean;
   warning: boolean;
 }> = [
-  { name: "native preferred model", model: "gpt-5.4", enabled: true, mode: "v2", keepNative: false, warning: false },
+  { name: "native preferred model", model: "gpt-5.5", enabled: true, mode: "v2", keepNative: false, warning: false },
   { name: "routed preferred model on the default surface", model: "anthropic/claude-sonnet-4-6", enabled: false, mode: "default", keepNative: false, warning: true },
   { name: "routed preferred model on V1", model: "anthropic/claude-sonnet-4-6", enabled: false, mode: "v1", keepNative: false, warning: false },
   { name: "forced V2 preserving native V1 with global V2 disabled", model: "anthropic/claude-sonnet-4-6", enabled: false, mode: "v2", keepNative: true, warning: false },
diff --git a/gui/tests/vision-reasoning-contract.test.ts b/gui/tests/vision-reasoning-contract.test.ts
index ca6d2699c5..40fb449b90 100644
--- a/gui/tests/vision-reasoning-contract.test.ts
+++ b/gui/tests/vision-reasoning-contract.test.ts
@@ -12,15 +12,15 @@ import {
 test("vision reasoning uses advertised model ladders and clamps unsupported persisted values", () => {
   const models: ModelInfo[] = [
     { id: "gpt-5.6-luna", provider: "openai", namespaced: "gpt-5.6-luna", reasoningEfforts: ["low", "medium", "high", "xhigh", "max"] },
-    { id: "gpt-5.4-mini", provider: "openai", namespaced: "gpt-5.4-mini", reasoningEfforts: ["low", "medium", "high", "xhigh"] },
+    { id: "gpt-5.5", provider: "openai", namespaced: "gpt-5.5", reasoningEfforts: ["low", "medium", "high", "xhigh"] },
   ];
 
   expect(visionReasoningLadder(models, "gpt-5.6-luna")).toEqual(VISION_REASONING_LEVELS);
-  const mini = visionReasoningLadder(models, "gpt-5.4-mini");
-  expect(mini).toEqual(["low", "medium", "high", "xhigh"]);
-  expect(clampVisionReasoningToLadder(mini, "max")).toBe("xhigh");
-  expect(clampVisionReasoningToLadder(mini, "high")).toBe("high");
-  expect(visionReasoningOptionsFor(mini, "max")).toEqual(mini);
+  const shorter = visionReasoningLadder(models, "gpt-5.5");
+  expect(shorter).toEqual(["low", "medium", "high", "xhigh"]);
+  expect(clampVisionReasoningToLadder(shorter, "max")).toBe("xhigh");
+  expect(clampVisionReasoningToLadder(shorter, "high")).toBe("high");
+  expect(visionReasoningOptionsFor(shorter, "max")).toEqual(shorter);
 });
 
 test("vision reasoning clamp matches the server for non-prefix ladders", () => {
diff --git a/gui/tests/vision-sidecar-dashboard.test.tsx b/gui/tests/vision-sidecar-dashboard.test.tsx
index fd41cc89fd..5a2c7cec3b 100644
--- a/gui/tests/vision-sidecar-dashboard.test.tsx
+++ b/gui/tests/vision-sidecar-dashboard.test.tsx
@@ -36,7 +36,7 @@ const initialSidecar: SidecarData = {
   },
   visionModels: [
     { value: "gpt-5.6-luna", label: "gpt-5.6-luna", backend: "openai", baseline: true },
-    { value: "gpt-5.4-mini", label: "gpt-5.4-mini", backend: "openai", baseline: true },
+    { value: "gpt-5.6-terra", label: "gpt-5.6-terra", backend: "openai", baseline: true },
   ],
 };
 
@@ -104,7 +104,7 @@ function harness(sidecar: SidecarData = initialSidecar) {
     visionModels: sidecar.visionModels ?? [],
     models: [
       { id: "gpt-5.6-luna", provider: "openai", namespaced: "gpt-5.6-luna", reasoningEfforts: ["low", "medium", "high", "xhigh", "max"] },
-      { id: "gpt-5.4-mini", provider: "openai", namespaced: "gpt-5.4-mini", reasoningEfforts: ["low", "medium", "high", "xhigh", "max"] },
+      { id: "gpt-5.6-terra", provider: "openai", namespaced: "gpt-5.6-terra", reasoningEfforts: ["low", "medium", "high", "xhigh", "max"] },
     ],
     saveSidecar,
     shadowCall: { enabled: false, model: "" },
@@ -304,11 +304,11 @@ test("choosing a model from Off sends enabled:true plus that model and backend",
   const { d, patches } = harness({ ...initialSidecar, vision: { ...initialSidecar.vision, enabled: false } });
   await mount(d);
   await act(async () => { modelTrigger().click(); });
-  const next = pickOption("gpt-5.4-mini");
+  const next = pickOption("gpt-5.6-terra");
   expect(next).toBeTruthy();
   await act(async () => { next!.click(); });
   expect(patches).toEqual([
-    { vision: { model: "gpt-5.4-mini", backend: "openai", reasoning: "medium", enabled: true } },
+    { vision: { model: "gpt-5.6-terra", backend: "openai", reasoning: "medium", enabled: true } },
   ]);
 });
 
@@ -369,12 +369,12 @@ test("model and reasoning saves still omit enabled, limit, and timeout", async (
   ) as HTMLButtonElement;
 
   await act(async () => { modelTrigger.click(); });
-  const nextModel = pickOption("gpt-5.4-mini");
+  const nextModel = pickOption("gpt-5.6-terra");
   expect(nextModel).toBeTruthy();
   await act(async () => { nextModel!.click(); });
   expect(patches).toHaveLength(1);
   expect(patches[0]).toEqual({
-    vision: { model: "gpt-5.4-mini", backend: "openai", reasoning: "medium" },
+    vision: { model: "gpt-5.6-terra", backend: "openai", reasoning: "medium" },
   });
   assertVisionControlFieldsOmitted(patches[0]!);
 
diff --git a/package.json b/package.json
index 936324ccec..6fae3e4d49 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@bitkyc08/opencodex",
-  "version": "2.51.0",
+  "version": "2.52.0",
   "description": "Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code",
   "type": "module",
   "main": "./bin/package-main.mjs",
@@ -48,6 +48,8 @@
     "privacy:scan": "bun scripts/privacy-scan.ts",
     "skill:surface": "bun scripts/generate-ocx-skill-surface.ts",
     "skill:surface:check": "bun scripts/generate-ocx-skill-surface.ts --check",
+    "structure:index": "bun scripts/structure-ssot.ts --fix",
+    "structure:check": "bun scripts/structure-ssot.ts",
     "generate:model-metadata": "bun scripts/generate-model-metadata.ts",
     "build:gui": "cd gui && bun install --frozen-lockfile && bun run build && cd .. && bun run prepare:package",
     "prepare:package": "bun scripts/prepare-package.ts",
diff --git a/scripts/release-notes.ts b/scripts/release-notes.ts
index df68ed2b07..76a364a980 100644
--- a/scripts/release-notes.ts
+++ b/scripts/release-notes.ts
@@ -1134,7 +1134,7 @@ async function main(argv: string[]): Promise<void> {
       console.error("✗ polish --base-url must be https: or a loopback http: host (the API key must not travel in plaintext)");
       process.exit(1);
     }
-    const model = args.get("model") ?? process.env.OPENAI_MODEL ?? "gpt-5.4";
+    const model = args.get("model") ?? process.env.OPENAI_MODEL ?? "gpt-5.6-luna";
 
     if (!(await Bun.file(inputPath).exists())) {
       console.error(`✗ polish input not found: ${inputPath}`);
diff --git a/scripts/structure-ssot.ts b/scripts/structure-ssot.ts
new file mode 100644
index 0000000000..ddc61e0994
--- /dev/null
+++ b/scripts/structure-ssot.ts
@@ -0,0 +1,559 @@
+#!/usr/bin/env bun
+/**
+ * structure/ single-source-of-truth gate.
+ *
+ * The maintainer docs under structure/ are a SECOND description of this tree, and a second
+ * description drifts. This module is the proof that it has not: it validates the doc map, the
+ * source-to-doc map, decision-record topology, invariant-to-test bindings, and every link, anchor
+ * and repository path the docs name. It also generates structure/INDEX.md, so the reading order
+ * cannot contradict the manifest.
+ *
+ * Two deliberate choices, both learned from an earlier revision of this file that got them wrong:
+ *
+ * - Paths are checked against the GIT INDEX first, not the filesystem. existsSync cannot tell a
+ *   tracked file from untracked local leftovers, and it is case-insensitive on Windows and
+ *   case-sensitive on Linux, so a filesystem-only gate gives a different verdict per machine and
+ *   fails a maintainer who still has a retired directory on disk.
+ * - A source area may be described by MORE THAN ONE doc. An earlier design demanded exactly one
+ *   owner per area; in this repository that claim was simply false (src/server/ is described by the
+ *   management-API doc, the Responses transport doc and the Images doc), and a rule that is false
+ *   is worse than no rule because the gate reports green while the map misdirects.
+ *
+ * Usage:
+ *   bun scripts/structure-ssot.ts            # report findings, exit 1 on failure
+ *   bun scripts/structure-ssot.ts --fix      # rewrite structure/INDEX.md from the manifest
+ */
+import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+
+const BT = "\u0060";
+
+export type Manifest = {
+  version: number;
+  sizeBudgetLines: number;
+  generatedPaths: string[];
+  absentPaths: { path: string; reason: string }[];
+  tiers: { id: number; name: string; purpose: string }[];
+  docs: { path: string; tier: number; title: string; scope: string; documents: string[] }[];
+  grace: {
+    undocumentedSourceAreas: { path: string; reason: string }[];
+    unboundInvariants: { id: string; reason: string }[];
+    oversizeDocs: string[];
+    staleRefs: string[];
+  };
+};
+
+const GENERATED_DOCS = ["INDEX.md"];
+const RULE_DOCS = ["AGENTS.md"];
+/**
+ * Roots that stay checked even after they are deleted. Deriving the root set from the tree alone
+ * means a reference becomes INVISIBLE exactly when the directory disappears, which is the moment
+ * stale references start appearing. go/ is the live example: it is retired and untracked, and
+ * without this list every remaining go/ mention would go unchecked.
+ */
+const HISTORICAL_ROOTS = ["src", "tests", "gui", "scripts", "docs", "docs-site", "bin", "go", "devlog", ".github", "structure", "readme"];
+
+const toPosix = (p: string) => p.split("\\").join("/");
+const trimSlash = (p: string) => p.replace(/\/+$/, "");
+
+/** Parse and validate the manifest, so a malformed file is an actionable failure, not a stack trace. */
+export function loadManifest(raw: string): { manifest: Manifest } | { error: string } {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (cause) {
+    return { error: "structure/manifest.json is not valid JSON: " + (cause as Error).message };
+  }
+  const m = parsed as Partial<Manifest>;
+  const problems: string[] = [];
+  const isArray = (v: unknown) => Array.isArray(v);
+  if (typeof m.sizeBudgetLines !== "number") problems.push("sizeBudgetLines must be a number");
+  if (!isArray(m.generatedPaths)) problems.push("generatedPaths must be an array");
+  if (!isArray(m.absentPaths)) problems.push("absentPaths must be an array");
+  else {
+    m.absentPaths.forEach((entry, i) => {
+      if (typeof entry?.path !== "string") problems.push("absentPaths[" + i + "].path must be a string");
+      if (typeof entry?.reason !== "string") problems.push("absentPaths[" + i + "].reason must be a string");
+    });
+  }
+  if (!isArray(m.tiers)) problems.push("tiers must be an array");
+  if (!isArray(m.docs)) problems.push("docs must be an array");
+  else {
+    m.docs.forEach((doc, i) => {
+      if (typeof doc?.path !== "string") problems.push("docs[" + i + "].path must be a string");
+      if (typeof doc?.tier !== "number") problems.push("docs[" + i + "].tier must be a number");
+      if (typeof doc?.title !== "string") problems.push("docs[" + i + "].title must be a string");
+      if (typeof doc?.scope !== "string") problems.push("docs[" + i + "].scope must be a string");
+      if (!isArray(doc?.documents)) problems.push("docs[" + i + "].documents must be an array");
+    });
+  }
+  const grace = m.grace as Partial<Manifest["grace"]> | undefined;
+  if (!grace) problems.push("grace must be an object");
+  else {
+    for (const key of ["undocumentedSourceAreas", "unboundInvariants", "oversizeDocs", "staleRefs"] as const) {
+      if (!isArray(grace[key])) problems.push("grace." + key + " must be an array");
+    }
+    if (isArray(grace.undocumentedSourceAreas)) {
+      grace.undocumentedSourceAreas.forEach((entry, i) => {
+        if (typeof entry?.path !== "string") problems.push("grace.undocumentedSourceAreas[" + i + "].path must be a string");
+        if (typeof entry?.reason !== "string") problems.push("grace.undocumentedSourceAreas[" + i + "].reason must be a string");
+      });
+    }
+    if (isArray(grace.unboundInvariants)) {
+      grace.unboundInvariants.forEach((entry, i) => {
+        if (typeof entry?.id !== "string") problems.push("grace.unboundInvariants[" + i + "].id must be a string");
+        if (typeof entry?.reason !== "string") problems.push("grace.unboundInvariants[" + i + "].reason must be a string");
+      });
+    }
+    for (const key of ["oversizeDocs", "staleRefs"] as const) {
+      if (!isArray(grace[key])) continue;
+      grace[key].forEach((entry, i) => {
+        if (typeof entry !== "string") problems.push("grace." + key + "[" + i + "] must be a string");
+      });
+    }
+  }
+  if (problems.length > 0) return { error: "structure/manifest.json is malformed: " + problems.join("; ") };
+  return { manifest: parsed as Manifest };
+}
+
+function listMarkdown(dir: string, root: string, out: string[] = []): string[] {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) listMarkdown(full, root, out);
+    else if (entry.name.endsWith(".md")) out.push(toPosix(relative(root, full)));
+  }
+  return out.sort();
+}
+
+/** Tracked files plus every directory on their way up, read once from the git index. */
+function trackedPaths(repoRoot: string): Set<string> | null {
+  let stdout: string;
+  try {
+    const run = Bun.spawnSync(["git", "ls-files", "-z"], { cwd: repoRoot, stdout: "pipe", stderr: "pipe" });
+    if (run.exitCode !== 0) return null;
+    stdout = new TextDecoder().decode(run.stdout);
+  } catch {
+    return null;
+  }
+  const set = new Set<string>();
+  for (const file of stdout.split("\0")) {
+    if (!file) continue;
+    set.add(file);
+    const parts = file.split("/");
+    for (let i = 1; i < parts.length; i += 1) set.add(parts.slice(0, i).join("/"));
+  }
+  return set.size > 0 ? set : null;
+}
+
+/** Markdown body with fenced blocks blanked out, so examples inside a fence are not scanned. */
+function withoutFences(body: string): string {
+  let fenced = false;
+  return body
+    .split("\n")
+    .map((line) => {
+      if (/^\s{0,3}(?:\u0060\u0060\u0060|~~~)/.test(line)) {
+        fenced = !fenced;
+        return "";
+      }
+      return fenced ? "" : line;
+    })
+    .join("\n");
+}
+
+/** GitHub-style heading anchor. */
+function headingAnchors(body: string): Set<string> {
+  const out = new Set<string>();
+  for (const line of withoutFences(body).split("\n")) {
+    const m = /^#{1,6}\s+(.*)$/.exec(line);
+    if (!m) continue;
+    const slug = m[1]
+      .replace(/\u0060/g, "")
+      .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
+      .trim()
+      .toLowerCase()
+      .replace(/[^\p{L}\p{N} _-]/gu, "")
+      .replace(/\s+/g, "-");
+    if (slug) out.add(slug);
+  }
+  return out;
+}
+
+export function renderIndex(manifest: Manifest): string {
+  const lines: string[] = [];
+  lines.push("# opencodex Structure Index");
+  lines.push("");
+  lines.push("This folder is the maintainer source of truth for the current system shape. Public user workflows");
+  lines.push("belong in " + BT + "docs-site/" + BT + ". Development work is recorded in " + BT + "devlog/" + BT + " units — " + BT + "_plan/" + BT + " while open,");
+  lines.push(BT + "_fin/" + BT + " once closed — while " + BT + "docs/" + BT + " keeps investigations and diagnostic notes worth retaining for");
+  lines.push("archaeology, debugging, or source research.");
+  lines.push("");
+  lines.push(
+    "Generated from " + BT + "structure/manifest.json" + BT + " by " + BT + "bun run structure:index" + BT + ". Do not edit by hand; " +
+      BT + "bun run structure:check" + BT + " fails when this file and the manifest disagree. The rules for changing anything",
+  );
+  lines.push("in this folder are in [" + BT + "AGENTS.md" + BT + "](AGENTS.md).");
+  lines.push("");
+  lines.push("## Reading order");
+  for (const tier of manifest.tiers) {
+    const docs = manifest.docs.filter((d) => d.tier === tier.id);
+    if (docs.length === 0) continue;
+    lines.push("");
+    lines.push("### Tier " + tier.id + " — " + tier.name);
+    lines.push("");
+    lines.push(tier.purpose);
+    lines.push("");
+    lines.push("| Doc | Scope |");
+    lines.push("| --- | --- |");
+    for (const doc of docs) lines.push("| [" + BT + doc.path + BT + "](" + doc.path + ") | " + doc.scope + " |");
+  }
+  lines.push("");
+  lines.push("## Which doc describes which source");
+  lines.push("");
+  lines.push("A source area can be described by more than one doc, because these docs are organised by topic and");
+  lines.push(BT + "src/" + BT + " is organised by module. Changing an area obliges the same change to update every doc listed");
+  lines.push("for it; see [" + BT + "AGENTS.md" + BT + "](AGENTS.md).");
+  lines.push("");
+  lines.push("| Source path | Described by |");
+  lines.push("| --- | --- |");
+  const byPath = new Map<string, string[]>();
+  for (const doc of manifest.docs) {
+    for (const area of doc.documents) byPath.set(area, [...(byPath.get(area) ?? []), doc.path]);
+  }
+  for (const area of [...byPath.keys()].sort()) {
+    const docs = byPath.get(area)!.map((d) => "[" + BT + d + BT + "](" + d + ")").join("<br>");
+    lines.push("| " + BT + area + BT + " | " + docs + " |");
+  }
+  lines.push("");
+  lines.push("### Not described by any doc");
+  lines.push("");
+  lines.push("| Source path | Why |");
+  lines.push("| --- | --- |");
+  for (const row of [...manifest.grace.undocumentedSourceAreas].sort((a, b) => a.path.localeCompare(b.path))) {
+    lines.push("| " + BT + row.path + BT + " | " + row.reason + " |");
+  }
+  lines.push("");
+  lines.push("## Decision records");
+  lines.push("");
+  lines.push("Superseded reasoning lives in " + BT + "decisions/" + BT + " as numbered records. A doc states the contract that holds now and");
+  lines.push("links the record that explains why; it never carries the reasoning inline.");
+  lines.push("");
+  return lines.join("\n") + "\n";
+}
+
+export function runStructureChecks(repoRoot: string): string[] {
+  const structureDir = join(repoRoot, "structure");
+  const failures: string[] = [];
+  const fail = (message: string) => failures.push(message);
+
+  const manifestPath = join(structureDir, "manifest.json");
+  if (!existsSync(manifestPath)) return ["structure/manifest.json is missing"];
+  const loaded = loadManifest(readFileSync(manifestPath, "utf8"));
+  if ("error" in loaded) return [loaded.error];
+  const manifest = loaded.manifest;
+
+  const tracked = trackedPaths(repoRoot);
+  const trackedLower = new Map<string, string>();
+  if (tracked) for (const p of tracked) trackedLower.set(p.toLowerCase(), p);
+
+  /**
+   * A repository path is real when git tracks it. The filesystem is consulted only when the index
+   * could not be read at all: CI checks out a clean tree, so an untracked local leftover that
+   * satisfied the gate here would still fail there, which is the split verdict this module exists
+   * to remove. The cost is that a newly written file has to be staged before the gate can see it.
+   */
+  const pathIsReal = (raw: string): "ok" | "missing" | string => {
+    const p = trimSlash(raw);
+    if (!tracked) return existsSync(join(repoRoot, p)) ? "ok" : "missing";
+    if (tracked.has(p)) return "ok";
+    const variant = trackedLower.get(p.toLowerCase());
+    if (variant && variant !== p) return variant;
+    return "missing";
+  };
+  const isTracked = (raw: string) => tracked?.has(trimSlash(raw)) ?? existsSync(join(repoRoot, trimSlash(raw)));
+  // Top-level entries, so a backticked root FILE is validated directly, the same as a directory
+  // path. The historical roots are unioned in so a deleted tree keeps being checked.
+  const rootEntries = new Set<string>(HISTORICAL_ROOTS);
+  if (tracked) for (const p of tracked) rootEntries.add(p.split("/")[0]!);
+  else for (const entry of readdirSync(repoRoot, { withFileTypes: true })) rootEntries.add(entry.name);
+
+  const present = listMarkdown(structureDir, structureDir);
+  const sotOnDisk = present.filter((p) => !p.startsWith("decisions/") && !GENERATED_DOCS.includes(p) && !RULE_DOCS.includes(p));
+  const declared = manifest.docs.map((d) => d.path);
+
+  // 1. doc map parity
+  for (const p of sotOnDisk) if (!declared.includes(p)) fail("structure/" + p + " is not listed in manifest.json");
+  for (const p of declared) if (!sotOnDisk.includes(p)) fail("manifest.json lists structure/" + p + " but the file is missing");
+  const seenDoc = new Set<string>();
+  for (const p of declared) {
+    if (seenDoc.has(p)) fail("manifest.json lists structure/" + p + " twice");
+    seenDoc.add(p);
+  }
+  for (const doc of manifest.docs) {
+    if (!manifest.tiers.some((t) => t.id === doc.tier)) fail("structure/" + doc.path + " claims unknown tier " + doc.tier);
+    // Leading digits are rejected outright: 09_x.md and 01-x.md are the same mistake.
+    if (!/^(?:[a-z][a-z0-9-]*\/)?[a-z][a-z0-9-]*\.md$/.test(doc.path)) {
+      fail("structure/" + doc.path + " must be kebab-case, start with a letter, and sit at most one directory deep");
+    }
+  }
+
+  // 2. size budget
+  for (const doc of manifest.docs) {
+    const p = join(structureDir, doc.path);
+    if (!existsSync(p)) continue;
+    const count = readFileSync(p, "utf8").replace(/\n$/, "").split("\n").length;
+    const graced = manifest.grace.oversizeDocs.includes(doc.path);
+    if (count > manifest.sizeBudgetLines && !graced) {
+      fail("structure/" + doc.path + " is " + count + " lines, over the " + manifest.sizeBudgetLines + "-line budget; split it or add it to grace.oversizeDocs with a plan");
+    }
+    if (count <= manifest.sizeBudgetLines && graced) {
+      fail("grace.oversizeDocs still lists structure/" + doc.path + ", which is now " + count + " lines; drop the grace entry");
+    }
+  }
+  for (const p of manifest.grace.oversizeDocs) {
+    if (!declared.includes(p)) fail("grace.oversizeDocs names structure/" + p + ", which is not a declared doc");
+  }
+
+  // 3. links, anchors, repository paths, and the inline-decision ban
+  const linkRe = /\]\(([^)\s]+)\)/g;
+  const pathRe = new RegExp(BT + "([A-Za-z0-9_.@-]+(?:/[A-Za-z0-9_.@-]*)*)" + BT, "g");
+  const anchorCache = new Map<string, Set<string>>();
+  for (const rel of present) {
+    const abs = join(structureDir, rel);
+    const raw = readFileSync(abs, "utf8");
+    const body = withoutFences(raw);
+    const isRecord = rel.startsWith("decisions/");
+    for (const line of body.split("\n")) {
+      if (/\[decision log\]/i.test(line) || /^-\s*목적과 의도\s*:/.test(line.trim())) {
+        if (!isRecord) fail("structure/" + rel + " carries inline decision-log reasoning; move it to decisions/ and link the record");
+      }
+    }
+    let m: RegExpExecArray | null;
+    linkRe.lastIndex = 0;
+    while ((m = linkRe.exec(body))) {
+      const target = m[1];
+      if (/^(?:https?|mailto):/.test(target)) continue;
+      const [file, fragment] = target.split("#");
+      // A fragment-only link points at this same document; it still has to name a real heading.
+      const resolved = file === "" ? abs : resolve(dirname(abs), file);
+      if (file !== "") {
+        const repoRel = toPosix(relative(repoRoot, resolved));
+        const verdict = pathIsReal(repoRel);
+        if (verdict === "missing") {
+          fail("structure/" + rel + " links " + target + ", which does not exist");
+          continue;
+        }
+        if (verdict !== "ok") {
+          fail("structure/" + rel + " links " + target + ", but the tracked path is " + verdict);
+          continue;
+        }
+      }
+      if (fragment && resolved.endsWith(".md")) {
+        if (!anchorCache.has(resolved)) anchorCache.set(resolved, headingAnchors(readFileSync(resolved, "utf8")));
+        if (!anchorCache.get(resolved)!.has(fragment)) {
+          fail("structure/" + rel + " links " + target + ", but that heading anchor does not exist");
+        }
+      }
+    }
+    // A decision record describes a PAST state, so its prose is not held against the present tree.
+    if (isRecord) continue;
+    pathRe.lastIndex = 0;
+    while ((m = pathRe.exec(body))) {
+      const named = trimSlash(m[1]);
+      // Only tokens rooted at a real top-level entry are paths; the rest are ordinary code spans.
+      if (!rootEntries.has(named.split("/")[0]!)) continue;
+      if (manifest.generatedPaths.some((g) => named === trimSlash(g) || named.startsWith(trimSlash(g) + "/"))) continue;
+      if (manifest.absentPaths.some((a) => trimSlash(a.path) === named)) continue;
+      if (manifest.grace.staleRefs.map(trimSlash).includes(named)) continue;
+      const verdict = pathIsReal(named);
+      if (verdict === "missing") fail("structure/" + rel + " names " + named + ", which this tree does not have");
+      else if (verdict !== "ok") fail("structure/" + rel + " names " + named + ", but the tracked path is " + verdict);
+    }
+  }
+  for (const stale of manifest.grace.staleRefs) {
+    if (pathIsReal(stale) === "ok") fail("grace.staleRefs still lists " + stale + ", which now exists; drop the grace entry");
+  }
+  for (const absent of manifest.absentPaths) {
+    if (isTracked(absent.path)) fail(absent.path + " is declared absent in manifest.json but is tracked; the docs describing its absence are wrong");
+  }
+
+  // 4. decision records
+  const adrFiles = present.filter((p) => p.startsWith("decisions/"));
+  const referenced = new Map<string, Set<string>>();
+  // Ownership is the declared link form, read with fences removed. A record path mentioned in prose
+  // or shown inside an example is not a claim of ownership, and counting it made an orphaned record
+  // look owned while reporting a second owner nobody could remove.
+  const ownerLinkRe = /^>\s*Decision record:\s*\[[^\]]*\]\(([^)\s]+)\)/gm;
+  for (const doc of manifest.docs) {
+    const abs = join(structureDir, doc.path);
+    if (!existsSync(abs)) continue;
+    const body = withoutFences(readFileSync(abs, "utf8"));
+    ownerLinkRe.lastIndex = 0;
+    let hit: RegExpExecArray | null;
+    while ((hit = ownerLinkRe.exec(body))) {
+      const target = hit[1].split("#")[0]!;
+      const repoRel = toPosix(relative(structureDir, resolve(dirname(abs), target)));
+      // The link has to land in decisions/; a basename match would let a record elsewhere claim
+      // ownership of a file it does not point at.
+      if (!repoRel.startsWith("decisions/")) {
+        fail("structure/" + doc.path + " points a Decision record line at " + target + ", which is not in decisions/");
+        continue;
+      }
+      referenced.set(repoRel, (referenced.get(repoRel) ?? new Set<string>()).add(doc.path));
+    }
+  }
+  const ids = new Set<string>();
+  for (const adr of adrFiles) {
+    const name = adr.slice("decisions/".length);
+    const match = /^ADR-([0-9]{4})-[a-z0-9-]+\.md$/.exec(name);
+    if (!match) {
+      fail("structure/" + adr + " does not match ADR-NNNN-slug.md");
+      continue;
+    }
+    if (ids.has(match[1])) fail("decision record number " + match[1] + " is used twice");
+    ids.add(match[1]);
+    const owners = [...(referenced.get(adr) ?? new Set<string>())];
+    if (owners.length === 0) fail("structure/" + adr + " is not linked from any doc; every record needs a contract owner");
+    if (owners.length > 1) fail("structure/" + adr + " is linked from " + owners.join(" and ") + "; a record has one owner");
+  }
+  for (const key of referenced.keys()) if (!adrFiles.includes(key)) fail("a doc links structure/" + key + ", which does not exist");
+
+  // 5. invariant-to-test bindings
+  const overviewPath = join(structureDir, "overview.md");
+  if (!existsSync(overviewPath)) {
+    fail("structure/overview.md is missing; it is the invariant index, and its absence would silence every binding check");
+  } else {
+    const body = readFileSync(overviewPath, "utf8");
+    const blocks: { id: string; text: string }[] = [];
+    let current: { id: string; text: string } | null = null;
+    for (const line of body.split("\n")) {
+      const start = /^-\s+\*\*(INV-[A-Z0-9-]+)\*\*/.exec(line);
+      if (start) {
+        if (current) blocks.push(current);
+        current = { id: start[1], text: line };
+      } else if (/^-\s/.test(line)) {
+        if (current) blocks.push(current);
+        current = null;
+      } else if (current) current.text += "\n" + line;
+    }
+    if (current) blocks.push(current);
+    if (blocks.length === 0) fail("overview.md declares no invariants; the invariant index cannot be empty");
+    const seen = new Set<string>();
+    const unbound = new Map(manifest.grace.unboundInvariants.map((u) => [u.id, u.reason]));
+    for (const block of blocks) {
+      if (seen.has(block.id)) fail("overview.md declares " + block.id + " twice");
+      seen.add(block.id);
+      const bound = new RegExp("Enforced by " + BT + "([^" + BT + "]+)" + BT).exec(block.text);
+      if (!bound) {
+        if (!unbound.has(block.id)) {
+          fail(block.id + " has no Enforced by binding and is not recorded in grace.unboundInvariants with a reason");
+        }
+        continue;
+      }
+      if (unbound.has(block.id)) {
+        fail(block.id + " is bound to a test and also listed in grace.unboundInvariants; drop the grace entry");
+        continue;
+      }
+      const test = bound[1];
+      if (!/^tests\/.+\.test\.ts$/.test(test)) {
+        fail(block.id + " names " + test + ", which is not a tests/**.test.ts file");
+        continue;
+      }
+      if (pathIsReal(test) !== "ok") {
+        fail(block.id + " names " + test + ", which this tree does not have");
+        continue;
+      }
+      const source = readFileSync(join(repoRoot, test), "utf8");
+      if (!new RegExp(block.id + "(?![A-Z0-9-])").test(source)) {
+        fail(test + " does not name " + block.id + "; the binding has to be readable from the test side too");
+      }
+    }
+    for (const id of unbound.keys()) {
+      if (!seen.has(id)) fail("grace.unboundInvariants names " + id + ", which overview.md does not declare");
+    }
+  }
+
+  // 6. source-to-doc map
+  const described = new Map<string, string[]>();
+  // What a doc actually names, so a manifest claim cannot invent coverage the prose does not have.
+  const namedByDoc = new Map<string, string[]>();
+  for (const doc of manifest.docs) {
+    const abs = join(structureDir, doc.path);
+    if (!existsSync(abs)) continue;
+    const body = withoutFences(readFileSync(abs, "utf8"));
+    const found: string[] = [];
+    const re = new RegExp(pathRe.source, "g");
+    let hit: RegExpExecArray | null;
+    while ((hit = re.exec(body))) found.push(hit[1]);
+    namedByDoc.set(doc.path, found);
+  }
+  for (const doc of manifest.docs) {
+    const own = new Set<string>();
+    for (const area of doc.documents) {
+      if (own.has(area)) fail("structure/" + doc.path + " lists " + area + " twice");
+      own.add(area);
+      described.set(area, [...(described.get(area) ?? []), doc.path]);
+      const verdict = pathIsReal(area);
+      if (verdict === "missing") fail("structure/" + doc.path + " claims " + area + ", which this tree does not have");
+      else if (verdict !== "ok") fail("structure/" + doc.path + " claims " + area + ", but the tracked path is " + verdict);
+      const names = namedByDoc.get(doc.path) ?? [];
+      if (!names.some((n) => n === area || n === trimSlash(area) || n.startsWith(area))) {
+        fail("structure/" + doc.path + " claims " + area + " but never names it or a path in it");
+      }
+    }
+  }
+  const graced = new Map(manifest.grace.undocumentedSourceAreas.map((g) => [g.path, g.reason]));
+  for (const g of graced.keys()) {
+    if (pathIsReal(g) !== "ok") fail("grace.undocumentedSourceAreas lists " + g + ", which this tree does not have");
+    if (described.has(g)) fail(g + " is both described and listed as undescribed");
+  }
+  // Enumerated from the index when it is readable, for the same reason paths are resolved there:
+  // an untracked scratch directory under src/ must not produce a failure CI cannot reproduce.
+  const srcAreas = new Set<string>();
+  if (tracked) {
+    for (const p of tracked) {
+      if (!p.startsWith("src/")) continue;
+      const rest = p.slice("src/".length);
+      const slash = rest.indexOf("/");
+      if (slash === -1) {
+        if (rest.endsWith(".ts")) srcAreas.add("src/" + rest);
+      } else srcAreas.add("src/" + rest.slice(0, slash) + "/");
+    }
+  } else if (existsSync(join(repoRoot, "src"))) {
+    for (const entry of readdirSync(join(repoRoot, "src"), { withFileTypes: true })) {
+      if (entry.isDirectory()) srcAreas.add("src/" + entry.name + "/");
+      else if (entry.name.endsWith(".ts")) srcAreas.add("src/" + entry.name);
+    }
+  }
+  for (const area of [...srcAreas].sort()) {
+    // A claim on one file inside a directory does not cover the directory.
+    if (described.has(area) || graced.has(area)) continue;
+    fail(area + " is described by no doc; add it to a doc's " + BT + "documents" + BT + " list or record it in grace.undocumentedSourceAreas with a reason");
+  }
+
+  // 7. generated index parity
+  const indexPath = join(structureDir, "INDEX.md");
+  const expected = renderIndex(manifest);
+  if (!existsSync(indexPath)) fail("structure/INDEX.md is missing; run bun run structure:index");
+  else if (readFileSync(indexPath, "utf8").replace(/\r\n/g, "\n") !== expected) {
+    fail("structure/INDEX.md drifted from manifest.json; run bun run structure:index");
+  }
+
+  return failures;
+}
+
+if (import.meta.main) {
+  const repoRoot = resolve(import.meta.dir, "..");
+  if (process.argv.includes("--fix")) {
+    const manifest = JSON.parse(readFileSync(join(repoRoot, "structure/manifest.json"), "utf8")) as Manifest;
+    writeFileSync(join(repoRoot, "structure/INDEX.md"), renderIndex(manifest), "utf8");
+    console.log("wrote structure/INDEX.md");
+  }
+  const failures = runStructureChecks(repoRoot);
+  if (failures.length === 0) {
+    console.log("structure/ SSOT checks passed");
+    process.exit(0);
+  }
+  for (const f of failures) console.error("  - " + f);
+  console.error(failures.length + " structure/ SSOT failure(s)");
+  process.exit(1);
+}
diff --git a/scripts/test-layout/layout.json b/scripts/test-layout/layout.json
index f83a0a8f49..b2eabcbcc9 100644
--- a/scripts/test-layout/layout.json
+++ b/scripts/test-layout/layout.json
@@ -11,7 +11,7 @@
   "domains": {
     "providers": {
       "match": [
-        "^(?:aside(?!-profile)|auto|azure|baseten|chutes|cline|command|commandcode|context|cyber|deepinfra|deepseek|digitalocean|exa|featherless|forward|hyperbolic|kimi|meta|mimo|minimax|moonshot|muse|new|nous|novita|nscale|nvidia|opencode|openrouter|qwen38|sambanova|umans|vercel|zcode|zhipu)-"
+        "^(?:aside(?!-profile)|auto|azure|baseten|chutes|cline(?!-(?:client|writer))|command|commandcode|context(?!-compat|-history)|cyber|deepinfra|deepseek|digitalocean|exa|featherless|forward|hyperbolic|kimi|meta|mimo|minimax|moonshot|muse|new|nous|novita|nscale|nvidia|opencode|openrouter|qwen38|sambanova|umans|vercel|zcode|zhipu)-"
       ],
       "children": {
         "cursor": [
@@ -33,11 +33,13 @@
     },
     "codex-integration": {
       "match": [
+        "^context-compat\\.test\\.ts$",
         "^(?:active|app|bearer|catalog|combos\\.test\\.ts|doctor\\.test\\.ts|effort|gather|history|injection|issue|multi|native|parallel|project|selected|slug|ultrafast|warmup\\.test\\.ts)-"
       ]
     },
     "server": {
       "match": [
+        "^context-history\\.test\\.ts$",
         "^aside-profiles-routes",
         "^(?:account|alias|bounded|cancel|config\\.test\\.ts|consume|data|debug|error|errors|fetch|health|input|loopback|management|memory|outbound|owned|passive|port|ports\\.test\\.ts|proxy|relay|response|retry|server|session|sidebar|stream|v2)-"
       ]
@@ -109,6 +111,7 @@
     "clients": {
       "match": [
         "^aside-profile(?!s-routes)",
+        "^cline-(?:client|writer)(?:-|[.])",
         "^(?:desktop|omp|pi|prime|remote|sync)-"
       ]
     },
@@ -278,6 +281,7 @@
     "catalog-vision-sidecar-modalities.test.ts": "codex-integration",
     "catalog-zero-credit-picker.test.ts": "codex-integration",
     "chat-completions-endpoint.test.ts": "responses",
+    "chat-conversation-affinity.test.ts": "responses",
     "chat-json-sse-fallback.test.ts": "responses",
     "chat-refusal.test.ts": "responses",
     "chatgpt-device-auth.test.ts": "oauth",
@@ -310,6 +314,7 @@
     "claude-desktop-remote-hub.test.ts": "claude-integration",
     "claude-dotenv-provenance-transport.test.ts": "claude-integration",
     "claude-gateway-cache.test.ts": "claude-integration",
+    "claude-inbound-cache-stabilize.test.ts": "claude-integration",
     "claude-inbound-debug.test.ts": "claude-integration",
     "claude-inbound.test.ts": "claude-integration",
     "claude-management-api.test.ts": "claude-integration",
@@ -317,6 +322,7 @@
     "claude-messages-endpoint.test.ts": "claude-integration",
     "claude-model-info.test.ts": "claude-integration",
     "claude-models-discovery.test.ts": "claude-integration",
+    "claude-native-affinity.test.ts": "claude-integration",
     "claude-native-passthrough.test.ts": "claude-integration",
     "claude-outbound.test.ts": "claude-integration",
     "claude-shell-hook.test.ts": "claude-integration",
@@ -377,10 +383,12 @@
     "client-injection-guard.test.ts": "codex-integration",
     "client-lifecycle-lock.test.ts": "clients",
     "client-machine-listener.test.ts": "clients",
+    "cline-client.test.ts": "clients",
     "cline-pass-deepseek-v4-tool-replay.test.ts": "providers",
     "cline-pass-provider.test.ts": "providers",
     "cline-pass-reasoning-efforts.test.ts": "providers",
     "cline-provider.test.ts": "providers",
+    "cline-writer.test.ts": "clients",
     "closed-pr-branch-cleanup.test.ts": "ci-workflows",
     "codebuddy-adapter.test.ts": "providers",
     "codebuddy-protocol.test.ts": "providers",
@@ -414,6 +422,7 @@
     "codex-cli-update-zero-effect.test.ts": "codex-integration",
     "codex-composed-acceptance.test.ts": "codex-integration",
     "codex-config-generation.test.ts": "codex-integration",
+    "codex-context-owner.test.ts": "codex-integration",
     "codex-convergence-account-selectors.test.ts": "codex-integration",
     "codex-convergence-contract.test.ts": "codex-integration",
     "codex-cooldown-recovery.test.ts": "codex-integration",
@@ -531,6 +540,9 @@
     "consume-for-inspection-cancel.test.ts": "server",
     "container-bootstrap.test.ts": "service",
     "context-cap-unknown-window.test.ts": "providers",
+    "context-compat.test.ts": "codex-integration",
+    "context-history-ownership.test.ts": "server",
+    "context-history.test.ts": "server",
     "continuation-dedup.test.ts": "responses",
     "core-lab-boundary.test.ts": "lab",
     "cost-cap-unknown-evidence.test.ts": "usage",
@@ -619,6 +631,9 @@
     "desktop-profile.test.ts": "clients",
     "desktop-remote-store.test.ts": "clients",
     "destination-policy-resolved.test.ts": "routing",
+    "devin-adapter.test.ts": "providers",
+    "devin-cli-adapter.test.ts": "providers",
+    "devin-hardening.test.ts": "providers",
     "digitalocean-scaleway-provider.test.ts": "providers",
     "docs-429-failover-claims.test.ts": "ci-workflows",
     "docs-bun-source-requirement.test.ts": "ci-workflows",
@@ -665,6 +680,7 @@
     "gemini-inline.test.ts": "images",
     "gemini-web-search.test.ts": "adapters/google",
     "generic-oauth-failover.test.ts": "oauth",
+    "pool-kernel-generic-sweep.test.ts": "oauth",
     "github-copilot-account-origin.test.ts": "providers/github-copilot",
     "github-copilot-oauth.test.ts": "providers/github-copilot",
     "github-copilot-sse-rewrite.test.ts": "providers/github-copilot",
@@ -696,6 +712,8 @@
     "grok-management-api.test.ts": "providers/xai",
     "grok-models-effort-list.test.ts": "providers/xai",
     "grok-orphan-adoption.test.ts": "providers/xai",
+    "grok-reset-coupon-cli.test.ts": "providers/xai",
+    "grok-reset-coupons.test.ts": "providers/xai",
     "grok-selection.test.ts": "providers/xai",
     "grok-status.test.ts": "providers/xai",
     "grok-sync.test.ts": "providers/xai",
@@ -850,6 +868,7 @@
     "model-pinned-effort.test.ts": "codex-integration",
     "model-presets.test.ts": "providers",
     "model-rename-migration.test.ts": "providers",
+    "context-window-seed-repair.test.ts": "providers",
     "model-selection-guidance.test.ts": "cli",
     "model-visibility-management-api.test.ts": "codex-integration",
     "models-feedback-callback.test.ts": "gui",
@@ -926,6 +945,7 @@
     "ollama-show-enrichment-v7.test.ts": "providers/ollama",
     "ollama-show-enrichment.test.ts": "providers/ollama",
     "ollama-show-ignore-abort.test.ts": "providers/ollama",
+    "omo-client.test.ts": "clients",
     "omp-path-contract.test.ts": "clients",
     "omp-yaml-source-inline-comments.test.ts": "clients",
     "openai-api-virtual-models.test.ts": "adapters/openai",
@@ -934,6 +954,7 @@
     "openai-chat-hardening.test.ts": "adapters/openai",
     "openai-chat-invalid-tool-call-diagnostics.test.ts": "adapters/openai",
     "openai-chat-model-suffix.test.ts": "adapters/openai",
+    "openai-chat-path-override.test.ts": "adapters/openai",
     "openai-chat-native-policy.test.ts": "adapters/openai",
     "openai-chat-parallel-stream.test.ts": "adapters/openai",
     "openai-chat-system-order.test.ts": "adapters/openai",
@@ -1042,6 +1063,9 @@
     "release-notes.test.ts": "ci-workflows",
     "release-version-line.test.ts": "ci-workflows",
     "remote-catalog.test.ts": "clients",
+    "remote-control-prototype.test.ts": "clients",
+    "remote-workspace-protocol.test.ts": "clients",
+    "remote-workspace-rpc-framing.test.ts": "clients",
     "remove-tree-helper.test.ts": "lib",
     "repo-hygiene.test.ts": "ci-workflows",
     "request-decompress.test.ts": "usage",
@@ -1180,6 +1204,7 @@
     "sidecar-settings-web-search-stream.test.ts": "vision",
     "sidecar-tracker.test.ts": "vision",
     "skill-ocx.test.ts": "ci-workflows",
+    "structure-ssot.test.ts": "ci-workflows",
     "slug-codec.test.ts": "codex-integration",
     "sponsor-presets.test.ts": "providers",
     "sse-client-frame-bounds.test.ts": "responses",
@@ -1344,7 +1369,9 @@
     "zhipu-bigmodel-responses-quota.test.ts": "providers",
     "zz-ci-api-usage-isolation.test.ts": "ci-workflows",
     "zz-ci-storage-policy-isolation.test.ts": "ci-workflows",
-    "zz-pr-coderabbit-readiness-revalidation.test.ts": "ci-workflows"
+    "zz-pr-coderabbit-readiness-revalidation.test.ts": "ci-workflows",
+    "devin-cli-login.test.ts": "providers",
+    "devin-cli-authmode-migration.test.ts": "providers"
   },
   "migrated": [
     "adapters",
diff --git a/skills/ocx/references/01_management_surface.md b/skills/ocx/references/01_management_surface.md
index 7fcf629e50..f9fec70034 100644
--- a/skills/ocx/references/01_management_surface.md
+++ b/skills/ocx/references/01_management_surface.md
@@ -472,6 +472,28 @@ JSON mode: `payload`.
 
 - CLI/admin-token refreshes only observe usage. After quota recovery, a human must click Refresh quotas in the dashboard to authorize model validation. Do not mint a GUI session to work around this consent boundary.
 
+### `ocx account grok-reset-coupons`
+
+Inspect or redeem Grok billing reset coupons; redemption is journaled and idempotent.
+
+| Method | Route |
+|---|---|
+| GET | `/api/grok/reset-coupons` |
+| POST | `/api/grok/reset-coupons/consume` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--consume` | boolean | Redeem one reset coupon; requires --yes. |
+| `--yes` | boolean | Explicit confirmation required by --consume. |
+| `--token-id` | string | Redeem a specific reset token instead of the default selection. |
+| `--operation-id` | string | UUIDv4 making a redemption idempotent: retries replay the journaled outcome. |
+| `--json` | boolean | Emit the coupon list or redemption result as JSON. |
+
+JSON mode: `payload`.
+
+- Without --consume this is a read: remaining coupons and their validity windows.
+- The operation is journaled before the upstream call, so retrying the same --operation-id replays the recorded outcome instead of spending a second coupon.
+
 ### `ocx account pause`
 
 Stop routing new requests to one account in the Codex pool.
@@ -525,10 +547,9 @@ Show or set how an account pool picks the next account.
 
 | Method | Route |
 |---|---|
-| GET | `/api/codex-auth/active` |
-| PUT | `/api/codex-auth/pool-strategy` |
-| GET | `/api/oauth/accounts/pool` |
-| PUT | `/api/oauth/accounts/pool` |
+| GET | `/api/pool/settings` |
+| PUT | `/api/pool/settings` |
+| PATCH | `/api/pool/settings` |
 
 | Flag | Value | Meaning |
 |---|---|---|
@@ -539,26 +560,46 @@ JSON mode: `envelope`.
 - A bare invocation reads and never writes.
 - The APPLIED value is echoed, not the requested one, so a server-side normalization stays visible.
 - Values are not re-validated in the CLI: the server owns the strategy names and the 1-100 sticky bound.
-- `anthropic` owns the full pool contract. Other OAuth providers reach the same endpoint with a generic subset (enabled/strategy/autoSwitchThreshold) whose settings persist but do not yet steer selection; `sticky` and `quotaWindow` are refused for them.
+- One route answers for every pool kind and declares which fields that kind honours in `supported`, so an unsupported field is a stated null rather than an absence. `anthropic` alone carries `quotaWindow`. Generic-provider settings steer selection only while `pool.kernel` is on. The legacy per-pool paths still work and are unchanged.
 
 ### `ocx account sticky`
 
 Show or set how many consecutive requests stay on one account.
 
+| Method | Route |
+|---|---|
+| GET | `/api/pool/settings` |
+| PUT | `/api/pool/settings` |
+| PATCH | `/api/pool/settings` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the applied strategy and sticky limit as JSON. |
+
+JSON mode: `envelope`.
+
+- Only meaningful under the sticky-capable strategies; the pool strategy is the other half of this setting.
+
+### `ocx account auto-switch`
+
+Show or set the usage percentage at which a pool moves to another account.
+
 | Method | Route |
 |---|---|
 | GET | `/api/codex-auth/active` |
-| PUT | `/api/codex-auth/pool-strategy` |
+| PUT | `/api/codex-auth/auto-switch` |
 | GET | `/api/oauth/accounts/pool` |
 | PUT | `/api/oauth/accounts/pool` |
 
 | Flag | Value | Meaning |
 |---|---|---|
-| `--json` | boolean | Emit the applied strategy and sticky limit as JSON. |
+| `--json` | boolean | Emit the stored threshold and whether it is applied. |
 
 JSON mode: `envelope`.
 
-- Only meaningful under the sticky-capable strategies; the pool strategy is the other half of this setting.
+- A bare invocation reads and never writes.
+- `on` stores 80%, `off` stores 0%, and `threshold <n>` accepts 0-100.
+- For a generic OAuth pool, `inert: true` means the threshold is stored but not applied, `inert: false` means the pool is applying it, and an absent `inert` is an unknown capability.
 
 ### `ocx storage cleanup`
 
@@ -728,6 +769,6 @@ JSON mode: `payload`.
 
 ## Counts
 
-- declared capabilities: 39
-- of those, state-changing: 18
+- declared capabilities: 41
+- of those, state-changing: 20
 - head-resolved invocations: 2
diff --git a/src/AGENTS.md b/src/AGENTS.md
index 9347a655fe..63fdea93f7 100644
--- a/src/AGENTS.md
+++ b/src/AGENTS.md
@@ -8,7 +8,7 @@ This file applies to `src/` and inherits the repository-wide rules in `/AGENTS.m
 - Do not assume a separate server compilation step.
 - Prefer Bun and Web-platform APIs. Introduce a Node-only runtime dependency only when the task explicitly requires compatibility code and the owning module already has that role.
 - Preserve existing public exports and configuration compatibility unless the task explicitly changes them.
-- Read the applicable documents in `structure/` before changing shared routing, adapters, transports, sidecars, authentication, configuration, or server architecture.
+- Read the applicable documents in `structure/` before changing shared routing, adapters, transports, sidecars, authentication, configuration, or server architecture. [`structure/INDEX.md`](../structure/INDEX.md) maps each source area to the docs that describe it — usually more than one, because those docs are organised by topic while `src/` is organised by module — and every doc listed for an area is updated in the same change that changes the area.
 
 ## Implementation rules
 
diff --git a/src/adapters/cline-pass-deepseek-v4-tool-replay.ts b/src/adapters/cline-pass-deepseek-v4-tool-replay.ts
index e2d0369974..cf28da46fe 100644
--- a/src/adapters/cline-pass-deepseek-v4-tool-replay.ts
+++ b/src/adapters/cline-pass-deepseek-v4-tool-replay.ts
@@ -2,7 +2,6 @@ import type { ProviderAdapter } from "./base";
 
 const CLINE_PASS_DEEPSEEK_V4_MODELS = new Set([
   "cline-pass/deepseek-v4-flash",
-  "cline-pass/deepseek-v4-pro",
 ]);
 
 function isRecord(value: unknown): value is Record<string, unknown> {
diff --git a/src/adapters/command-code.ts b/src/adapters/command-code.ts
index c20dc88be6..4b7c707d7e 100644
--- a/src/adapters/command-code.ts
+++ b/src/adapters/command-code.ts
@@ -495,7 +495,6 @@ function supportedCommandCodeEffort(provider: OcxProviderConfig, modelId: string
   let wire = requested;
   const lower = canonicalId.toLowerCase();
   const needsAlias =
-    lower === "deepseek/deepseek-v4-pro" ||
     lower === "deepseek/deepseek-v4-flash" ||
     lower === "zai-org/glm-5.2";
   if (requested === "xhigh" && !supported.includes("xhigh") && supported.includes("max")) {
diff --git a/src/adapters/cursor.ts b/src/adapters/cursor.ts
index 157da1eaa3..7382c25d8c 100644
--- a/src/adapters/cursor.ts
+++ b/src/adapters/cursor.ts
@@ -24,9 +24,11 @@ import {
 import {
   commitCursorCheckpoint,
   cursorCheckpointRefHash,
+  cursorCheckpointShape,
   invalidateCursorCheckpoint,
 } from "./cursor/checkpoint-store";
 import { debugProviderDiagnostic } from "../lib/debug";
+import { isDebugEnabled } from "../lib/debug-settings";
 import { createAdapterTierMetadata } from "../providers/fastwire";
 import { estimateTokens } from "../lib/token-estimate";
 import { rememberCursorThreadConversation } from "./cursor/thread-continuity";
@@ -208,6 +210,10 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
               externalModel: isCursorExternalWireModel(activeRequest.modelId),
               storeCheckpoints: activeRequest.contextUsageStoreCheckpoints !== false,
               capturedBytes: lastTransport?.captured?.byteLength ?? 0,
+              // Byte length says nothing about coverage. `pendingToolCalls` does: it is what
+              // distinguishes a snapshot that knows about the suspended call from one that merely
+              // arrived after it (#4245). Counts only; the decode is skipped unless debug is on.
+              capturedShape: isDebugEnabled() ? cursorCheckpointShape(lastTransport?.captured) : undefined,
             });
             return;
           }
diff --git a/src/adapters/cursor/checkpoint-store.ts b/src/adapters/cursor/checkpoint-store.ts
index 720bc8dc2e..758430064f 100644
--- a/src/adapters/cursor/checkpoint-store.ts
+++ b/src/adapters/cursor/checkpoint-store.ts
@@ -184,6 +184,43 @@ export function cursorCheckpointRefHash(ref: string): string {
   return createHash("sha256").update("ocx:cursor:ckpt-ref:").update(ref).digest("hex").slice(0, 16);
 }
 
+/**
+ * Counts only — never content. Diagnostics about a checkpoint have so far reported its size in
+ * bytes, which says nothing about what is in it, and that gap is exactly what left #4245's native
+ * half undecidable: `capturedAfterClientTool` proves a snapshot ARRIVED after the tool call, and
+ * only `pendingToolCalls` says whether the snapshot actually knows about one.
+ *
+ * `pendingToolCalls` is documented upstream as raw JSON tool-call parts awaiting execution, so a
+ * non-zero count on a suspended turn is the coverage evidence. The strings themselves are request
+ * content and are never read here.
+ *
+ * If you extend this, keep it counts-only. `ConversationStateStructure` also carries
+ * `readPaths`, `previousWorkspaceUris`, and the `fileStates`/`fileStatesV2` keys — all of which
+ * are user paths or workspace identity, and all of which would turn a diagnostic into a privacy
+ * leak the moment someone returns them as values instead of lengths.
+ */
+export function cursorCheckpointShape(checkpointBytes: Uint8Array | undefined): {
+  turns: number;
+  turnsOld: number;
+  rootPromptMessages: number;
+  todos: number;
+  pendingToolCalls: number;
+} | undefined {
+  if (!checkpointBytes || checkpointBytes.byteLength === 0) return undefined;
+  try {
+    const state = fromBinary(ConversationStateStructureSchema, checkpointBytes);
+    return {
+      turns: state.turns.length,
+      turnsOld: state.turnsOld.length,
+      rootPromptMessages: state.rootPromptMessagesJson.length,
+      todos: state.todos.length,
+      pendingToolCalls: state.pendingToolCalls.length,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
 export function commitCursorCheckpoint(input: {
   conversationId: string;
   identityScope?: string;
diff --git a/src/adapters/cursor/live-transport.ts b/src/adapters/cursor/live-transport.ts
index 355f9be18f..2d6385ae77 100644
--- a/src/adapters/cursor/live-transport.ts
+++ b/src/adapters/cursor/live-transport.ts
@@ -115,6 +115,15 @@ const CLIENT_TOOL_FINALIZE_GRACE_MS = 50;
 const GENERIC_TOOL_COUNT_MIN_FINALIZE_GRACE_MS = 750;
 const GENERIC_TOOL_COUNT_MAX_FINALIZE_GRACE_MS = 1_800;
 const GENERIC_TOOL_COUNT_PER_TOOL_GRACE_MS = 125;
+/**
+ * A client-tool turn suspends before `turnEnded`, and upstream sends that turn's conversation
+ * checkpoint right after `toolCallStarted` — after the 50 ms drain grace, so it used to be
+ * cancelled away and every such turn full-replayed with `cached_tokens: 0`. Measured on a live
+ * account with the tool catalog held constant: 50 ms captures nothing, 1500 ms captures 3036
+ * bytes (#4245, devlog 260911_cursor_checkpoint_capture). This window is paid only by a turn
+ * that never sends one; `handleServerMessage` finalizes early as soon as the frame lands.
+ */
+const CHECKPOINT_CAPTURE_GRACE_MS = 1_500;
 const cursorContextUsageTracker = createCursorContextUsageTracker();
 
 /**
@@ -413,6 +422,28 @@ export function finalizeAfterDrain(state: ReturnType<typeof createCursorProtobuf
   return finalizeTurnEvents(state);
 }
 
+/**
+ * Whether a drained client-tool turn should wait one more bounded window for the conversation
+ * checkpoint instead of cancelling now.
+ *
+ * This mirrors `finalizeAfterDrain`'s two guards rather than calling it, and that is load-bearing:
+ * `finalizeAfterDrain` reaches `finalizeTurnEvents`, which sets `state.terminated`, and then returns
+ * `[]` for a terminated state. Draining first and re-arming would make the retry return early at the
+ * length check and leave the stream uncancelled. Pure for unit testing.
+ */
+export function shouldExtendForCheckpointCapture(input: {
+  /** Optional on the event state, so accept its real shape rather than forcing a cast at the call site. */
+  terminated: boolean | undefined;
+  openToolCallCount: number;
+  wantsCheckpointCapture: boolean;
+  hasCapturedCheckpoint: boolean;
+  alreadyExtended: boolean;
+}): boolean {
+  if (input.terminated || input.openToolCallCount > 0) return false;
+  if (!input.wantsCheckpointCapture || input.hasCapturedCheckpoint) return false;
+  return !input.alreadyExtended;
+}
+
 export function clientToolFinalizeGraceMsForRequest(request: CursorRunRequest, baseGraceMs = CLIENT_TOOL_FINALIZE_GRACE_MS): number {
   if (request.rawMessages?.at(-1)?.role === "toolResult") return baseGraceMs;
   const text = activePromptText(request);
@@ -468,6 +499,10 @@ class LiveCursorTransport implements CursorTransport {
    */
   private emittedTerminal = false;
   private pendingFinalize?: ReturnType<typeof setTimeout>;
+  /** The armed finalize body, so the checkpoint frame can run it early instead of waiting out the window. */
+  private pendingFinalizeRun?: () => void;
+  private checkpointGraceExtended = false;
+  private wantsCheckpointCapture = false;
   private readonly clientToolFinalizeGraceMs: number;
   private activeClientToolFinalizeGraceMs: number;
   private readonly token: string;
@@ -641,6 +676,7 @@ class LiveCursorTransport implements CursorTransport {
     };
     const activeText = activePromptText(activeRequest);
     this.activeClientToolFinalizeGraceMs = clientToolFinalizeGraceMsForRequest(activeRequest, this.clientToolFinalizeGraceMs);
+    this.wantsCheckpointCapture = activeRequest.contextUsageStoreCheckpoints !== false;
     const cursorVisibleTools = cursorToolsForActivePrompt(activeRequest.tools, activeText, activeRequest.toolChoice);
     const clientToolDefs = buildCursorToolDefinitions(cursorVisibleTools, activeRequest.toolChoice);
     // `request.tools` is the catalog already filtered and budgeted by request-builder. Derive
@@ -981,6 +1017,7 @@ class LiveCursorTransport implements CursorTransport {
       clearTimeout(this.pendingFinalize);
       this.pendingFinalize = undefined;
     }
+    this.pendingFinalizeRun = undefined;
   }
 
   /**
@@ -1001,11 +1038,26 @@ class LiveCursorTransport implements CursorTransport {
   private scheduleClientToolFinalize(
     state: ReturnType<typeof createCursorProtobufEventState>,
     push: (message: CursorServerMessage) => void,
+    graceMsOverride?: number,
   ): void {
     this.clearPendingFinalize();
-    this.pendingFinalize = setTimeout(() => {
+    const run = (): void => {
       this.pendingFinalize = undefined;
+      this.pendingFinalizeRun = undefined;
       if (this.expectedClose) return;
+      // The checkpoint for THIS turn is the one we most want and the one we used to throw
+      // away. Extend once, bounded, before draining (#4245).
+      if (shouldExtendForCheckpointCapture({
+        terminated: state.terminated,
+        openToolCallCount: state.openToolCalls.size,
+        wantsCheckpointCapture: this.wantsCheckpointCapture,
+        hasCapturedCheckpoint: this.capturedCheckpointBytes !== undefined,
+        alreadyExtended: this.checkpointGraceExtended,
+      })) {
+        this.checkpointGraceExtended = true;
+        this.scheduleClientToolFinalize(state, push, CHECKPOINT_CAPTURE_GRACE_MS);
+        return;
+      }
       const terminal = finalizeAfterDrain(state);
       if (terminal.length === 0) return;
       for (const event of terminal) push(event);
@@ -1013,9 +1065,13 @@ class LiveCursorTransport implements CursorTransport {
         reason: "Responses bridge owns client tools; ending turn without fake mcpResult",
         framesReceived: this.framesReceived,
         elapsedMs: Date.now() - this.turnStartedAt,
+        graceMs: graceMsOverride ?? this.activeClientToolFinalizeGraceMs,
+        checkpointGraceExtended: this.checkpointGraceExtended,
       });
       this.cancelCursorRun();
-    }, this.activeClientToolFinalizeGraceMs);
+    };
+    this.pendingFinalizeRun = run;
+    this.pendingFinalize = setTimeout(run, graceMsOverride ?? this.activeClientToolFinalizeGraceMs);
   }
 
   private open(
@@ -1032,6 +1088,10 @@ class LiveCursorTransport implements CursorTransport {
     }
     this.turnStartedAt = Date.now();
     this.framesReceived = 0;
+    this.checkpointGraceExtended = false;
+    // A turn must not inherit the previous one's snapshot: a stale capture would make
+    // shouldExtendForCheckpointCapture skip the wait this turn actually needs.
+    this.capturedCheckpointBytes = undefined;
     this.sawAssistantText = false;
     this.emittedTerminal = false;
     this.firstFrameAt = undefined;
@@ -1450,6 +1510,18 @@ class LiveCursorTransport implements CursorTransport {
       } catch {
         this.capturedCheckpointBytes = undefined;
       }
+      // We are only still open because the grace was extended waiting for exactly this frame.
+      // Stop waiting, so a turn that does send a checkpoint pays arrival latency rather than the
+      // whole window. Deferred one tick so this frame finishes being mapped and pushed first;
+      // finalizing inline would emit the terminal events ahead of it.
+      if (this.checkpointGraceExtended && this.pendingFinalizeRun && this.capturedCheckpointBytes) {
+        const run = this.pendingFinalizeRun;
+        this.clearPendingFinalize();
+        this.pendingFinalize = setTimeout(run, 0);
+        // Keep the pair in step: clearPendingFinalize() drops the callback, and every other
+        // owner of pendingFinalize expects pendingFinalizeRun to describe it.
+        this.pendingFinalizeRun = run;
+      }
     }
     if (message.message.case === "kvServerMessage") {
       this.writeConnectFrame(encodeConnectFrame(handleCursorNativeKv(message.message.value, this.blobRequestScope)));
diff --git a/src/adapters/devin-cli/acp.ts b/src/adapters/devin-cli/acp.ts
new file mode 100644
index 0000000000..28bd4fc6b0
--- /dev/null
+++ b/src/adapters/devin-cli/acp.ts
@@ -0,0 +1,204 @@
+/**
+ * Agent Client Protocol framing for the Devin CLI.
+ *
+ * `devin acp` speaks newline-delimited JSON-RPC on stdin/stdout. One ACP session
+ * answers one prompt, so a turn is: initialize -> session/new -> session/prompt,
+ * with session/update notifications streaming in between and a unary reply to
+ * the prompt carrying the stop reason and usage.
+ *
+ * This module is pure. It never spawns a process and never touches the network,
+ * so the framing and the event mapping are testable against captured lines, the
+ * same discipline src/adapters/coding-agent/protocol.ts follows for the
+ * stream-json CLIs.
+ */
+import type { AdapterEvent, OcxParsedRequest, OcxToolCall, OcxUsage } from "../../types";
+
+/** Hard ceiling on a single buffered stdout line. */
+export const MAX_ACP_LINE_BYTES = 8 * 1024 * 1024;
+/** Hard ceiling on total stdout bytes consumed for one turn. */
+export const MAX_ACP_TOTAL_BYTES = 64 * 1024 * 1024;
+
+export class AcpProtocolError extends Error {
+  readonly code = "protocol_error";
+  readonly status = 502;
+  constructor(message: string) {
+    super(message);
+    this.name = "AcpProtocolError";
+  }
+}
+
+export const ACP_INITIALIZE_ID = 1;
+export const ACP_SESSION_NEW_ID = 2;
+export const ACP_SESSION_PROMPT_ID = 3;
+
+export function initializeFrame(clientVersion: string): Record<string, unknown> {
+  return {
+    jsonrpc: "2.0",
+    id: ACP_INITIALIZE_ID,
+    method: "initialize",
+    params: { protocolVersion: 1, clientInfo: { name: "opencodex", version: clientVersion }, capabilities: {} },
+  };
+}
+
+export function sessionNewFrame(cwd: string, modelId?: string): Record<string, unknown> {
+  const params: Record<string, unknown> = { cwd, mcpServers: [] };
+  // The CLI picks its own default when no model is named, which is what an
+  // unset or vendor-default selection should do.
+  if (modelId) params.model = modelId;
+  return { jsonrpc: "2.0", id: ACP_SESSION_NEW_ID, method: "session/new", params };
+}
+
+export function sessionPromptFrame(sessionId: string, prompt: string): Record<string, unknown> {
+  return {
+    jsonrpc: "2.0",
+    id: ACP_SESSION_PROMPT_ID,
+    method: "session/prompt",
+    params: { sessionId, prompt: [{ type: "text", text: prompt }] },
+  };
+}
+
+/**
+ * Answer a permission request without a human.
+ *
+ * A headless turn has nobody to approve a tool call, and an unanswered
+ * `session/request_permission` stalls the agent until the turn times out. The
+ * answer is a refusal by default: this provider runs an agent in the operator's
+ * own tree, and auto-approving whatever it asks for would let any prompt that
+ * reaches the proxy read, write and execute there. Approval is an explicit
+ * operator decision, and only then is an allow-shaped option preferred over
+ * positional guessing — the first option in a real prompt is sometimes the
+ * rejection.
+ */
+export function permissionResponseFrame(
+  id: number | string,
+  options: Array<{ optionId?: string; name?: string; kind?: string }> | undefined,
+  allowed = false,
+): Record<string, unknown> {
+  if (!allowed) {
+    return { jsonrpc: "2.0", id, result: { outcome: { outcome: "cancelled" } } };
+  }
+  const list = options ?? [];
+  const allow =
+    list.find((o) => typeof o.kind === "string" && /^allow/i.test(o.kind)) ??
+    list.find((o) => /allow|accept|yes/i.test(`${o.optionId ?? ""} ${o.name ?? ""}`));
+  if (!allow?.optionId) {
+    // Nothing offered says "allow". Guessing at `list[0]` here is how an
+    // auto-answer selects a rejection and calls it approval.
+    return { jsonrpc: "2.0", id, result: { outcome: { outcome: "cancelled" } } };
+  }
+  return { jsonrpc: "2.0", id, result: { outcome: { outcome: "selected", optionId: allow.optionId } } };
+}
+
+/**
+ * Flatten an OcxContext into the single prompt string one ACP session takes.
+ *
+ * ACP has no multi-message history on session/prompt, so the conversation is
+ * projected into labelled blocks. Tool calls and results are rendered rather
+ * than dropped, because a turn that omits them loses the thread of a tool loop.
+ */
+export function buildAcpPrompt(parsed: OcxParsedRequest): string {
+  const blocks: string[] = [];
+  const system = parsed.context.systemPrompt?.filter((line) => line.trim().length > 0).join("\n");
+  if (system) blocks.push(fence("System", system));
+  for (const message of parsed.context.messages) {
+    if (message.role === "toolResult") {
+      const body = typeof message.content === "string" ? message.content : JSON.stringify(message.content ?? "");
+      blocks.push(fence("Tool", `[result id=${message.toolCallId}]\n${body}`));
+      continue;
+    }
+    const parts = typeof message.content === "string" ? [] : message.content;
+    let text = typeof message.content === "string"
+      ? message.content
+      : parts.map((p) => (p.type === "text" ? p.text : "")).filter(Boolean).join("\n");
+    if (message.role === "assistant" && Array.isArray(parts)) {
+      const calls = parts
+        .filter((p): p is OcxToolCall => p.type === "toolCall")
+        .map((c) => `[call ${c.name} id=${c.id}]\n${JSON.stringify(c.arguments ?? {})}`)
+        .join("\n\n");
+      if (calls) text = text ? `${text}\n\n${calls}` : calls;
+    }
+    if (!text.trim()) continue;
+    const label = message.role === "assistant" ? "Assistant" : message.role === "developer" ? "System" : "User";
+    blocks.push(fence(label, text));
+  }
+  if (blocks.length === 0) return "(empty)";
+  const joined = blocks.join("\n\n");
+  // Keep the oldest turns rather than the newest when trimming: the tail is
+  // what the agent is answering.
+  return joined.length > MAX_ACP_PROMPT_CHARS
+    ? `[truncated]\n${joined.slice(joined.length - MAX_ACP_PROMPT_CHARS)}`
+    : joined;
+}
+
+export type AcpTurnOutcome = { stopReason?: string; usage?: OcxUsage };
+
+/** ACP stop reasons that mean the turn ended normally. */
+const NATURAL_STOP = new Set(["end_turn", "stop", "completed"]);
+
+export function mapAcpStopReason(reason: unknown): string | undefined {
+  if (typeof reason !== "string" || NATURAL_STOP.has(reason)) return undefined;
+  if (reason === "max_tokens") return "max_tokens";
+  return reason;
+}
+
+export function mapAcpUsage(raw: unknown): OcxUsage | undefined {
+  if (!raw || typeof raw !== "object") return undefined;
+  const u = raw as Record<string, unknown>;
+  const input = typeof u.inputTokens === "number" ? u.inputTokens : 0;
+  const output = typeof u.outputTokens === "number" ? u.outputTokens : 0;
+  if (input === 0 && output === 0) return undefined;
+  const total = typeof u.totalTokens === "number" ? u.totalTokens : input + output;
+  return { inputTokens: input, outputTokens: output, ...(total > 0 ? { totalTokens: total } : {}) };
+}
+
+function chunkText(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (content && typeof content === "object") {
+    const text = (content as { text?: unknown }).text;
+    if (typeof text === "string") return text;
+  }
+  return "";
+}
+
+/**
+ * Translate one session/update notification into adapter events.
+ *
+ * Tool lifecycle is explicit in ACP: `tool_call` opens one and
+ * `tool_call_update` with a terminal status closes it, so the caller does not
+ * have to infer boundaries from interleaving the way a delta-only wire forces.
+ */
+export function acpUpdateToEvents(update: Record<string, unknown>): AdapterEvent[] {
+  const kind = update.sessionUpdate;
+  if (kind === "agent_message_chunk") {
+    const text = chunkText(update.content);
+    return text ? [{ type: "text_delta", text }] : [];
+  }
+  if (kind === "agent_thought_chunk") {
+    const text = chunkText(update.content);
+    return text ? [{ type: "thinking_delta", thinking: text }] : [];
+  }
+  // The CLI's own tool calls are NOT client tools. Devin executes them itself
+  // inside its session, so emitting tool_call_start here would either fail the
+  // turn — the Responses bridge rejects a tool Codex never declared — or ask
+  // Codex to run something the agent has already run. Vendor tools stay
+  // internal and Codex keeps ownership of mutation, which is the same rule the
+  // CodeBuddy and Qoder adapters follow.
+  //
+  // They are not dropped silently, though. A Devin tool operation that runs
+  // longer than the bridge's stall timeout would otherwise look like upstream
+  // silence and get the still-working turn aborted, so an internal update
+  // becomes a heartbeat: proof of life without a client-visible tool.
+  if (kind === "tool_call" || kind === "tool_call_update" || kind === "plan" || kind === "current_mode_update") {
+    return [{ type: "heartbeat" }];
+  }
+  return [];
+}
+/** Ceiling on the flattened conversation handed to one ACP prompt. */
+export const MAX_ACP_PROMPT_CHARS = 200_000;
+
+/** Fence a block label so a message body cannot forge one. */
+function fence(label: string, body: string): string {
+  // A user or tool result that contains a line reading `[System]` would
+  // otherwise appear to open a system block in the flattened prompt.
+  return `[${label}]\n${body.replace(/^\[(System|User|Assistant|Tool)\]/gm, " $&")}`;
+}
diff --git a/src/adapters/devin-cli/adapter.ts b/src/adapters/devin-cli/adapter.ts
new file mode 100644
index 0000000000..f31bf77373
--- /dev/null
+++ b/src/adapters/devin-cli/adapter.ts
@@ -0,0 +1,345 @@
+/**
+ * Devin CLI adapter: one ACP session per turn over stdio.
+ *
+ * This is the local half of Devin support. The cloud-direct `devin` adapter
+ * talks to Cognition's api-server; this one drives the installed `devin` CLI,
+ * which carries its own credentials from `devin auth login`, so the proxy never
+ * sees a token for this provider.
+ *
+ * runTurn-only, like the Cursor and cloud Devin adapters: a JSON-RPC handshake
+ * over a child process has no fetch-shaped request to hand to the generic wire
+ * path.
+ *
+ * The child is treated as untrusted and unprivileged. It gets a scoped
+ * environment rather than the proxy's, its permission requests are refused
+ * unless an operator opted in, and it is reaped rather than merely signalled,
+ * because a Devin grandchild that ignores SIGTERM would otherwise keep writing
+ * in the operator's tree after the turn returned.
+ */
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import type { AdapterEvent, OcxParsedRequest, OcxProviderConfig, OcxUsage } from "../../types";
+import type { IncomingMeta, ProviderAdapter } from "../base";
+import { baseScopedEnv } from "../coding-agent/turn";
+import {
+  ACP_INITIALIZE_ID,
+  ACP_SESSION_NEW_ID,
+  ACP_SESSION_PROMPT_ID,
+  MAX_ACP_LINE_BYTES,
+  MAX_ACP_TOTAL_BYTES,
+  acpUpdateToEvents,
+  buildAcpPrompt,
+  initializeFrame,
+  mapAcpStopReason,
+  mapAcpUsage,
+  permissionResponseFrame,
+  sessionNewFrame,
+  sessionPromptFrame,
+} from "./acp";
+import { DEVIN_CLI_INSTALL_HINT, resolveDevinCliBinary } from "./binary";
+
+/** A turn that has not produced a prompt reply by this point is abandoned. */
+const DEVIN_CLI_TURN_TIMEOUT_MS = 10 * 60 * 1000;
+/** Grace between SIGTERM and SIGKILL when reaping the child. */
+const DEVIN_CLI_KILL_GRACE_MS = 2_000;
+/** How long to wait for the child to actually exit before giving up on it. */
+const DEVIN_CLI_REAP_MS = 5_000;
+
+/**
+ * Identity URL for the provider. The CLI does the real transport over stdio;
+ * this is only what the configuration records as the destination, and it has to
+ * be an http(s) URL because provider config validation rejects other schemes.
+ */
+export const DEVIN_CLI_IDENTITY_URL = "https://cli.devin.ai";
+
+/**
+ * Opt-in for letting the CLI act on the machine.
+ *
+ * Off by default: this provider runs an agent in the operator's own tree, and a
+ * proxy that auto-approves whatever a prompt asks for is a remote shell.
+ */
+const DEVIN_CLI_ALLOW_TOOLS_ENV = "OPENCODEX_DEVIN_CLI_ALLOW_TOOLS";
+
+export type DevinCliSpawn = (binary: string, args: string[], options: { cwd: string; env: Record<string, string> }) => ChildProcessWithoutNullStreams;
+
+export function devinCliToolsAllowed(env: NodeJS.ProcessEnv = process.env): boolean {
+  const raw = env[DEVIN_CLI_ALLOW_TOOLS_ENV]?.trim().toLowerCase();
+  return raw === "1" || raw === "true" || raw === "yes";
+}
+
+export function createDevinCliAdapter(provider: OcxProviderConfig, deps?: { spawn?: DevinCliSpawn }): ProviderAdapter {
+  const spawnChild: DevinCliSpawn = deps?.spawn
+    ?? ((binary, args, options) => spawn(binary, args, {
+      ...options,
+      stdio: ["pipe", "pipe", "pipe"],
+      windowsHide: true,
+      // Give the child its own process group on POSIX so the reap below can
+      // signal the whole tree. Devin spawns shells and tools of its own when
+      // the operator allows them, and signalling only the direct pid leaves
+      // those descendants writing in the operator's tree after the turn ended.
+      detached: process.platform !== "win32",
+    }) as ChildProcessWithoutNullStreams);
+
+  return {
+    name: "devin-cli",
+
+    buildRequest() {
+      // Placeholder: this adapter never travels the fetch path. The URL is the
+      // provider's identity, not a destination anything connects to.
+      return { url: provider.baseUrl || DEVIN_CLI_IDENTITY_URL, method: "POST", headers: {}, body: "" };
+    },
+
+    async *parseStream(): AsyncGenerator<AdapterEvent> {
+      yield { type: "error", message: "Devin CLI adapter uses runTurn; the fetch/parseStream path is disabled." };
+    },
+
+    async runTurn(parsed: OcxParsedRequest, incoming: IncomingMeta, emit: (event: AdapterEvent) => void) {
+      if (incoming.abortSignal?.aborted) {
+        emit({ type: "error", message: "Devin CLI turn was aborted before start." });
+        return;
+      }
+      const binary = resolveDevinCliBinary();
+      if (!binary) {
+        emit({ type: "error", message: `Devin CLI not found. ${DEVIN_CLI_INSTALL_HINT}` });
+        return;
+      }
+
+      const modelId = parsed.modelId.includes("/")
+        ? parsed.modelId.slice(parsed.modelId.lastIndexOf("/") + 1)
+        : parsed.modelId;
+      const cwd = process.env.OPENCODEX_DEVIN_CLI_CWD?.trim() || process.cwd();
+      const toolsAllowed = devinCliToolsAllowed();
+
+      await new Promise<void>((resolve) => {
+        let child: ChildProcessWithoutNullStreams;
+        try {
+          child = spawnChild(binary, ["acp"], {
+            cwd,
+            env: {
+              // A scoped environment, not the proxy's. The child would
+              // otherwise inherit every credential this process holds.
+              ...baseScopedEnv(),
+              NO_COLOR: "1",
+              // "normal" is the CLI's own refuse-by-default mode. "ask" reads like
+              // the right name for it but is not a value the binary accepts: Devin
+              // CLI 3000.10.21 exits 2 with
+              //   invalid value 'ask' for '--permission-mode <PERMISSION_MODE>'
+              //   Valid options: normal (auto), accept-edits, dangerous (yolo,
+              //   bypass), autonomous (requires --sandbox)
+              // before answering a single prompt, so every turn on this provider
+              // failed with the default (tools not allowed) configuration — the
+              // one path most operators are on. Found by running a real turn
+              // against an installed, signed-in CLI; no unit test could see it,
+              // because the spawn is injected and the fake child accepts anything.
+              DEVIN_PERMISSION_MODE: toolsAllowed ? (process.env.DEVIN_PERMISSION_MODE ?? "bypass") : "normal",
+            },
+          });
+        } catch (error) {
+          emit({ type: "error", message: `Devin CLI failed to start (${binary}): ${(error as Error).message}. ${DEVIN_CLI_INSTALL_HINT}` });
+          return resolve();
+        }
+
+        let settled = false;
+        let closed = false;
+        let sawProtocolFrame = false;
+        let sawPromptReply = false;
+        let buffer = "";
+        let totalBytes = 0;
+        let usage: OcxUsage | undefined;
+        let stopReason: string | undefined;
+        let stderrTail = "";
+
+        const turnTimer = setTimeout(
+          () => finish(`Devin CLI turn exceeded ${DEVIN_CLI_TURN_TIMEOUT_MS}ms`),
+          DEVIN_CLI_TURN_TIMEOUT_MS,
+        );
+        const onAbort = () => finish("Devin CLI turn was aborted.");
+
+        /**
+         * Reap the child rather than just signalling it, then resolve.
+         *
+         * `child.killed` only records that a signal was sent. Resolving on that
+         * lets a grandchild keep running in the operator's tree after runTurn
+         * returned, which is why this waits for `close` and escalates.
+         */
+        function reapAndResolve(): void {
+          if (closed || child.exitCode !== null || child.signalCode !== null) return resolve();
+          let done = false;
+          const settle = () => {
+            if (done) return;
+            done = true;
+            clearTimeout(killTimer);
+            clearTimeout(reapTimer);
+            resolve();
+          };
+          child.once("close", settle);
+          signalTree("SIGTERM");
+          const killTimer = setTimeout(() => signalTree("SIGKILL"), DEVIN_CLI_KILL_GRACE_MS);
+          const reapTimer = setTimeout(settle, DEVIN_CLI_REAP_MS);
+        }
+
+        /**
+         * Signal the child's whole process group where the platform has one.
+         * Devin launches shells and tools of its own once the operator allows
+         * them, and those descendants do not receive a signal aimed at the
+         * direct pid. Falls back to the single process when the group send is
+         * unavailable or the group is already gone.
+         */
+        function signalTree(signal: NodeJS.Signals): void {
+          const pid = child.pid;
+          if (pid !== undefined && process.platform !== "win32") {
+            try {
+              process.kill(-pid, signal);
+              return;
+            } catch { /* no group, or already reaped - fall through */ }
+          }
+          try { child.kill(signal); } catch { /* already gone */ }
+        }
+
+        /** Terminate the turn exactly once, with an error when given a reason. */
+        function finish(errorMessage?: string): void {
+          if (settled) return;
+          settled = true;
+          clearTimeout(turnTimer);
+          incoming.abortSignal?.removeEventListener("abort", onAbort);
+          child.stdout.destroy();
+          if (errorMessage) emit({ type: "error", message: errorMessage, ...(usage ? { usage } : {}) });
+          else emit({ type: "done", ...(usage ? { usage } : {}), ...(stopReason ? { stopReason } : {}) });
+          reapAndResolve();
+        }
+
+        incoming.abortSignal?.addEventListener("abort", onAbort, { once: true });
+        // The signal can fire between the pre-spawn check and this listener.
+        if (incoming.abortSignal?.aborted) return finish("Devin CLI turn was aborted.");
+
+        const send = (frame: Record<string, unknown>): void => {
+          if (!child.stdin.destroyed) child.stdin.write(`${JSON.stringify(frame)}\n`);
+        };
+        // EPIPE after the child is killed is an ordinary race, not a crash.
+        child.stdin.on("error", () => {});
+
+        child.on("error", (err) => finish(`Devin CLI failed to start (${binary}): ${err.message}. ${DEVIN_CLI_INSTALL_HINT}`));
+
+        child.on("close", (code) => {
+          closed = true;
+          if (settled) return;
+          // Flush a final frame that arrived without a trailing newline before
+          // deciding the turn failed: the prompt reply carrying usage and the
+          // stop reason is often the last line written.
+          flush(buffer);
+          buffer = "";
+          if (settled) return;
+          // A close without a prompt reply is a failure, not an empty success.
+          const detail = stderrTail.trim().slice(-400);
+          finish(
+            `Devin CLI exited (code ${code ?? "null"}) before answering the prompt` +
+            (detail ? `: ${detail}` : "."),
+          );
+        });
+
+        child.stderr?.setEncoding("utf8");
+        child.stderr?.on("data", (chunk: string) => {
+          // Bounded: diagnostics are for the error message, not a buffer to grow.
+          stderrTail = (stderrTail + chunk).slice(-4096);
+        });
+
+        child.stdout.setEncoding("utf8");
+        child.stdout.on("data", (chunk: string) => {
+          if (settled) return;
+          totalBytes += Buffer.byteLength(chunk, "utf8");
+          if (totalBytes > MAX_ACP_TOTAL_BYTES) return finish("Devin CLI produced more output than one turn may consume.");
+          buffer += chunk;
+          let index: number;
+          while ((index = buffer.indexOf("\n")) >= 0) {
+            const line = buffer.slice(0, index);
+            buffer = buffer.slice(index + 1);
+            flush(line);
+            if (settled) return;
+          }
+          if (Buffer.byteLength(buffer, "utf8") > MAX_ACP_LINE_BYTES) {
+            finish("Devin CLI emitted a single line larger than the frame cap.");
+          }
+        });
+
+        // The prompt reply carrying usage and the stop reason is often the last
+        // thing written, and it is not guaranteed to end with a newline. Flush
+        // the remainder when the stream ends rather than waiting for the child
+        // to exit and then calling a complete turn a failure.
+        child.stdout.on("end", () => {
+          const tail = buffer;
+          buffer = "";
+          flush(tail);
+        });
+
+        function flush(raw: string): void {
+          const line = raw.trim();
+          if (!line || settled) return;
+          let frame: Record<string, unknown>;
+          try {
+            frame = JSON.parse(line) as Record<string, unknown>;
+          } catch {
+            // The CLI prints a banner before the protocol starts, so plain text
+            // is expected up to the first valid frame. After that the stream is
+            // protocol, and a line that is shaped like a frame but does not
+            // parse is corruption: dropping it silently loses a session/update
+            // or lets the turn wait out the timeout for a reply that already
+            // arrived damaged.
+            if (sawProtocolFrame || line.startsWith("{")) {
+              finish("Devin CLI emitted a malformed ACP frame.");
+            }
+            return;
+          }
+          sawProtocolFrame = true;
+          handle(frame);
+        }
+
+        /** JSON-RPC ids are allowed to come back as strings. */
+        const idOf = (value: unknown): number | undefined => {
+          if (typeof value === "number") return value;
+          if (typeof value === "string" && /^\d+$/.test(value)) return Number(value);
+          return undefined;
+        };
+
+        function handle(frame: Record<string, unknown>): void {
+          if (settled) return;
+          const id = idOf(frame.id);
+          const error = frame.error as { message?: string } | undefined;
+
+          if (id === ACP_INITIALIZE_ID) {
+            if (error) return finish(`Devin CLI initialize failed: ${error.message ?? "unknown error"}`);
+            send(sessionNewFrame(cwd, modelId));
+            return;
+          }
+          if (id === ACP_SESSION_NEW_ID) {
+            if (error) return finish(`Devin CLI session/new failed: ${error.message ?? "unknown error"}`);
+            const sessionId = (frame.result as { sessionId?: string } | undefined)?.sessionId;
+            if (!sessionId) return finish("Devin CLI session/new returned no sessionId.");
+            send(sessionPromptFrame(sessionId, buildAcpPrompt(parsed)));
+            return;
+          }
+          if (frame.method === "session/request_permission" && frame.id != null) {
+            const params = frame.params as { options?: Array<{ optionId?: string; name?: string; kind?: string }> } | undefined;
+            send(permissionResponseFrame(frame.id as number | string, params?.options, toolsAllowed));
+            return;
+          }
+          if (frame.method === "session/update") {
+            const update = (frame.params as { update?: Record<string, unknown> } | undefined)?.update;
+            if (!update) return;
+            for (const event of acpUpdateToEvents(update)) emit(event);
+            return;
+          }
+          if (id === ACP_SESSION_PROMPT_ID) {
+            if (error) return finish(`Devin CLI session/prompt failed: ${error.message ?? "unknown error"}`);
+            sawPromptReply = true;
+            const result = frame.result as { stopReason?: unknown; usage?: unknown } | undefined;
+            usage = mapAcpUsage(result?.usage) ?? usage;
+            stopReason = mapAcpStopReason(result?.stopReason);
+            finish();
+          }
+        }
+
+        void sawPromptReply;
+        send(initializeFrame(process.env.OPENCODEX_VERSION ?? "0.0.0"));
+      });
+    },
+  };
+}
diff --git a/src/adapters/devin-cli/binary.ts b/src/adapters/devin-cli/binary.ts
new file mode 100644
index 0000000000..7435e262f1
--- /dev/null
+++ b/src/adapters/devin-cli/binary.ts
@@ -0,0 +1,69 @@
+/**
+ * Locate the Devin CLI.
+ *
+ * The official installer (`curl -fsSL https://cli.devin.ai/install.sh | bash`)
+ * and the Homebrew cask both drop the binary in one of a small set of places.
+ * The environment override comes first so an operator can point at a specific
+ * build without touching PATH, and PATH is the last resort rather than the
+ * first so a shadowed name cannot silently win.
+ */
+import { existsSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import { homedir } from "node:os";
+
+export const DEVIN_CLI_BIN_ENV = "OPENCODEX_DEVIN_CLI_BIN";
+
+export const DEVIN_CLI_INSTALL_HINT =
+  "Install the Devin CLI with `curl -fsSL https://cli.devin.ai/install.sh | bash` or `brew install --cask devin-cli`, then run `devin auth login`.";
+
+let cached: string | undefined;
+
+/** Reset the discovery cache (tests, or an explicit re-check after an install). */
+export function clearDevinCliBinaryCache(): void {
+  cached = undefined;
+}
+
+function candidatePaths(home: string): string[] {
+  return [
+    join(home, "AppData", "Local", "Microsoft", "WinGet", "Links", "devin.exe"),
+    join(home, ".local", "share", "devin", "bin", "devin"),
+    join(home, ".devin", "bin", "devin"),
+    join(home, ".local", "bin", "devin"),
+    "/opt/homebrew/bin/devin",
+    "/usr/local/bin/devin",
+    "/usr/bin/devin",
+  ];
+}
+
+function fromPath(exists: (p: string) => boolean): string | undefined {
+  const pathVar = process.env.PATH ?? "";
+  for (const dir of pathVar.split(delimiter)) {
+    if (!dir) continue;
+    for (const name of ["devin", "devin.exe"]) {
+      const full = join(dir, name);
+      if (exists(full)) return full;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Resolve the executable, or undefined when it is not installed.
+ *
+ * `exists` and `home` are seams so the resolution order can be tested without
+ * depending on what happens to be installed on the machine running the tests.
+ */
+export function resolveDevinCliBinary(opts?: { exists?: (p: string) => boolean; home?: string; useCache?: boolean }): string | undefined {
+  const exists = opts?.exists ?? existsSync;
+  const useCache = opts?.useCache ?? opts === undefined;
+  if (useCache && cached) return cached;
+  const override = process.env[DEVIN_CLI_BIN_ENV]?.trim();
+  if (override) {
+    if (useCache) cached = override;
+    return override;
+  }
+  const home = opts?.home ?? homedir();
+  const found = candidatePaths(home).find((p) => exists(p)) ?? fromPath(exists);
+  if (found && useCache) cached = found;
+  return found;
+}
diff --git a/src/adapters/devin-cli/models.ts b/src/adapters/devin-cli/models.ts
new file mode 100644
index 0000000000..5d22a049b0
--- /dev/null
+++ b/src/adapters/devin-cli/models.ts
@@ -0,0 +1,57 @@
+/**
+ * Models the Devin CLI accepts on `session/new`.
+ *
+ * The CLI picks its own default when no model is named, so this roster exists
+ * for the picker rather than as a gate. It is a static list on purpose: ACP has
+ * no discovery call, and the vendor roster moves faster than a pinned copy
+ * would, so an unknown id is passed through to the CLI to accept or refuse.
+ */
+export const DEVIN_CLI_DEFAULT_MODEL = "swe-2";
+
+export const DEVIN_CLI_MODELS = [
+  "swe-2",
+  "swe-2-high",
+  "claude-opus-5-medium",
+  "claude-fable-5-1-medium",
+  "claude-sonnet-5-medium",
+  "gpt-6-astra-medium",
+  "gpt-5-6-sol-medium",
+  "gemini-3-8-flash-medium",
+  "glm-5-3-high",
+  "glm-5-3-low",
+  "kimi-k3-high",
+] as const;
+
+/**
+ * Context windows for the CLI roster, in the same effort-suffixed ids the CLI
+ * accepts.
+ *
+ * Without this the picker fell back to the 128k default for every Devin CLI
+ * model, including `swe-2`, which is the roster's own default — so the one
+ * model most sessions ran reported less than half its real window.
+ *
+ * The numbers come from Cognition's `GetCascadeModelConfigs` catalog
+ * (`ClientModelConfig` field #18), which is the only first-party source: the
+ * Devin CLI and Desktop model pages, the SWE-2 announcement, and the Windsurf
+ * model reference all list these models without a window. The CLI is a separate
+ * product from the cloud, but Cognition documents the same models on both and
+ * describes no per-surface difference — the SWE-2 announcement ships it to
+ * Desktop, CLI, Web, and Fusion in one sentence — so the catalog's figure is
+ * used for both rather than inventing a second table.
+ *
+ * ACP has no discovery call, so unlike the cloud provider this cannot be
+ * refreshed live; it needs updating when the roster above does.
+ */
+export const DEVIN_CLI_MODEL_CONTEXT_WINDOWS: Record<string, number> = {
+  "swe-2": 262_000,
+  "swe-2-high": 262_000,
+  "claude-opus-5-medium": 1_000_000,
+  "claude-fable-5-1-medium": 1_000_000,
+  "claude-sonnet-5-medium": 1_000_000,
+  "gpt-6-astra-medium": 1_000_000,
+  "gpt-5-6-sol-medium": 1_000_000,
+  "gemini-3-8-flash-medium": 1_048_576,
+  "glm-5-3-high": 1_048_576,
+  "glm-5-3-low": 1_048_576,
+  "kimi-k3-high": 1_048_576,
+};
diff --git a/src/adapters/devin.ts b/src/adapters/devin.ts
new file mode 100644
index 0000000000..a95d6de5e2
--- /dev/null
+++ b/src/adapters/devin.ts
@@ -0,0 +1,326 @@
+/**
+ * Devin / Cognition / Windsurf adapter.
+ *
+ * Uses the unofficial cloud-direct Connect-RPC client (GetChatMessage).
+ * OpenCodex injects the OAuth API key onto provider.apiKey
+ * before runTurn. This adapter maps OcxContext <-> ChatHistoryItem and
+ * streams CloudChatEvent into AdapterEvent.
+ */
+import type { AdapterEvent, OcxAssistantMessage, OcxContentPart, OcxMessage, OcxParsedRequest, OcxProviderConfig, OcxTool, OcxToolCall, OcxToolResultMessage, OcxUsage } from "../types";
+import type { IncomingMeta, ProviderAdapter } from "./base";
+import { streamChatEvents, allocateCascadeId, CloudChatError, type ChatHistoryItem, type ToolDef } from "./devin/cloud-direct";
+import { getCachedCatalog } from "./devin/cloud-direct/catalog";
+import { DEVIN_DEFAULT_API_SERVER, resolveDevinApiServer } from "../oauth/devin";
+
+export const DEVIN_API_SERVER = DEVIN_DEFAULT_API_SERVER;
+
+const EFFORT_SUFFIXES = new Set(["low", "medium", "high", "xhigh", "max", "none", "1m", "max-1m", "none-1m", "fast"]);
+
+/**
+ * Cognition's catalog spells model ids with hyphens (`swe-1-7`), but the same
+ * models appear elsewhere - other proxies, hand-written config - with the dotted
+ * version number (`swe-1.7`). Left alone, a dotted id misses every catalog
+ * lookup and then gets an effort suffix appended to a name the server does not
+ * know, which Cognition answers with an opaque permission_denied.
+ */
+export function normalizeDevinModelId(modelId: string): string {
+  return modelId.replace(/\./g, "-");
+}
+
+function hasEffortSuffix(modelId: string): boolean {
+  const parts = modelId.split("-");
+  return parts.length > 1 && EFFORT_SUFFIXES.has(parts[parts.length - 1]!);
+}
+
+/**
+ * Resolve the wire model UID using the live catalog as the source of truth.
+ * Cognition's catalog lists most models with an effort suffix
+ * (e.g. `gpt-5-6-sol-high`); the base id alone is not accepted for those.
+ *
+ * If the catalog is available: use the exact UID when it exists, otherwise
+ * append the reasoning effort (or `medium` default) and pick a variant the
+ * account actually has.
+ *
+ * If the catalog is unavailable (degraded mode): append the effort suffix
+ * for any base id that doesn't already carry one, mirroring the catalog shape.
+ */
+async function resolveWireModelUid(
+  rawModelId: string,
+  apiKey: string,
+  host: string,
+  reasoningEffort?: string,
+): Promise<string> {
+  const modelId = normalizeDevinModelId(rawModelId);
+  if (hasEffortSuffix(modelId)) return modelId;
+  const catalog = await getCachedCatalog(apiKey, host);
+  if (catalog) {
+    if (catalog.byUid.has(modelId)) return modelId;
+    const effort = reasoningEffort && EFFORT_SUFFIXES.has(reasoningEffort) ? reasoningEffort : "medium";
+    const suffixed = `${modelId}-${effort}`;
+    if (catalog.byUid.has(suffixed)) return suffixed;
+    // Fall back to any enabled variant of this base model.
+    for (const uid of catalog.byUid.keys()) {
+      if (uid.startsWith(modelId + "-") && !catalog.byUid.get(uid)?.disabled) return uid;
+    }
+  }
+  // Degraded mode: append the default effort suffix.
+  const effort = reasoningEffort && EFFORT_SUFFIXES.has(reasoningEffort) ? reasoningEffort : "medium";
+  return `${modelId}-${effort}`;
+}
+
+export class DevinMissingCredentialError extends Error {
+  constructor() {
+    super("Devin live transport requires a Devin API key. Run ocx login devin to sign in with your Cognition/Devin account.");
+    this.name = "DevinMissingCredentialError";
+  }
+}
+
+export function resolveDevinToken(provider: OcxProviderConfig, headers?: Headers): string {
+  const providerKey = provider.apiKey?.trim();
+  if (providerKey) return providerKey;
+  const forwarded = headers?.get("authorization") ?? headers?.get("Authorization");
+  if (forwarded?.toLowerCase().startsWith("bearer ")) return forwarded.slice("bearer ".length).trim();
+  const envToken = process.env.OPENCODEX_DEVIN_TEST_TOKEN?.trim();
+  if (envToken) return envToken;
+  throw new DevinMissingCredentialError();
+}
+
+function textFromParts(content: string | OcxContentPart[] | undefined): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content.map((part) => (part.type === "text" ? part.text : "")).filter(Boolean).join("\n");
+}
+
+function toolResultText(message: OcxToolResultMessage): string {
+  const body = textFromParts(message.content);
+  return message.isError ? ("ERROR: " + body) : body;
+}
+
+function assistantToolCalls(message: OcxAssistantMessage): Array<{ id: string; name: string; arguments: string }> {
+  return message.content
+    .filter((part): part is OcxToolCall => part.type === "toolCall")
+    .map((part) => ({
+      id: part.id,
+      name: part.name,
+      arguments: JSON.stringify(part.arguments ?? {}),
+    }));
+}
+
+function assistantText(message: OcxAssistantMessage): string {
+  return message.content
+    // Thinking stays out of the replayed content. Cognition has no reasoning
+    // replay field, and folding chain-of-thought into assistant text sends it
+    // back as visible prior output - which the model then treats as something
+    // it said to the user.
+    .map((part) => (part.type === "text" ? part.text : ""))
+    .filter(Boolean)
+    .join("\n");
+}
+
+export function mapOcxMessagesToDevin(parsed: OcxParsedRequest): ChatHistoryItem[] {
+  const items: ChatHistoryItem[] = [];
+  const system = parsed.context.systemPrompt?.filter((line) => line.trim().length > 0).join("\n");
+  if (system) items.push({ role: "system", content: system });
+
+  for (const message of parsed.context.messages) {
+    const mapped = mapOneMessage(message);
+    if (mapped) items.push(mapped);
+  }
+  return items;
+}
+
+function mapOneMessage(message: OcxMessage): ChatHistoryItem | undefined {
+  if (message.role === "user" || message.role === "developer") {
+    const text = textFromParts(message.content).trim();
+    if (!text) return undefined;
+    return { role: message.role === "developer" ? "system" : "user", content: text };
+  }
+  if (message.role === "assistant") {
+    const toolCalls = assistantToolCalls(message);
+    const text = assistantText(message);
+    if (!text && toolCalls.length === 0) return undefined;
+    return {
+      role: "assistant",
+      content: text || "",
+      ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : {}),
+    };
+  }
+  if (message.role === "toolResult") {
+    return {
+      role: "tool",
+      content: toolResultText(message),
+      tool_call_id: message.toolCallId,
+    };
+  }
+  return undefined;
+}
+
+export function mapOcxToolsToDevin(tools: OcxTool[] | undefined): ToolDef[] | undefined {
+  if (!tools || tools.length === 0) return undefined;
+  return tools.map((tool) => ({
+    name: tool.name,
+    description: tool.description ?? "",
+    parameters: tool.parameters ?? { type: "object", properties: {} },
+  }));
+}
+
+export function createDevinAdapter(
+  provider: OcxProviderConfig,
+  context: { providerId?: string } = {},
+): ProviderAdapter {
+  // Which credential slot holds this row's tenant. Defaults to `devin` so every
+  // existing caller — including the tests that construct this adapter directly —
+  // behaves exactly as before.
+  const credentialProviderId = context.providerId ?? "devin";
+  const cascadeIds = new Map<string, string>();
+  const CASCADE_ID_MAX = 256;
+
+  return {
+    name: "devin",
+
+    buildRequest() {
+      return {
+        url: provider.baseUrl || DEVIN_API_SERVER,
+        method: "POST",
+        headers: {},
+        body: "",
+      };
+    },
+
+    async *parseStream(): AsyncGenerator<AdapterEvent> {
+      yield {
+        type: "error",
+        message: "Devin adapter uses runTurn; the fetch/parseStream path is disabled.",
+      };
+    },
+
+    async runTurn(parsed: OcxParsedRequest, incoming: IncomingMeta, emit: (event: AdapterEvent) => void) {
+      if (incoming.abortSignal?.aborted) {
+        emit({ type: "error", message: "Devin turn was aborted before start." });
+        return;
+      }
+      let apiKey: string;
+      try {
+        apiKey = resolveDevinToken(provider, incoming.headers);
+      } catch (error) {
+        emit({ type: "error", message: error instanceof Error ? error.message : String(error) });
+        return;
+      }
+
+      const threadKey = parsed._clientThreadId || parsed.previousResponseId || "default";
+      let cascadeId = cascadeIds.get(threadKey);
+      if (!cascadeId) {
+        // Evict oldest entries to bound memory in long-running proxy processes.
+        if (cascadeIds.size >= CASCADE_ID_MAX) {
+          const firstKey = cascadeIds.keys().next().value;
+          if (firstKey) cascadeIds.delete(firstKey);
+        }
+        cascadeId = allocateCascadeId();
+        cascadeIds.set(threadKey, cascadeId);
+      }
+
+      const rawModelId = parsed.modelId.includes("/") ? parsed.modelId.slice(parsed.modelId.lastIndexOf("/") + 1) : parsed.modelId;
+      // The signed-in account's tenant decides the host, not the static registry
+      // entry: an EU or FedStart account that used provider.baseUrl would send
+      // every RPC to the US server it is not provisioned on.
+      const host = resolveDevinApiServer(provider.baseUrl, credentialProviderId);
+      const modelUid = await resolveWireModelUid(rawModelId, apiKey, host, parsed.options.reasoning);
+      let openToolId: string | undefined;
+      let usage: OcxUsage | undefined;
+      let stopReason: string | undefined;
+
+      const closeOpenTool = () => {
+        if (!openToolId) return;
+        emit({ type: "tool_call_end" });
+        openToolId = undefined;
+      };
+
+      try {
+        for await (const event of streamChatEvents({
+          apiKey,
+          apiServerUrl: host,
+          modelUid,
+          messages: mapOcxMessagesToDevin(parsed),
+          tools: mapOcxToolsToDevin(parsed.context.tools),
+          cascadeId,
+          // Without these the request falls back to the encoder's defaults
+          // (8192 output, a 128k context window, temperature 0.7), so a client
+          // that asked for a 4k cap never got one.
+          completionOpts: {
+            ...(typeof parsed.options.maxOutputTokens === "number" ? { maxOutputTokens: parsed.options.maxOutputTokens } : {}),
+            ...(typeof parsed.options.temperature === "number" ? { temperature: parsed.options.temperature } : {}),
+            ...(typeof parsed.options.topP === "number" ? { topP: parsed.options.topP } : {}),
+          },
+          signal: incoming.abortSignal,
+        })) {
+          if (incoming.abortSignal?.aborted) {
+            // Emitting nothing here left the bridge to synthesize adapter_eof.
+            // Say what happened instead, the way the other runTurn-only adapter
+            // does, and carry any usage already seen.
+            closeOpenTool();
+            emit({ type: "error", message: "Devin turn was aborted.", ...(usage ? { usage } : {}) });
+            return;
+          }
+          if (event.kind === "text") {
+            closeOpenTool();
+            if (event.text) emit({ type: "text_delta", text: event.text });
+            continue;
+          }
+          if (event.kind === "reasoning") {
+            if (event.text) emit({ type: "thinking_delta", thinking: event.text });
+            continue;
+          }
+          if (event.kind === "tool_call_start") {
+            closeOpenTool();
+            openToolId = event.id;
+            emit({ type: "tool_call_start", id: event.id, name: event.name });
+            continue;
+          }
+          if (event.kind === "tool_call_args") {
+            if (event.argsDelta) emit({ type: "tool_call_delta", arguments: event.argsDelta });
+            continue;
+          }
+          if (event.kind === "finish") {
+            closeOpenTool();
+            // A natural completion carries no stopReason: the bridge reads any
+            // truthy value as "this turn did not reach a final answer", so
+            // reporting "stop" costs every clean Devin turn its final_answer
+            // phase.
+            stopReason = event.reason === "length" ? "max_tokens" : event.reason === "stop" ? undefined : event.reason;
+            continue;
+          }
+          if (event.kind === "usage") {
+            const total = event.totalTokens ?? ((event.promptTokens ?? 0) + (event.completionTokens ?? 0));
+            usage = {
+              inputTokens: event.promptTokens ?? 0,
+              outputTokens: event.completionTokens ?? 0,
+              ...(total > 0 ? { totalTokens: total } : {}),
+              ...(event.cachedInputTokens !== undefined ? { cachedInputTokens: event.cachedInputTokens } : {}),
+              ...(event.cacheCreationInputTokens !== undefined ? { cacheCreationInputTokens: event.cacheCreationInputTokens } : {}),
+              ...(event.reasoningTokens !== undefined ? { reasoningOutputTokens: event.reasoningTokens } : {}),
+            };
+            continue;
+          }
+        }
+        closeOpenTool();
+        if (incoming.abortSignal?.aborted) {
+          emit({ type: "error", message: "Devin turn was aborted.", ...(usage ? { usage } : {}) });
+        } else {
+          emit({ type: "done", ...(usage ? { usage } : {}), ...(stopReason ? { stopReason } : {}) });
+        }
+      } catch (error) {
+        closeOpenTool();
+        if (incoming.abortSignal?.aborted) {
+          emit({ type: "error", message: "Devin turn was aborted.", ...(usage ? { usage } : {}) });
+          return;
+        }
+        const message = error instanceof CloudChatError
+          ? ("Devin cloud error" + (error.code ? " " + error.code : "") + ": " + error.message)
+          : error instanceof Error ? error.message : String(error);
+        // Usage that already arrived is still real; dropping it loses the
+        // accounting for a turn that did most of its work before failing.
+        emit({ type: "error", message, ...(usage ? { usage } : {}) });
+      }
+    },
+  };
+}
diff --git a/src/adapters/devin/cloud-direct/auth.ts b/src/adapters/devin/cloud-direct/auth.ts
new file mode 100644
index 0000000000..4aa4e02a57
--- /dev/null
+++ b/src/adapters/devin/cloud-direct/auth.ts
@@ -0,0 +1,264 @@
+/*
+ * Derived from rsvedant/opencode-windsurf-auth (src/cloud-direct/), MIT licensed,
+ * Copyright (c) 2026 Vedant. The full notice is in ./index.ts.
+ */
+/**
+ * Mint the short-lived `user_jwt` that accompanies the persistent OAuth-issued
+ * `api_key`. The catalog RPC uses it. The hosted chat path does not need it and
+ * only sends it when an operator opts in, so a mint failure here cannot take
+ * down a turn.
+ *
+ *   POST https://server.codeium.com/exa.auth_pb.AuthService/GetUserJwt
+ *   Content-Type: application/proto             ← unary, NOT streaming
+ *   Body: GetUserJwtRequest { metadata: Metadata }
+ *   Response: GetUserJwtResponse { user_jwt: string }  (field 1)
+ *
+ * The returned JWT has a payload like:
+ *   {
+ *     "api_key": "devin-synthetic-apikey$account-…$user-…",
+ *     "auth_uid": "devin-auth-uid$…",
+ *     "email": "user@example.com",
+ *     "exp": <unix-seconds>,         ← ~24 minute TTL
+ *     "pro": true,
+ *     "teams_tier": "TEAMS_TIER_DEVIN_PRO",
+ *     ...
+ *   }
+ *
+ * The JWT is signed HS256 by the server — can't be forged client-side. We
+ * cache it and refresh shortly before `exp`.
+ */
+
+import * as crypto from 'crypto';
+import { encodeMessage, iterFields } from './wire.js';
+import { buildMetadata } from './metadata.js';
+import { anySignal } from '../../../lib/abort.js';
+import { validateDevinApiBaseUrl } from '../../../oauth/devin/api-base.js';
+
+const DEFAULT_HOST = 'https://server.codeium.com';
+
+export interface MintedUserJwt {
+  jwt: string;
+  /** Unix epoch seconds when the JWT expires. */
+  expiresAt: number;
+}
+
+export class CloudAuthError extends Error {
+  constructor(message: string, public readonly status?: number) {
+    super(message);
+    this.name = 'CloudAuthError';
+  }
+}
+
+/**
+ * Default mint timeout — 30s is generous (the endpoint responds in ~200ms
+ * in steady state) but enough headroom for slow networks. Callers can pass
+ * a tighter `signal` to override.
+ */
+const MINT_TIMEOUT_MS = 30_000;
+
+/**
+ * Mint a fresh user_jwt by calling exa.auth_pb.AuthService/GetUserJwt.
+ * `host` defaults to https://server.codeium.com — pass your tenant URL if your
+ * RegisterUser response gave a different host.
+ *
+ * Always applies an internal 30s timeout so a network stall here can't
+ * deadlock every concurrent chat request. If the caller passes a `signal`,
+ * we honor whichever fires first via AbortSignal.any.
+ */
+export async function mintUserJwt(
+  apiKey: string,
+  host: string = DEFAULT_HOST,
+  signal?: AbortSignal,
+): Promise<MintedUserJwt> {
+  const metadata = buildMetadata({
+    apiKey,
+    sessionId: crypto.randomUUID(),
+    requestId: BigInt(Date.now()),
+    triggerId: crypto.randomUUID(),
+  });
+  // GetUserJwtRequest { metadata: Metadata }   — Metadata is field 1
+  const req = encodeMessage(1, metadata);
+
+  // Compose caller signal with our internal timeout via `anySignal` — a
+  // small polyfill of `AbortSignal.any` for runtimes (Node 18 / older
+  // Bun) that lack the built-in. The previous fallback silently dropped
+  // the CALLER's signal on those runtimes, so a chat-cancel during a
+  // GetUserJwt mint would keep the network request alive for up to the
+  // full 30s timeout.
+  const timeoutSignal = AbortSignal.timeout(MINT_TIMEOUT_MS);
+  const composed = signal ? anySignal([signal, timeoutSignal]) : undefined;
+  const combinedSignal: AbortSignal = composed?.signal ?? timeoutSignal;
+
+  // The host arrives from RegisterUser via the credential store. It is checked
+  // again here because this request carries the long-lived api_key inside the
+  // protobuf body, and a host that slipped past persistence would exfiltrate it.
+  const base = validateDevinApiBaseUrl(host);
+  if (!base) {
+    throw new CloudAuthError(`Refusing to mint a user_jwt against a non-Cognition host.`);
+  }
+  let resp: Response;
+  try {
+    resp = await fetch(`${base}/exa.auth_pb.AuthService/GetUserJwt`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/proto',
+      'Connect-Protocol-Version': '1',
+    },
+    body: new Uint8Array(req),
+    // A redirect would replay this POST - whose body holds the api_key - at
+    // whatever host Location names.
+    redirect: 'error',
+    signal: combinedSignal,
+    });
+  } finally {
+    // The caller's signal belongs to a whole turn; do not keep a listener on it.
+    composed?.cleanup();
+  }
+  const buf = Buffer.from(await resp.arrayBuffer());
+
+  if (!resp.ok) {
+    // The body is not echoed. A Connect error here can quote the request, and
+    // the request contains the api_key; this message reaches CLI output, the
+    // adapter's error event, and /api/logs.
+    throw new CloudAuthError(`GetUserJwt failed (HTTP ${resp.status})`, resp.status);
+  }
+
+  // Response is GetUserJwtResponse { user_jwt: string } where user_jwt is
+  // field 1, length-delimited. Decode the field properly instead of
+  // regex-scanning the whole buffer — the previous regex would pick up
+  // any JWT-shaped substring in the response (trace IDs, signature
+  // headers, any cached token inadvertently logged) and could even land
+  // on a non-user_jwt if Cognition ever embeds another JWT in a sibling
+  // field.
+  let jwt: string | null = null;
+  for (const f of iterFields(buf)) {
+    if (f.num === 1 && f.wire === 2 && Buffer.isBuffer(f.value)) {
+      const s = (f.value as Buffer).toString('utf8');
+      // Sanity-check the shape — defensive: if the cloud ever moves user_jwt
+      // out from field 1 we want a clean error, not silently wrong creds.
+      // base64url with OPTIONAL `=` padding on each segment. Most modern
+      // JWTs omit the `=`, but the spec allows it and a future server-side
+      // change could re-introduce it; either way it's still a valid token.
+      if (/^eyJ[A-Za-z0-9_-]{10,}={0,2}\.[A-Za-z0-9_-]+={0,2}\.[A-Za-z0-9_-]+={0,2}$/.test(s)) {
+        jwt = s;
+        break;
+      }
+    }
+  }
+  if (!jwt) {
+    throw new CloudAuthError(
+      // Same reason: a 200 whose field-1 value failed the shape check may still
+      // be a live token, so only the size is reported.
+      `GetUserJwt returned 200 without a usable field-1 JWT (${buf.length} bytes)`,
+    );
+  }
+
+  // Decode the payload to get the expiry.
+  let expiresAt = Math.floor(Date.now() / 1000) + 600;   // fallback: 10 min
+  try {
+    const parts = jwt.split('.');
+    const pad = (s: string) => s + '='.repeat((4 - (s.length % 4)) % 4);
+    const payload = JSON.parse(
+      Buffer.from(pad(parts[1]).replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf8'),
+    );
+    if (typeof payload.exp === 'number') expiresAt = payload.exp;
+  } catch { /* fall back to default */ }
+
+  return { jwt, expiresAt };
+}
+
+// ----------------------------------------------------------------------------
+// In-memory cache — refresh ~60s before expiry
+// ----------------------------------------------------------------------------
+
+interface CacheEntry {
+  jwt: string;
+  expiresAt: number;
+  apiKey: string;
+  host: string;
+}
+
+/**
+ * Cache is keyed by (apiKey, host). A single shared `cache` slot only holds
+ * the MOST RECENTLY USED entry — common case is one account at a time, so
+ * a single slot is enough. inFlight is a per-key map so a JWT mint for
+ * account A doesn't get returned to a concurrent request for account B.
+ *
+ * Previously `inFlight` was a singleton — if account A's mint was in flight
+ * and a request for account B arrived, B got A's JWT. That's the M1
+ * "concurrent requests after account switch get wrong JWT" bug.
+ */
+let cache: CacheEntry | null = null;
+const inFlight = new Map<string, Promise<MintedUserJwt>>();
+/**
+ * Monotonic epoch counter. Incremented on every `clearCachedUserJwt()`
+ * call so an in-flight mint that started BEFORE the clear can't
+ * repopulate the cache after-the-fact. Without this, a logout that
+ * happened concurrently with a mint would silently get its just-
+ * invalidated JWT cached and served for the next ~24 minutes.
+ */
+let cacheEpoch = 0;
+
+function flightKey(apiKey: string, host: string): string {
+  return `${host}\x1f${apiKey}`;
+}
+
+/**
+ * Get a cached user_jwt or mint a new one. Refreshes when the cached JWT is
+ * within 60s of expiry. Multiple concurrent callers for the SAME (apiKey, host)
+ * share the same in-flight mint; concurrent callers for DIFFERENT keys each
+ * get their own mint.
+ */
+export async function getCachedUserJwt(apiKey: string, host: string = DEFAULT_HOST, signal?: AbortSignal): Promise<string> {
+  const now = Math.floor(Date.now() / 1000);
+  if (cache && cache.apiKey === apiKey && cache.host === host && cache.expiresAt > now + 60) {
+    return cache.jwt;
+  }
+  // Race the caller's signal against the shared promise so one caller's
+  // cancellation doesn't propagate to unrelated callers sharing the mint.
+  // mintUserJwt has its own MINT_TIMEOUT_MS guard for the shared lifetime.
+  const raceSignal = <T>(p: Promise<T>): Promise<T> =>
+    signal
+      ? Promise.race([
+          p,
+          new Promise<T>((_, reject) => {
+            if (signal.aborted) reject(signal.reason);
+            else signal.addEventListener('abort', () => reject(signal.reason), { once: true });
+          }),
+        ])
+      : p;
+  const key = flightKey(apiKey, host);
+  const existing = inFlight.get(key);
+  if (existing) {
+    const minted = await raceSignal(existing);
+    return minted.jwt;
+  }
+  const promise = mintUserJwt(apiKey, host);
+  inFlight.set(key, promise);
+  // Snapshot the epoch BEFORE awaiting the mint. If clearCachedUserJwt()
+  // fires while we're awaiting (logout-during-mint), the epoch changes
+  // and we won't repopulate the cache with the just-invalidated JWT.
+  const epochAtStart = cacheEpoch;
+  try {
+    const minted = await raceSignal(promise);
+    if (cacheEpoch === epochAtStart) {
+      cache = { jwt: minted.jwt, expiresAt: minted.expiresAt, apiKey, host };
+    }
+    return minted.jwt;
+  } finally {
+    inFlight.delete(key);
+  }
+}
+
+/**
+ * Drop the in-memory JWT cache. Call after credential changes (logout,
+ * account switch) so long-running opencode processes don't keep using a
+ * JWT minted from a now-invalid api_key. Also bumps the cache epoch so
+ * any in-flight mint racing with this clear can't repopulate cache
+ * with the stale JWT after-the-fact.
+ */
+export function clearCachedUserJwt(): void {
+  cache = null;
+  inFlight.clear();
+  cacheEpoch++;
+}
diff --git a/src/adapters/devin/cloud-direct/catalog.ts b/src/adapters/devin/cloud-direct/catalog.ts
new file mode 100644
index 0000000000..f7638d1660
--- /dev/null
+++ b/src/adapters/devin/cloud-direct/catalog.ts
@@ -0,0 +1,306 @@
+/*
+ * Derived from rsvedant/opencode-windsurf-auth (src/cloud-direct/), MIT licensed,
+ * Copyright (c) 2026 Vedant. The full notice is in ./index.ts.
+ */
+/**
+ * Per-account model catalog from Cognition's `GetCascadeModelConfigs`.
+ *
+ * Why this exists — issue #14:
+ *   The cloud's `GetChatMessage` returns a single Connect-streaming EOS frame
+ *   containing `{"error":{"code":"permission_denied","message":"an internal
+ *   error occurred (trace ID: <hex>)"}}` whenever the caller's account tier
+ *   does not include the requested `model_uid`. Reproduced byte-identical on a
+ *   `TEAMS_TIER_DEVIN_FREE` account for every Anthropic/Gemini/Premium UID
+ *   (only `swe-1-6-slow` streamed a real reply). The user-facing message is
+ *   indistinguishable from a transient server fault — issue #14's reporter
+ *   spent multiple sessions guessing.
+ *
+ *   The pre-flight here checks the per-account catalog (`disabled` flag on
+ *   `ClientModelConfig` field #4) BEFORE we spend a roundtrip on a request
+ *   the cloud will refuse. When the lookup fails (network, auth, schema
+ *   drift) we silently fall back to the chat path so a transient catalog
+ *   outage can't take chat down with it.
+ *
+ * Schema (verified against the bundled `extension.js`,
+ * `exa.codeium_common_pb.ClientModelConfig`):
+ *
+ *   GetCascadeModelConfigsResponse {
+ *     #1 client_model_configs: repeated ClientModelConfig
+ *   }
+ *   ClientModelConfig {
+ *     #1  label                string
+ *     #4  disabled             bool   ← the gate this module reads
+ *     #22 model_uid            string ← what `GetChatMessage` accepts
+ *   }
+ *
+ *   Disabled semantics: TRUE means "this UID exists in the catalog but the
+ *   caller's account/tier cannot run inference against it." BYOK models
+ *   surface as `disabled: false` so users with their own provider keys still
+ *   pass through — the only way they fail at chat time is a missing key,
+ *   which surfaces with a different message.
+ *
+ * Cache: per (apiServerUrl, apiKey) for {@link CATALOG_TTL_MS}. Cognition
+ * doesn't bump catalog entries mid-session in normal operation, so a 10-min
+ * TTL trades one extra roundtrip per ~10 min for clear errors on every chat.
+ */
+
+import * as crypto from 'crypto';
+import { buildMetadata } from './metadata.js';
+import { getCachedUserJwt } from './auth.js';
+import { encodeMessage, iterFields } from './wire.js';
+import { resolveDevinApiBaseUrl } from '../../../oauth/devin/api-base.js';
+
+/** 10 minutes — see header. */
+const CATALOG_TTL_MS = 10 * 60 * 1000;
+
+/** Catalog endpoint inactivity timeout. Cognition responds in <500ms steady-state. */
+const CATALOG_FETCH_TIMEOUT_MS = 10_000;
+
+export interface ModelCatalogEntry {
+  /** Cloud-side `model_uid` (e.g. `claude-opus-4-7-medium`). */
+  modelUid: string;
+  /** Human label (e.g. `Claude Opus 4.7 Medium`) — used in error messages. */
+  label: string;
+  /** True when the caller's account tier cannot use this UID for chat. */
+  disabled: boolean;
+  /**
+   * Maximum input tokens the account may send this model, from
+   * `ClientModelConfig` field #18.
+   *
+   * Cognition publishes no context-window numbers anywhere: not in the Devin
+   * CLI or Desktop model pages, not in the SWE-2 or SWE-1.7 announcements, and
+   * not in the Windsurf model reference, which has no such table. The only
+   * numbers on those pages are long-context PRICING thresholds, which are a
+   * different quantity. That makes this field the single first-party source,
+   * and it is per account rather than per model id.
+   *
+   * Absent when the entry omits the field, which is how a future schema change
+   * degrades: the caller keeps its static fallback instead of reporting zero.
+   */
+  contextWindow?: number;
+}
+
+export interface CacheEntry {
+  /** Lookup keyed by `model_uid`. */
+  byUid: Map<string, ModelCatalogEntry>;
+  fetchedAt: number;
+  /** Cache key components, captured for invalidation/log purposes. */
+  apiKey: string;
+  host: string;
+}
+
+let cached: CacheEntry | null = null;
+let inFlight: Promise<CacheEntry> | null = null;
+let inFlightKey: string | null = null;
+// Bumped on clearCachedCatalog so an in-flight fetch racing with a clear
+// can't repopulate the cache with a just-invalidated catalog.
+let cacheEpoch = 0;
+
+function flightKey(apiKey: string, host: string): string {
+  return `${host}\x1f${apiKey}`;
+}
+
+/**
+ * Parse a GetCascadeModelConfigsResponse buffer into a UID-keyed map.
+ * A malformed catalog returns an empty map.
+ */
+export function parseCatalogBuffer(buf: Buffer, apiKey: string, host: string): CacheEntry {
+  // GetCascadeModelConfigsResponse #1 (repeated ClientModelConfig)
+  const byUid = new Map<string, ModelCatalogEntry>();
+  for (const f of iterFields(buf)) {
+    if (f.num !== 1 || f.wire !== 2 || !Buffer.isBuffer(f.value)) continue;
+    let label = '';
+    let modelUid = '';
+    let disabled = false;
+    let contextWindow = 0;
+    for (const sf of iterFields(f.value as Buffer)) {
+      if (sf.num === 1 && sf.wire === 2 && Buffer.isBuffer(sf.value)) {
+        label = (sf.value as Buffer).toString('utf8');
+      } else if (sf.num === 4 && sf.wire === 0) {
+        // #4 = disabled (bool, varint 0/1)
+        disabled = sf.value === 1n;
+      } else if (sf.num === 18 && sf.wire === 0) {
+        // #18 = max input tokens. Identified by dumping a live catalog and
+        // reading the varints back against models whose windows are known from
+        // their upstream vendors: 1000000 on the Claude and GPT rows, 1048576
+        // on Gemini/Kimi/GLM, 500000 on Grok, 262000 on swe-2.
+        contextWindow = Number(sf.value);
+      } else if (sf.num === 22 && sf.wire === 2 && Buffer.isBuffer(sf.value)) {
+        modelUid = (sf.value as Buffer).toString('utf8');
+      }
+    }
+    if (modelUid.length > 0) {
+      byUid.set(modelUid, {
+        modelUid,
+        label: label || modelUid,
+        disabled,
+        ...(contextWindow > 0 ? { contextWindow } : {}),
+      });
+    }
+  }
+  return { byUid, fetchedAt: Date.now(), apiKey, host };
+}
+
+/**
+ * Fetch the cascade model catalog for `(apiKey, host)` and parse the
+ * subset of `ClientModelConfig` we care about into a UID-keyed map.
+ *
+ * Throws on transport/auth failure so the caller can decide whether to fall
+ * back to "skip pre-flight". Does NOT throw on an unexpected response body —
+ * a malformed catalog returns an empty map, treated the same as "model not
+ * listed" by the chat pre-flight.
+ *
+ * Uses only an internal timeout — caller cancellation is handled by
+ * getCachedCatalog racing each caller's signal against the shared promise.
+ */
+async function fetchCatalog(apiKey: string, host: string): Promise<CacheEntry> {
+  const userJwt = await getCachedUserJwt(apiKey, host);
+
+  const metadata = buildMetadata({
+    apiKey,
+    userJwt,
+    sessionId: crypto.randomUUID(),
+    requestId: BigInt(Date.now()),
+    triggerId: crypto.randomUUID(),
+  });
+  // GetCascadeModelConfigsRequest { metadata: Metadata }  — Metadata is #1.
+  const reqBody = encodeMessage(1, metadata);
+
+  // Internal 10s timeout so a stalled catalog endpoint can't deadlock chat.
+  // The shared fetch uses only this internal timeout — caller cancellation is
+  // handled by racing each caller's signal against the shared promise in
+  // getCachedCatalog, so one caller's abort never propagates to unrelated
+  // callers sharing the same in-flight fetch.
+  const ac = new AbortController();
+  const timer = setTimeout(
+    () => ac.abort(new Error(`catalog: fetch timeout (${CATALOG_FETCH_TIMEOUT_MS}ms)`)),
+    CATALOG_FETCH_TIMEOUT_MS,
+  );
+
+  let resp: Response;
+  try {
+    resp = await fetch(`${resolveDevinApiBaseUrl(host)}/exa.api_server_pb.ApiServerService/GetCascadeModelConfigs`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/proto', 'Connect-Protocol-Version': '1' },
+      body: new Uint8Array(reqBody),
+      // This body carries the api_key; a redirect would replay it elsewhere.
+      redirect: 'error',
+      signal: ac.signal,
+    });
+    if (!resp.ok) {
+      // Status only: the error body can quote the api_key-bearing request.
+      throw new Error(`GetCascadeModelConfigs failed (HTTP ${resp.status})`);
+    }
+    // Read the body BEFORE clearing the timeout — fetch resolves on headers,
+    // not body completion. A stalled body would otherwise block indefinitely.
+    const buf = Buffer.from(await resp.arrayBuffer());
+    return parseCatalogBuffer(buf, apiKey, host);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Get the cached catalog for `(apiKey, host)`, fetching when missing or stale.
+ *
+ * Concurrent callers for the SAME (apiKey, host) share one in-flight fetch
+ * (no thundering herd on startup). Concurrent callers for DIFFERENT keys
+ * serialise the in-flight slot but only one of them holds it at a time —
+ * good enough for opencode's single-account-at-a-time usage pattern.
+ *
+ * Returns `null` on fetch failure (network, transient 5xx, auth issue). The
+ * caller treats `null` as "skip pre-flight and let the chat path surface the
+ * server-side error itself."
+ */
+export async function getCachedCatalog(
+  apiKey: string,
+  host: string,
+  signal?: AbortSignal,
+): Promise<CacheEntry | null> {
+  if (cached && cached.apiKey === apiKey && cached.host === host) {
+    if (Date.now() - cached.fetchedAt < CATALOG_TTL_MS) {
+      return cached;
+    }
+  }
+
+  const key = flightKey(apiKey, host);
+  // Race the caller's signal against the shared promise so one caller's
+  // cancellation doesn't propagate to unrelated callers sharing the fetch.
+  const raceSignal = <T>(p: Promise<T>): Promise<T> =>
+    signal
+      ? Promise.race([
+          p,
+          new Promise<T>((_, reject) => {
+            if (signal.aborted) reject(signal.reason);
+            else signal.addEventListener('abort', () => reject(signal.reason), { once: true });
+          }),
+        ])
+      : p;
+
+  if (inFlight && inFlightKey === key) {
+    try {
+      return await raceSignal(inFlight);
+    } catch {
+      return null;
+    }
+  }
+
+  const promise = fetchCatalog(apiKey, host);
+  inFlight = promise;
+  inFlightKey = key;
+  const epochAtStart = cacheEpoch;
+  try {
+    const result = await raceSignal(promise);
+    if (cacheEpoch === epochAtStart) {
+      cached = result;
+    }
+    return result;
+  } catch {
+    return null;
+  } finally {
+    if (inFlight === promise) {
+      inFlight = null;
+      inFlightKey = null;
+    }
+  }
+}
+
+/**
+ * Drop the cached catalog. Call after logout/account switch so a fresh
+ * sign-in doesn't see a previous account's allow-list. Bumps the cache
+ * epoch so an in-flight fetch racing with this clear can't repopulate
+ * the cache with the just-invalidated catalog.
+ */
+export function clearCachedCatalog(): void {
+  cached = null;
+  inFlight = null;
+  inFlightKey = null;
+  cacheEpoch++;
+}
+
+/**
+ * Tier-disabled error — thrown by the chat pre-flight when the catalog lists
+ * a model as `disabled: true` for this account. The message names the model
+ * and points at the plan page, replacing Cognition's opaque
+ * "an internal error occurred" trailer.
+ */
+export class ModelNotAvailableError extends Error {
+  constructor(
+    public readonly modelUid: string,
+    public readonly label: string,
+    public readonly reason: 'disabled' | 'not_listed',
+  ) {
+    super(
+      reason === 'disabled'
+        ? `Model "${label}" (uid=${modelUid}) is not enabled for your Cognition account. ` +
+          `The Cognition catalog returned it with disabled=true — meaning your current plan/tier ` +
+          `does not include this model. ` +
+          `Check the model picker on https://codeium.com/account, or pick a different model. ` +
+          `(This message replaces Cognition's "an internal error occurred" — same root cause.)`
+        : `Model uid "${modelUid}" is not listed in the Cognition catalog for your account. ` +
+          `Either the UID has been retired upstream or your account/region doesn't serve it. ` +
+          `Run \`curl http://127.0.0.1:42100/v1/models\` to see the canonical names your plan accepts.`,
+    );
+    this.name = 'ModelNotAvailableError';
+  }
+}
diff --git a/src/adapters/devin/cloud-direct/chat.ts b/src/adapters/devin/cloud-direct/chat.ts
new file mode 100644
index 0000000000..334156daf9
--- /dev/null
+++ b/src/adapters/devin/cloud-direct/chat.ts
@@ -0,0 +1,1274 @@
+/*
+ * Derived from rsvedant/opencode-windsurf-auth (src/cloud-direct/), MIT licensed,
+ * Copyright (c) 2026 Vedant. The full notice is in ./index.ts.
+ */
+/**
+ * Cloud-direct streaming chat. Talks to
+ * `server.codeium.com/exa.api_server_pb.ApiServerService/GetChatMessage`
+ * with no local language_server in the path. Returns an async iterable of
+ * CloudChatEvent deltas (text, reasoning, tool calls, usage, finish) so the
+ * caller can stream straight into opencodex's internal AdapterEvent model.
+ *
+ * What this supports:
+ *   - Single- or multi-turn chat using the prompt-and-history pattern the LS
+ *     uses (flatten history into one ChatMessagePrompt list)
+ *   - All free Windsurf/Cognition models (swe-1-7, swe-1-7-lightning, etc.)
+ *     and any model the user's api_key is entitled to
+ *   - Streaming (uses Connect-streaming envelope, emits deltas as they arrive)
+ *   - Tool definitions (encoded via `encodeToolDef`) and tool-call events
+ *     (tool_call_start, tool_call_args) decoded from the response stream
+ *   - Usage and finish-reason events for terminal completion
+ *
+ * Wire-protocol: Connect-RPC streaming over HTTPS with manual protobuf
+ * encoding (see `wire.ts`).
+ */
+
+import * as crypto from 'crypto';
+import * as zlib from 'zlib';
+import {
+  encodeMessage,
+  encodeString,
+  encodeVarintField,
+  frameConnectStream,
+  iterFields,
+  parseConnectFrames,
+} from './wire.js';
+import { buildMetadata } from './metadata.js';
+import { getCachedUserJwt } from './auth.js';
+import { getCachedCatalog, ModelNotAvailableError } from './catalog.js';
+import { anySignal, cancelBodyOnAbort } from '../../../lib/abort.js';
+import { resolveDevinApiBaseUrl } from '../../../oauth/devin/api-base.js';
+
+/**
+ * Connect-RPC streaming inactivity timeout. If the cloud sends zero bytes
+ * for this long after the last chunk, we abort the fetch. The cloud's own
+ * idle limit is around 90s on most models; we set ours a little above so
+ * we only trigger when the server has genuinely stopped responding.
+ */
+const CLOUD_STREAM_IDLE_MS = 120_000;
+/** Time-to-first-byte timeout. */
+const CLOUD_STREAM_TTFB_MS = 60_000;
+/** Maximum acceptable Connect-RPC frame length (16 MB). */
+const MAX_FRAME_LEN = 16 * 1024 * 1024;
+
+/**
+ * Per-(apiKey, host) session/cascade ID cache. Cloud uses these for
+ * server-side context caching across turns of the same conversation; if we
+ * mint a fresh sessionId on every call (which we used to), every turn looks
+ * like a brand-new session and the prompt-cache hit ratio is zero.
+ * Single-process scope is enough: opencode lives in one runtime for a TUI
+ * session, and CLI one-shots don't benefit from caching anyway.
+ */
+interface SessionIds {
+  sessionId: string;
+  cascadeId: string;
+}
+/**
+ * Bounded the same way the adapter bounds its cascade-id map: a long-running
+ * proxy sees one entry per (host, api_key) pair, and nothing ever evicted them.
+ */
+const SESSION_CACHE_MAX = 256;
+const sessionCache = new Map<string, SessionIds>();
+function getOrAllocateSessionIds(apiKey: string, host: string, cascadeIdOverride?: string): SessionIds {
+  const key = `${host}\x1f${apiKey}`;
+  let ids = sessionCache.get(key);
+  if (!ids) {
+    ids = {
+      sessionId: crypto.randomUUID(),
+      cascadeId: cascadeIdOverride ?? allocateCascadeId(),
+    };
+    if (sessionCache.size >= SESSION_CACHE_MAX) {
+      const oldest = sessionCache.keys().next().value;
+      if (oldest !== undefined) sessionCache.delete(oldest);
+    }
+    sessionCache.set(key, ids);
+  } else if (cascadeIdOverride && ids.cascadeId !== cascadeIdOverride) {
+    // Caller explicitly requested a different cascadeId — honor it.
+    ids = { sessionId: ids.sessionId, cascadeId: cascadeIdOverride };
+    sessionCache.set(key, ids);
+  }
+  return ids;
+}
+
+/** Drop the cached session IDs — call after logout so a new sign-in starts fresh. */
+export function clearSessionIds(): void {
+  sessionCache.clear();
+}
+
+// ----------------------------------------------------------------------------
+// Per-conversation cascade state — generated client-side; cloud lazy-registers
+// ----------------------------------------------------------------------------
+
+/**
+ * Allocate a fresh cascade UUID. The cloud lazy-registers cascade_id on first
+ * use — confirmed empirically (random UUID accepted, model responded). One
+ * cascade_id per opencode-CLI conversation is fine; reuse across turns to
+ * preserve server-side context.
+ */
+export function allocateCascadeId(): string {
+  return crypto.randomUUID();
+}
+
+// ----------------------------------------------------------------------------
+// Request encoders
+// ----------------------------------------------------------------------------
+
+/**
+ * ChatMessagePrompt {
+ *   #2 source: enum CHAT_MESSAGE_SOURCE_USER=1 / ASSISTANT=2 / SYSTEM=3 / TOOL=4
+ *   #3 prompt: string                          (text content)
+ *   #4 num_tokens: int                          (rough estimate)
+ *   #5 safe_for_code_telemetry: bool            (1 = ok to log)
+ *   #10 images: repeated ImageData              (multimodal)
+ * }
+ *
+ * ImageData (exa.codeium_common_pb.ImageData) {
+ *   #1 base64_data: string
+ *   #2 mime_type: string
+ *   #3 caption: string  (optional)
+ * }
+ */
+function encodeImageData(img: { mimeType: string; base64Data: string; caption?: string }): Buffer {
+  const parts: Buffer[] = [
+    encodeString(1, img.base64Data),
+    encodeString(2, img.mimeType),
+  ];
+  if (img.caption) parts.push(encodeString(3, img.caption));
+  return Buffer.concat(parts);
+}
+
+/**
+ * Encode one ChatToolCall sub-message:
+ *   {#1 id, #2 name, #3 arguments_json}
+ * Verified against `exa.codeium_common_pb.ChatToolCall` from extension.js.
+ */
+function encodeChatToolCall(tc: { id: string; name: string; arguments: string }): Buffer {
+  return Buffer.concat([
+    encodeString(1, tc.id),
+    encodeString(2, tc.name),
+    encodeString(3, tc.arguments),
+  ]);
+}
+
+function encodeChatMessagePrompt(
+  content: ContentPart[],
+  source: number,
+  opts?: { toolCallId?: string; toolCalls?: Array<{ id: string; name: string; arguments: string }> },
+): Buffer {
+  const textParts = content.filter((p): p is { type: 'text'; text: string } => p.type === 'text');
+  const imageParts = content.filter((p): p is { type: 'image'; mimeType: string; base64Data: string; caption?: string } => p.type === 'image');
+  const joined = textParts.map((p) => p.text).join('\n');
+  const parts: Buffer[] = [
+    // #1 message_id. The verified turn-1 capture stamps one on every prompt.
+    encodeString(1, crypto.randomUUID()),
+    encodeVarintField(2, source),
+    encodeString(3, joined),
+  ];
+  // Tool-result message: attach the id of the call this result answers.
+  // Without it, the model can't pair multi-tool conversations.
+  if (opts?.toolCallId) {
+    parts.push(encodeString(7, opts.toolCallId));
+  }
+  // Assistant message with tool_calls: encode each as a ChatToolCall.
+  if (opts?.toolCalls && opts.toolCalls.length > 0) {
+    for (const tc of opts.toolCalls) {
+      parts.push(encodeMessage(6, encodeChatToolCall(tc)));
+    }
+  }
+  for (const img of imageParts) {
+    parts.push(encodeMessage(10, encodeImageData(img)));
+  }
+  return Buffer.concat(parts);
+}
+
+const SOURCE_BY_ROLE: Record<string, number> = {
+  user: 1,
+  assistant: 2,
+  // NOTE: do not send source=3 (SYSTEM) directly — the Codeium chat backend
+  // returns "third-party model provider is experiencing issues" when any
+  // ChatMessagePrompt has source=SYSTEM. The captured LS upstream traffic
+  // shows the IDE inlines system context into the *user* prompt (source=1)
+  // wrapped in <additional_metadata>...</additional_metadata>. We collapse
+  // role:'system' messages into the next user turn before building the
+  // proto — see `collapseSystemIntoUser` below.
+  system: 1,
+  tool: 4,
+};
+
+/**
+ * Collapse OpenAI-style messages so all `role:'system'` entries are inlined
+ * into the immediately-following user message, matching the wire format the
+ * IDE uses. Cognition's chat backend rejects raw role=system entries.
+ *
+ *   [{system: "S1"}, {system: "S2"}, {user: "U1"}, {assistant: "A1"}, {user: "U2"}]
+ *
+ * becomes
+ *
+ *   [{user: "<system>\nS1\nS2\n</system>\nU1"}, {assistant: "A1"}, {user: "U2"}]
+ *
+ * If there's no following user message, the trailing system messages get
+ * appended as a synthesized user turn.
+ */
+function collapseSystemIntoUser(messages: ChatHistoryItem[]): ChatHistoryItem[] {
+  const out: ChatHistoryItem[] = [];
+  let pendingSystem: string[] = [];
+
+  const flushTextOf = (content: ContentPart[]): string =>
+    content.filter((p): p is { type: 'text'; text: string } => p.type === 'text')
+           .map((p) => p.text).join('\n');
+
+  for (const m of messages) {
+    if (m.role === 'system') {
+      const parts = normalizeContent(m.content);
+      const text = flushTextOf(parts);
+      if (text) pendingSystem.push(text);
+    } else if (m.role === 'user' && pendingSystem.length > 0) {
+      const userParts = normalizeContent(m.content);
+      const userText = flushTextOf(userParts);
+      const userImages = userParts.filter((p) => p.type === 'image');
+      const wrapped = `<system>\n${pendingSystem.join('\n\n')}\n</system>\n${userText}`;
+      const newContent: ContentPart[] = [{ type: 'text', text: wrapped }, ...userImages];
+      out.push({ role: 'user', content: newContent });
+      pendingSystem = [];
+    } else {
+      // Flush accumulated system text before any non-system, non-user turn
+      // (assistant / tool) so system instructions keep their leading position
+      // instead of being deferred to a trailing synthesized user message.
+      if (pendingSystem.length > 0) {
+        out.push({
+          role: 'user',
+          content: [{ type: 'text', text: `<system>\n${pendingSystem.join('\n\n')}\n</system>` }],
+        });
+        pendingSystem = [];
+      }
+      out.push(m);
+    }
+  }
+  if (pendingSystem.length > 0) {
+    // Trailing system messages with no following user turn — convert to a
+    // standalone user message so they still reach the model.
+    out.push({
+      role: 'user',
+      content: [{ type: 'text', text: `<system>\n${pendingSystem.join('\n\n')}\n</system>` }],
+    });
+  }
+  return out;
+}
+
+/**
+ * CompletionConfiguration — mirrors the LS-shipped defaults, lets the caller
+ * override the obvious knobs.
+ */
+/** Output cap when the caller named none. */
+const DEFAULT_MAX_OUTPUT_TOKENS = 8192;
+/** Context window when the caller named none. */
+const DEFAULT_CONTEXT_WINDOW = 128_000;
+
+/**
+ * Cognition rejects a temperature of exactly 0 with the same opaque internal
+ * error it uses for a malformed request, so a client asking for deterministic
+ * output would fail every turn. Clamp to the smallest value the wire accepts
+ * rather than silently substituting the service default, which would be a
+ * different answer than the caller asked for.
+ */
+const MIN_TEMPERATURE = 0.0001;
+
+function safeTemperature(value: number | undefined): number {
+  if (value === undefined) return 0.7;
+  return value <= 0 ? MIN_TEMPERATURE : value;
+}
+
+function encodeCompletionConfiguration(opts: {
+  maxOutputTokens?: number;
+  maxInputTokens?: number;
+  temperature?: number;
+  topK?: number;
+  topP?: number;
+}): Buffer {
+  const enc64 = (fieldNum: number, n: number): Buffer => {
+    const b = Buffer.alloc(8);
+    b.writeDoubleLE(n, 0);
+    return Buffer.concat([Buffer.from([(fieldNum << 3) | 1]), b]);
+  };
+  // Tag map, verified by building the same turn with a working client and
+  // diffing the encoded messages field by field: #2 is the OUTPUT cap and #3 is
+  // the context window. This layout had those two swapped, so a caller asking
+  // for 32 output tokens put 32 into the context-window field and the request
+  // came back as an opaque "an internal error occurred" — for every turn, on
+  // every account, which is why free and paid failed identically. #6 and #11
+  // are not part of the message the service accepts.
+  return Buffer.concat([
+    encodeVarintField(1, 1),
+    encodeVarintField(2, opts.maxOutputTokens ?? DEFAULT_MAX_OUTPUT_TOKENS),
+    encodeVarintField(3, opts.maxInputTokens ?? DEFAULT_CONTEXT_WINDOW),
+    enc64(5, safeTemperature(opts.temperature)),
+    encodeVarintField(7, opts.topK ?? 40),
+    enc64(8, opts.topP ?? 1.0),
+  ]);
+}
+
+/**
+ * Multimodal content part — text or image.
+ *
+ * Text: `{ type: 'text', text: '...' }`
+ * Image: `{ type: 'image', mimeType: 'image/png', base64Data: '...' [, caption: '...'] }`
+ *
+ * Matches the OpenAI/@ai-sdk multimodal message shape — we accept their
+ * `image_url: { url: 'data:image/png;base64,...' }` form via {@link parseContent}.
+ */
+export type ContentPart =
+  | { type: 'text'; text: string }
+  | { type: 'image'; mimeType: string; base64Data: string; caption?: string };
+
+export interface ChatHistoryItem {
+  role: 'user' | 'assistant' | 'system' | 'tool';
+  /**
+   * Either a plain string or an array of {@link ContentPart}. Plain strings are
+   * shorthand for `[{ type: 'text', text: '...' }]`.
+   */
+  content: string | ContentPart[];
+  /**
+   * For `role: 'tool'` only — the id of the assistant's preceding tool_call
+   * this message answers. Required by the cloud's chat backend to pair
+   * tool results with calls; without it, multi-tool conversations can't
+   * tell the model which call produced which result. Encoded as
+   * ChatMessagePrompt field #7 (verified against the Windsurf bundled
+   * extension.js proto schema `exa.chat_pb.ChatMessagePrompt`).
+   */
+  tool_call_id?: string;
+  /**
+   * For `role: 'assistant'` only — the tool calls the assistant emitted.
+   * Encoded as ChatMessagePrompt field #6 (repeated ChatToolCall, where
+   * each ChatToolCall has #1 id, #2 name, #3 arguments_json).
+   */
+  tool_calls?: Array<{ id: string; name: string; arguments: string }>;
+}
+
+/**
+ * Normalize ChatHistoryItem content into structured parts. Accepts strings,
+ * OpenAI multimodal `[{type:'text',text}, {type:'image_url',image_url}]`, and
+ * our own `[{type:'image', mimeType, base64Data}]`.
+ */
+function normalizeContent(content: string | ContentPart[] | unknown): ContentPart[] {
+  if (typeof content === 'string') return [{ type: 'text', text: content }];
+  if (!Array.isArray(content)) return [];
+  const out: ContentPart[] = [];
+  // Each element may follow our own ContentPart shape, the OpenAI multimodal
+  // `image_url` shape, or be malformed — narrow defensively per branch.
+  const parts = content as Array<Record<string, unknown>>;
+  for (const p of parts) {
+    if (!p || typeof p !== 'object') continue;
+    if (p.type === 'text' && typeof p.text === 'string') {
+      out.push({ type: 'text', text: p.text });
+    } else if (p.type === 'image' && typeof p.base64Data === 'string') {
+      const mimeType = typeof p.mimeType === 'string' ? p.mimeType : 'image/png';
+      const caption = typeof p.caption === 'string' ? p.caption : undefined;
+      out.push({ type: 'image', mimeType, base64Data: p.base64Data, caption });
+    } else if (p.type === 'image_url' && p.image_url) {
+      // OpenAI/@ai-sdk shape — parse data: URL into base64 + mime.
+      const imgRef = p.image_url as string | { url?: string };
+      const url: string = typeof imgRef === 'string' ? imgRef : (imgRef.url ?? '');
+      const m = url.match(/^data:([^;]+);base64,(.+)$/);
+      if (m) out.push({ type: 'image', mimeType: m[1], base64Data: m[2] });
+      else if (url) out.push({ type: 'text', text: `[image url: ${url}]` });
+    }
+  }
+  return out;
+}
+
+export interface ToolDef {
+  /** Function name. */
+  name: string;
+  /** Plain-English description. */
+  description: string;
+  /** JSON Schema for the function's arguments. */
+  parameters: unknown;
+}
+
+/**
+ * Streaming event emitted by the cloud-direct chat loop.
+ *
+ *   - `text`        : incremental visible content from the assistant
+ *   - `reasoning`   : incremental internal thinking (Anthropic-style, kept
+ *                     separate from visible content; @ai-sdk consumers can
+ *                     render in a collapsed/grey region)
+ *   - `tool_call_*` : function-calling deltas (id+name once, args streamed)
+ *   - `finish`      : stream terminated cleanly with a reason
+ *   - `usage`       : final token-accounting block (input/output/total counts)
+ */
+export type CloudChatEvent =
+  | { kind: 'text'; text: string }
+  | { kind: 'reasoning'; text: string }
+  | { kind: 'tool_call_start'; id: string; name: string }
+  | {
+      kind: 'tool_call_args';
+      argsDelta: string;
+      /**
+       * Tool-call id this delta belongs to, when the cloud surfaced one in
+       * this frame. Cognition's wire format only carries id on the START
+       * frame today, so most argsDelta events arrive without one — callers
+       * route those to the most-recent-start by convention. If Cognition
+       * ever interleaves args across calls, the consumer should prefer
+       * `id` over the rolling lastToolCallId.
+       */
+      id?: string;
+    }
+  // Note: there is no `tool_call_end` event. Cognition's wire format
+  // signals the end of a tool call implicitly — args just stop arriving
+  // for the current id and either a new `tool_call_start` fires or the
+  // stream finishes. Consumers should treat each `tool_call_start` as
+  // ending the previous call.
+  | { kind: 'finish'; reason: 'stop' | 'tool_calls' | 'length' | 'content_filter' }
+  | {
+      kind: 'usage';
+      promptTokens?: number;
+      completionTokens?: number;
+      totalTokens?: number;
+      /**
+       * Tokens served from the cache. Surfaced separately so callers tracking
+       * cost can distinguish them from fresh input tokens (Anthropic / OpenAI
+       * both bill cache reads cheaper than fresh prompts).
+       */
+      cachedInputTokens?: number;
+      /** Tokens written to the cache on this request (Anthropic-style). */
+      cacheCreationInputTokens?: number;
+      /** Reasoning tokens (gpt-5-x reasoning models, Claude thinking variants). */
+      reasoningTokens?: number;
+    };
+
+interface BuildArgs {
+  apiKey: string;
+  userJwt?: string;
+  modelUid: string;
+  messages: ChatHistoryItem[];
+  cascadeId: string;
+  /**
+   * GetChatMessageRequest #22. Optional because it is omitted on a first turn;
+   * the working client only reuses one across a later tool loop.
+   */
+  promptId?: string;
+  sessionId: string;
+  requestId: bigint;
+  triggerId: string;
+  tools?: ToolDef[];
+  /** Default 5 = CHAT_MESSAGE_REQUEST_TYPE_CASCADE (matches captured LS body). */
+  requestType?: number;
+  completionOpts?: {
+    maxOutputTokens?: number;
+    maxInputTokens?: number;
+    temperature?: number;
+    topK?: number;
+    topP?: number;
+  };
+}
+
+/**
+ * ChatToolDefinition proto, observed in the LS upstream traffic:
+ *   { #1 name (string), #2 description (string), #3 parameters_schema (JSON string) }
+ *
+ * Truncation note: Codeium's tool validator rejects very long descriptions
+ * with a generic `failed_precondition: "Unable to process request due to an
+ * MCP configuration issue."` error. opencode ships some tools (notably `bash`)
+ * with ~9.6 KB descriptions packed with examples and rules. We truncate to a
+ * conservative `MAX_DESC_LEN` and append an ellipsis so the cloud accepts
+ * them. The model still gets the first chunk of the description (where the
+ * essential signature lives); detailed examples are sacrificed for
+ * compatibility.
+ */
+/**
+ * The Codeium tool validator rejects any tool whose description hits exactly
+ * 7,000 chars (or more) with a misleading `failed_precondition: "Unable to
+ * process request due to an MCP configuration issue."` error. Binary-search
+ * verified to char-precision:
+ *   - 6,999 chars → server accepts
+ *   - 7,000 chars → server returns MCP error
+ *
+ * The limit is per-description, content-sensitive (plain `a`-repeats up to
+ * 20K work fine; the bash description's exact byte at position 6999 trips
+ * it). We truncate to the maximum-1 (6,998) for a one-char safety margin.
+ *
+ * We do NOT need to aggregate-cap — 200K total tool descriptions across 200
+ * tools was confirmed to pass server-side. Only per-string length is gated.
+ */
+const MAX_TOOL_DESC_LEN = 6998;
+
+/**
+ * Cognition's cloud enforces a case-sensitive, whitespace-exact exact-phrase
+ * blocklist on tool descriptions. Binary-search isolated the trigger to the
+ * 7-word phrase "Takes a task_id parameter identifying the task" — verbatim,
+ * capital T, single spaces — which causes a `permission_denied` trailer error
+ * regardless of model or account tier. Any deviation (lowercase, reword,
+ * reorder, extra whitespace) passes. The phrase appears verbatim in Claude
+ * Code's built-in TaskOutput tool description.
+ *
+ * Rewrite known triggers to meaning-preserving forms. This is a
+ * Cognition-specific constraint alongside the length limit above; if
+ * Cognition adds more blocklisted phrases, extend this table and add a
+ * regression test in tests/devin-adapter.test.ts.
+ *
+ * Not every entry is matched the same way. The Claude Code phrase above is
+ * case-sensitive and whitespace-exact, but the two Codex entries below are
+ * not: against a live account, lowercasing the first word and doubling an
+ * interior space both still produced `permission_denied`, while changing any
+ * single word passed. So those two match case-insensitively with flexible
+ * whitespace and an optional comma, and the rewrite swaps only the leading
+ * verb — the smallest edit measured to clear the filter.
+ *
+ * These two sentences are Codex's own built-in `exec_command` and
+ * `write_stdin` descriptions, verbatim. Every Codex turn carries them, so
+ * before this table knew about them the cloud refused literally every request
+ * from a Codex client — a bare "hi" included — while the same account
+ * answered a hand-built request with an ordinary shell tool. The visible
+ * symptom was the adapter's own blocklist message pointing back at this
+ * table, which is why they are named here rather than left to the next person
+ * to re-bisect.
+ */
+const COGNITION_BLOCKLIST_REWRITES: ReadonlyArray<[RegExp, string]> = [
+  [/\bTakes a task_id parameter identifying the task\b/g, "Accepts a task_id parameter identifying the task"],
+  [
+    /\bRuns\s+a\s+command\s+in\s+a\s+PTY,?\s+returning\s+output\s+or\s+a\s+session\s+ID\s+for\s+ongoing\s+interaction\b/gi,
+    "Executes a command in a PTY, returning output or a session ID for ongoing interaction",
+  ],
+  [
+    /\bWrites\s+characters\s+to\s+an\s+existing\s+unified\s+exec\s+session\s+and\s+returns\s+recent\s+output\b/gi,
+    "Sends characters to an existing unified exec session and returns recent output",
+  ],
+];
+
+function sanitizeToolDescriptionForCognition(description: string): string {
+  let out = description;
+  for (const [pattern, replacement] of COGNITION_BLOCKLIST_REWRITES) {
+    out = out.replace(pattern, replacement);
+  }
+  return out;
+}
+
+/** Test-only: exercise the Cognition blocklist rewrite directly. */
+export function sanitizeToolDescriptionForCognitionForTests(description: string): string {
+  return sanitizeToolDescriptionForCognition(description);
+}
+
+function encodeToolDef(tool: ToolDef): Buffer {
+  const rawDesc = sanitizeToolDescriptionForCognition(tool.description ?? '');
+  const desc =
+    rawDesc.length > MAX_TOOL_DESC_LEN
+      ? rawDesc.slice(0, MAX_TOOL_DESC_LEN - 24) + '\n…(truncated for cloud)'
+      : rawDesc;
+  return Buffer.concat([
+    encodeString(1, tool.name),
+    encodeString(2, desc),
+    encodeString(3, JSON.stringify(tool.parameters ?? {})),
+  ]);
+}
+
+export function buildGetChatMessageRequestForTests(args: BuildArgs): Buffer {
+  return buildGetChatMessageRequest(args);
+}
+
+function buildGetChatMessageRequest(args: BuildArgs): Buffer {
+  const metadata = buildMetadata({
+    apiKey: args.apiKey,
+    userJwt: args.userJwt,
+    sessionId: args.sessionId,
+    requestId: args.requestId,
+    triggerId: args.triggerId,
+    // GetChatMessage accepts only the calibrated identity shape.
+    cloudChatShape: true,
+  });
+
+  // System messages must be inlined into the user turn (Cognition cloud
+  // rejects source=3). See `collapseSystemIntoUser` for the format.
+  const collapsed = collapseSystemIntoUser(args.messages);
+  const promptParts = collapsed.map((m) =>
+    encodeMessage(
+      3,
+      encodeChatMessagePrompt(
+        normalizeContent(m.content),
+        SOURCE_BY_ROLE[m.role] ?? 1,
+        // Thread tool_call_id (for tool results) + tool_calls (for assistant
+        // turns that fired tools) into the proto. Cloud rejects multi-tool
+        // conversations otherwise — it can't pair a tool result with the
+        // assistant call that produced it.
+        {
+          toolCallId: m.role === 'tool' ? m.tool_call_id : undefined,
+          toolCalls: m.role === 'assistant' ? m.tool_calls : undefined,
+        },
+      ),
+    ),
+  );
+
+  const completion = encodeCompletionConfiguration(args.completionOpts ?? {});
+
+  const toolParts: Buffer[] = (args.tools ?? []).map((t) =>
+    encodeMessage(10, encodeToolDef(t)),
+  );
+
+  // Field layout from mitm capture of the LS:
+  //   #1  metadata
+  //   #3  chat_message_prompts (repeated — one element per history turn)
+  //   #7  request_type (varint enum)
+  //   #8  completion_configuration
+  //   #10 tools (repeated ChatToolDefinition)
+  //   #16 cascade_id (string)
+  //   #21 chat_model_uid (string)
+  //   #22 prompt_id (string)
+  return Buffer.concat([
+    encodeMessage(1, metadata),
+    // #2 system_prompt is always written, empty when the caller had none. The
+    // system turn is separately collapsed into the first user message because
+    // source=SYSTEM is refused; this field is the one the wire expects here.
+    encodeString(2, ''),
+    ...promptParts,
+    encodeVarintField(7, args.requestType ?? 5),
+    encodeMessage(8, completion),
+    ...toolParts,
+    // #15 session model config: { id, turn, 4 }. Present on every verified
+    // request.
+    encodeMessage(15, Buffer.concat([
+      encodeString(1, crypto.randomUUID()),
+      encodeVarintField(2, 1),
+      encodeVarintField(3, 4),
+    ])),
+    encodeString(16, args.cascadeId),
+    encodeVarintField(20, 1),
+    encodeString(21, args.modelUid),
+    // #22 is deliberately omitted. It is a user-exchange id that only appears
+    // from the second turn onward and is reused across that turn's tool loop; a
+    // fresh per-request uuid matches neither shape.
+  ]);
+}
+
+// ----------------------------------------------------------------------------
+// Response parsing — pull `delta_text` (top-level field #9) out of each frame
+// ----------------------------------------------------------------------------
+
+/**
+ * Decode a single streaming ChatMessage proto frame into one or more
+ * CloudChatEvents. Captured shape (from a tool-using swe-1.6 chat):
+ *
+ *   ChatMessage {
+ *     #1  bot_id (string)
+ *     #2  timestamp { seconds, nanos }
+ *     #5  finish_reason (varint — 10 = "tool_calls" observed, others unknown)
+ *     #6  ToolCallDelta {
+ *           #1 id (string, only on first tool-call frame)
+ *           #2 name (string, only on first tool-call frame)
+ *           #3 arguments_delta (string, JSON fragment, streamed)
+ *         }
+ *     #7  ChatStatus { #6 status_code, #9 model_name }
+ *     #9  delta_text (string)
+ *     #12 (fixed64) some_hash
+ *     #17 (string) message_uuid
+ *     #28 UsageStats { #1 label, ... }
+ *   }
+ *
+ * #9 appears both at top-level (text delta) AND inside #7 (model_name).
+ * iterFields walks top-level only, so we don't confuse the two.
+ *
+ * #5 is the finish_reason. Observed value `10` = tool_calls finish. We map
+ * any non-zero to 'tool_calls' for now (and let the caller fall back to
+ * 'stop' if no tool_call deltas were emitted).
+ */
+function* decodeChatFrame(proto: Buffer): Generator<CloudChatEvent> {
+  for (const f of iterFields(proto)) {
+    if (f.num === 3 && f.wire === 2 && Buffer.isBuffer(f.value)) {
+      // Visible delta_text — what the user should SEE in the chat.
+      //
+      // We previously had this mapping inverted (#3 = thinking, #9 = visible),
+      // which produced two compounding bugs in the TUI:
+      //   1. The model's CoT was rendered as plain content, so the user saw
+      //      "The user wants me to X..." instead of the answer.
+      //   2. The actual answer (which lives in #3) was silently dropped — so
+      //      the assistant turn appeared to end after the CoT with nothing
+      //      after, matching the "model wrote reasoning then went silent"
+      //      symptom the user reported.
+      // Verified live: prompted swe-1.6 with "explain then answer 2+2"; #3
+      // streamed "2+2=4 because... 4" while #9 streamed the meta-narration
+      // "The user wants me to perform a reasoning task...".
+      const s = (f.value as Buffer).toString('utf8');
+      if (s) yield { kind: 'text', text: s };
+    } else if (f.num === 9 && f.wire === 2 && Buffer.isBuffer(f.value)) {
+      // Internal thinking / chain-of-thought. Surface as `reasoning` so
+      // @ai-sdk consumers (opencode TUI) render it in a collapsed grey
+      // block instead of inline with the answer.
+      const s = (f.value as Buffer).toString('utf8');
+      if (s) yield { kind: 'reasoning', text: s };
+    } else if (f.num === 6 && f.wire === 2 && Buffer.isBuffer(f.value)) {
+      let id: string | undefined;
+      let name: string | undefined;
+      let argsDelta: string | undefined;
+      for (const sf of iterFields(f.value as Buffer)) {
+        if (sf.wire === 2 && Buffer.isBuffer(sf.value)) {
+          const s = (sf.value as Buffer).toString('utf8');
+          if (sf.num === 1) id = s;
+          else if (sf.num === 2) name = s;
+          else if (sf.num === 3) argsDelta = s;
+        }
+      }
+      if (id !== undefined && name !== undefined) {
+        yield { kind: 'tool_call_start', id, name };
+      }
+      if (argsDelta !== undefined) {
+        // Pass through `id` when this frame carries one (Cognition only
+        // sets it on the start frame today, but defending against future
+        // interleaving). Callers should prefer `id` over their rolling
+        // lastToolCallId when both are available.
+        yield { kind: 'tool_call_args', argsDelta, ...(id !== undefined ? { id } : {}) };
+      }
+    } else if (f.num === 5 && f.wire === 0) {
+      const v = Number(f.value);
+      // exa.codeium_common_pb.StopReason → OpenAI finish_reason.
+      // Source of truth: Windsurf extension.js sets `setEnumType("StopReason", [...])`
+      //   0 UNSPECIFIED      → "stop" (no signal — treat as natural end)
+      //   1 INCOMPLETE       → "length" (request cut short, model wanted more)
+      //   2 STOP_PATTERN     → "stop"   (model emitted its stop sequence — NORMAL)
+      //   3 MAX_TOKENS       → "length"
+      //   4-9 internal       → "stop"
+      //  10 FUNCTION_CALL    → "tool_calls"
+      //  11 CONTENT_FILTER   → "content_filter"
+      //  12 NON_INSERTION    → "stop"
+      //  13 ERROR            → "stop"   (errors come as Connect trailer, not via this)
+      //
+      // We had 2 and 3 swapped previously, which made the model's normal
+      // STOP_PATTERN look like "length" → @ai-sdk treated complete responses
+      // as truncated. That was the "model wrote reasoning then went silent"
+      // symptom the user kept hitting.
+      let reason: 'stop' | 'tool_calls' | 'length' | 'content_filter' = 'stop';
+      if (v === 10) reason = 'tool_calls';
+      else if (v === 11) reason = 'content_filter';
+      else if (v === 1 || v === 3) reason = 'length';
+      // else stays 'stop' for 0/2/4-9/12/13
+      yield { kind: 'finish', reason };
+    } else if (f.num === 28 && f.wire === 2 && Buffer.isBuffer(f.value)) {
+      const usage = decodeUsageBlock(f.value as Buffer);
+      if (usage) yield usage;
+    }
+  }
+}
+
+/**
+ * UsageStats block at proto field #28. Captured shape (mitm of a real call):
+ *
+ *   UsageStats {
+ *     #1 label = "Token Usage"
+ *     #2 entries [
+ *       UsageEntry {
+ *         #1 label = "Input tokens" / "Output tokens" / "Cached tokens" / ...
+ *         #2 value (fixed32 — IEEE 754 float, OpenAI-style count cast)
+ *         #3 unit = " tokens"
+ *         #5 metric_id = "input_tokens" / "output_tokens" / ...
+ *       },
+ *       ...
+ *     ]
+ *   }
+ *
+ * We extract the standard input/output counts and synthesize a `total`.
+ * Anything else (cached, reasoning_tokens, …) is dropped for v1.
+ */
+function decodeUsageBlock(buf: Buffer): CloudChatEvent | null {
+  let promptTokens: number | undefined;
+  let completionTokens: number | undefined;
+  let cachedInputTokens: number | undefined;
+  let cacheCreationInputTokens: number | undefined;
+  let reasoningTokens: number | undefined;
+
+  for (const f of iterFields(buf)) {
+    // Each UsageEntry lives at field 2 (repeated). Field 1 is the block label
+    // ("Token Usage"); skip.
+    if (f.num !== 2 || f.wire !== 2 || !Buffer.isBuffer(f.value)) continue;
+
+    // Observed entry shape:
+    //   UsageEntry {
+    //     #4 (sub-message) {
+    //       #1 label = "Input tokens" / "Output tokens"
+    //       #2 (fixed32) value (IEEE 754 LE float — count as float)
+    //       #3 unit = " token"
+    //       #4 unit_plural = " tokens"
+    //     }
+    //     #5 metric_id = "input_tokens" / "output_tokens" / "cached_input_tokens" / ...
+    //   }
+    let entryMetric: string | undefined;
+    let entryValue: number | undefined;
+    for (const sf of iterFields(f.value as Buffer)) {
+      if (sf.num === 5 && sf.wire === 2 && Buffer.isBuffer(sf.value)) {
+        entryMetric = (sf.value as Buffer).toString('utf8');
+      } else if (sf.num === 4 && sf.wire === 2 && Buffer.isBuffer(sf.value)) {
+        // Recurse into the displayed-dimension submessage to pull the fixed32
+        // value at its field 2.
+        for (const ssf of iterFields(sf.value as Buffer)) {
+          if (ssf.num === 2 && ssf.wire === 5 && Buffer.isBuffer(ssf.value)) {
+            entryValue = (ssf.value as Buffer).readFloatLE(0);
+            break;
+          }
+        }
+      }
+    }
+    if (entryMetric && entryValue !== undefined && Number.isFinite(entryValue)) {
+      const n = Math.round(entryValue);
+      if (entryMetric === 'input_tokens') promptTokens = n;
+      else if (entryMetric === 'output_tokens') completionTokens = n;
+      else if (entryMetric === 'cached_input_tokens' || entryMetric === 'cache_read_input_tokens') {
+        cachedInputTokens = (cachedInputTokens ?? 0) + n;
+      } else if (entryMetric === 'cache_creation_input_tokens') {
+        cacheCreationInputTokens = (cacheCreationInputTokens ?? 0) + n;
+      } else if (entryMetric === 'reasoning_tokens' || entryMetric === 'output_reasoning_tokens') {
+        reasoningTokens = (reasoningTokens ?? 0) + n;
+      }
+    }
+  }
+  if (promptTokens === undefined && completionTokens === undefined) return null;
+  // totalTokens reflects what OpenAI's API counts as billable: input +
+  // output. Cached / cache-creation / reasoning subtotals are surfaced as
+  // additional fields so callers that want a fuller picture (e.g. cost
+  // breakdown for reasoning models) can read them, but they're NOT
+  // double-counted into total.
+  const total = (promptTokens ?? 0) + (completionTokens ?? 0);
+  return {
+    kind: 'usage',
+    promptTokens,
+    completionTokens,
+    totalTokens: total > 0 ? total : undefined,
+    cachedInputTokens,
+    cacheCreationInputTokens,
+    reasoningTokens,
+  };
+}
+
+// ----------------------------------------------------------------------------
+// Public API: streamChat
+// ----------------------------------------------------------------------------
+
+export interface CloudChatRequest {
+  /** Persistent OAuth-issued api_key (`devin-session-token$<JWT>`). */
+  apiKey: string;
+  /** Pre-resolved API server URL from RegisterUser (falls back to default). */
+  apiServerUrl?: string;
+  /** Model UID — e.g. `swe-1-6`, `kimi-k2-6`, `claude-opus-4-7-medium`. */
+  modelUid: string;
+  /** Chat history. */
+  messages: ChatHistoryItem[];
+  /**
+   * Tool definitions available to the model. Cloud encodes these in the
+   * GetChatMessage request's `tools` field (proto #10). When set, the model
+   * may emit `tool_call_start`/`_args`/`_end` events instead of plain text.
+   */
+  tools?: ToolDef[];
+  /** Cascade ID — reuse across turns of the same conversation. */
+  cascadeId?: string;
+  /** Optional sampling overrides. */
+  completionOpts?: BuildArgs['completionOpts'];
+  /** Override request_type (default = 5, CASCADE). */
+  requestType?: number;
+  /** Abort signal — closes the fetch stream. */
+  signal?: AbortSignal;
+}
+
+export class CloudChatError extends Error {
+  constructor(message: string, public readonly code?: string, public readonly traceId?: string) {
+    super(message);
+    this.name = 'CloudChatError';
+  }
+}
+
+const TRACE_ID_RE = /\(trace ID: ([0-9a-f]+)\)/i;
+
+/**
+ * Stream chat events from the cloud. Yields CloudChatEvent (text deltas, tool
+ * call deltas, finish reason). Use `streamChatText` for legacy text-only iteration.
+ *
+ * On error (auth fail, quota exhausted, malformed request) throws a
+ * CloudChatError with the cloud's `code` + `traceId` for diagnostics.
+ */
+export async function* streamChatEvents(req: CloudChatRequest): AsyncGenerator<CloudChatEvent> {
+  // The api-server host comes from RegisterUser through the credential store.
+  // Validate it here too: this request body carries the api_key, so an
+  // unallowlisted host is credential exfiltration rather than a wrong endpoint.
+  const host = resolveDevinApiBaseUrl(req.apiServerUrl);
+  // The hosted chat path does not require the short-lived user_jwt; the working
+  // reference omits it by default. Minting it is opt-in so a mint failure or a
+  // JWT the chat service does not accept cannot break every turn.
+  const userJwt = process.env.OPENCODEX_DEVIN_SEND_USER_JWT === "1"
+    ? await getCachedUserJwt(req.apiKey, host, req.signal)
+    : undefined;
+
+  // Pre-flight: consult the per-account model catalog. Cognition's cloud
+  // returns an opaque `permission_denied: "an internal error occurred (trace
+  // ID: ...)"` for every chat call that targets a model not enabled on the
+  // caller's tier — issue #14. The catalog's `disabled` flag is the
+  // authoritative source for "can this account run this UID"; we surface a
+  // named error here so the user knows why instead of guessing.
+  //
+  // Best-effort: if the catalog fetch fails (network, auth, schema drift) we
+  // pass through to the chat call. The cloud will still surface its own
+  // error and the trailer-error path below enriches the message in-place.
+  // Treat an empty catalog (schema drift / unexpected response) as "no catalog"
+  // so chat passes through instead of failing every request.
+  const catalog = await getCachedCatalog(req.apiKey, host, req.signal).catch(() => null);
+  if (catalog && catalog.byUid.size > 0) {
+    const entry = catalog.byUid.get(req.modelUid);
+    if (!entry) {
+      throw new ModelNotAvailableError(req.modelUid, req.modelUid, 'not_listed');
+    }
+    if (entry.disabled) {
+      throw new ModelNotAvailableError(req.modelUid, entry.label, 'disabled');
+    }
+  }
+
+  // Reuse session + cascade ids across calls for the same (apiKey, host).
+  // Without this, every turn looks like a brand-new server-side session
+  // and the cloud's prompt cache never hits — significant cost regression
+  // for long conversations.
+  const sessionIds = getOrAllocateSessionIds(req.apiKey, host, req.cascadeId);
+
+  const proto = buildGetChatMessageRequest({
+    apiKey: req.apiKey,
+    userJwt,
+    modelUid: req.modelUid,
+    messages: req.messages,
+    tools: req.tools,
+    cascadeId: sessionIds.cascadeId,
+    sessionId: sessionIds.sessionId,
+    requestId: BigInt(Date.now()),
+    triggerId: crypto.randomUUID(),
+    requestType: req.requestType,
+    completionOpts: req.completionOpts,
+  });
+  // The request envelope goes up uncompressed. A gzipped GetChatMessage frame is
+  // rejected with the same opaque `invalid_argument: an internal error occurred`
+  // the short fingerprint produces, and it is one of three things that have to be
+  // right together — the other two are the doubled Basic credential and the
+  // 732-character Metadata #31.
+  const framed = frameConnectStream(proto, false);
+  const body = new Blob([new Uint8Array(framed)], { type: "application/connect+proto" });
+
+  // Compose caller signal with a TTFB timeout. If the cloud takes longer
+  // than CLOUD_STREAM_TTFB_MS to start the response, abort. Once any byte
+  // arrives we cancel the TTFB timer and start the per-chunk idle timer
+  // inside the read loop instead.
+  const ttfbController = new AbortController();
+  const ttfbTimer = setTimeout(() => ttfbController.abort(new Error(`cloud-direct: time-to-first-byte timeout (${CLOUD_STREAM_TTFB_MS}ms)`)), CLOUD_STREAM_TTFB_MS);
+  const ttfbSignal = ttfbController.signal;
+  // Compose req.signal + ttfbSignal. AbortSignal.any was added in Node
+  // 20.3 / Bun 1.0; our `engines` allows Node ≥18, so on Node 18-20.2 the
+  // built-in is missing. The previous fallback `req.signal ?? ttfbSignal`
+  // silently discarded one of the two signals (TTFB if caller passed
+  // one), defeating the timeout guard. anySignal() is a real polyfill.
+  const composed = req.signal ? anySignal([req.signal, ttfbSignal]) : undefined;
+  const initialSignal: AbortSignal = composed?.signal ?? ttfbSignal;
+
+  let resp: Response;
+  try {
+    resp = await fetch(`${host}/exa.api_server_pb.ApiServerService/GetChatMessage`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/connect+proto',
+        'Connect-Protocol-Version': '1',
+        'Connect-Accept-Encoding': 'gzip',
+        // The credential is the session token doubled and dash-joined. A single
+        // copy is refused with permission_denied. The protobuf body keeps one
+        // copy, in Metadata #3.
+        Authorization: `Basic ${req.apiKey}-${req.apiKey}`,
+        'User-Agent': 'connect-es/2.0.0',
+        Accept: '*/*',
+      },
+      body,
+      redirect: 'error',
+      signal: initialSignal,
+    });
+  } finally {
+    clearTimeout(ttfbTimer);
+    // The composed signal only guards the headers hop; the body is cancelled
+    // through cancelBodyOnAbort below. Detaching here keeps a long-lived caller
+    // signal from collecting one listener per turn.
+    composed?.cleanup();
+  }
+
+  if (!resp.ok) {
+    // The body is not echoed into the message. This error reaches the adapter's
+    // error event and /api/logs, and a Connect error can quote the request that
+    // produced it - which is the request holding the api_key.
+    throw new CloudChatError(`GetChatMessage failed (HTTP ${resp.status})`, undefined);
+  }
+  if (!resp.body) {
+    throw new CloudChatError('GetChatMessage response had no body stream');
+  }
+
+  // Cancel the body when the client goes away. Without this the read loop never
+  // observes req.signal after headers arrive: the turn keeps draining until the
+  // idle timer fires, and the stream then ends without an EOS trailer, which
+  // this function would report as a truncated upstream response rather than as
+  // the cancellation it actually was.
+  const detachBodyCancel = cancelBodyOnAbort(resp.body, req.signal);
+
+  // Incremental parsing. We previously did `pending = Buffer.concat([pending,
+  // chunk])` per chunk — O(n²) over a long stream because every chunk copies
+  // every buffered byte again. Now we keep a queue of arriving chunks with a
+  // running offset; we only `Buffer.concat` when a frame straddles a chunk
+  // boundary, and we slice/drop fully-consumed chunks immediately. For
+  // typical 50-200KB responses this is ~5x faster and produces zero waste.
+  const chunkQueue: Buffer[] = [];
+  let queuedBytes = 0;
+  // Bun + Node ReadableStream readers diverge on the type-level shape
+  // (Bun's includes a `readMany` method); both work the same at runtime.
+  const reader = resp.body.getReader() as ReadableStreamDefaultReader<Uint8Array>;
+  let trailerError: { code?: string; message: string; traceId?: string } | null = null;
+  let sawEos = false;
+
+  /**
+   * Try to read the next `n` bytes from the chunk queue WITHOUT consuming
+   * them. Returns null if not enough buffered.
+   */
+  function peek(n: number): Buffer | null {
+    if (queuedBytes < n) return null;
+    if (chunkQueue.length === 1 && chunkQueue[0].length >= n) {
+      return chunkQueue[0].slice(0, n);
+    }
+    // Cross-chunk peek — concat just the prefix we need.
+    const parts: Buffer[] = [];
+    let remaining = n;
+    for (const c of chunkQueue) {
+      if (remaining <= 0) break;
+      if (c.length <= remaining) {
+        parts.push(c);
+        remaining -= c.length;
+      } else {
+        parts.push(c.slice(0, remaining));
+        remaining = 0;
+      }
+    }
+    return Buffer.concat(parts, n);
+  }
+
+  /** Drop the first `n` bytes from the chunk queue. */
+  function drop(n: number): void {
+    queuedBytes -= n;
+    let remaining = n;
+    while (remaining > 0 && chunkQueue.length > 0) {
+      const head = chunkQueue[0];
+      if (head.length <= remaining) {
+        chunkQueue.shift();
+        remaining -= head.length;
+      } else {
+        chunkQueue[0] = head.slice(remaining);
+        remaining = 0;
+      }
+    }
+  }
+
+  // Track the idle timer at outer scope so the finally block can clear it
+  // regardless of how we exit the read loop (clean done, throw, etc).
+  // Previously this lived inside `try { ... }` and was only cleared on
+  // normal exit — an error path left a 120s timer in the event loop and
+  // the process refused to exit promptly.
+  let idleTimer: ReturnType<typeof setTimeout> | null = null;
+  try {
+    const resetIdle = (): Promise<{ value?: Uint8Array; done: boolean }> => {
+      if (idleTimer) clearTimeout(idleTimer);
+      const idleController = new AbortController();
+      idleTimer = setTimeout(
+        () => idleController.abort(new Error(`cloud-direct: idle timeout (${CLOUD_STREAM_IDLE_MS}ms with no bytes)`)),
+        CLOUD_STREAM_IDLE_MS,
+      );
+      // Race the reader.read() against idle abort. When abort wins, we
+      // also actively `cancel()` the underlying body stream so the
+      // pending read() resolves promptly with done=true instead of
+      // hanging on the now-dead TCP socket until the OS notices.
+      //
+      // Promise-handling carefully: the reader.read() promise can settle
+      // AFTER the outer race rejects (we cancelled, the read eventually
+      // sees the cancellation and either resolves with done=true or
+      // rejects with an abort error). We attach an explicit `.catch(()=>{})`
+      // on the read promise so any post-race rejection doesn't surface as
+      // an unhandled-rejection warning in the host runtime.
+      return new Promise((resolve, reject) => {
+        let settled = false;
+        const settle = (fn: () => void): void => {
+          if (settled) return;
+          settled = true;
+          fn();
+        };
+        const readP = reader.read();
+        // Defensive: swallow any post-race rejection. If the outer promise
+        // already settled via the abort listener, we still need a handler
+        // attached to readP or Node logs an unhandledRejection.
+        readP.catch(() => { /* swallowed; outer promise already rejected */ });
+
+        idleController.signal.addEventListener('abort', () => {
+          try { void resp.body?.cancel(idleController.signal.reason ?? new Error('idle abort')); } catch { /* */ }
+          settle(() => reject(idleController.signal.reason ?? new Error('idle abort')));
+        }, { once: true });
+
+        readP.then(
+          (v) => settle(() => resolve(v)),
+          (e) => settle(() => reject(e)),
+        );
+      });
+    };
+
+    while (true) {
+      const { value, done } = await resetIdle();
+      if (done) break;
+      if (value) {
+        chunkQueue.push(Buffer.from(value));
+        queuedBytes += value.length;
+      }
+
+      // Drain every complete frame currently buffered.
+      while (queuedBytes >= 5) {
+        const header = peek(5);
+        if (!header) break;
+        const flags = header[0];
+        const len = header.readUInt32BE(1);
+        // Cap frame length to prevent memory exhaustion from a corrupt/malicious
+        // length prefix. 16MB is well above any legitimate Connect-RPC frame.
+        if (len > MAX_FRAME_LEN) {
+          throw new CloudChatError(`Connect frame length ${len} exceeds ${MAX_FRAME_LEN} byte cap`);
+        }
+        if (queuedBytes < 5 + len) break; // frame still arriving
+        drop(5);
+        const raw = peek(len) ?? Buffer.alloc(0);
+        drop(len);
+
+        let payload = raw;
+        if (flags & 0x01) {
+          try {
+            // MAX_FRAME_LEN caps the COMPRESSED frame, so without an output cap
+            // a 16 MiB gzip frame can still inflate to gigabytes. The inbound
+            // request path (src/server/request-decompress.ts) already bounds
+            // decompression the same way.
+            payload = zlib.gunzipSync(raw, { maxOutputLength: MAX_FRAME_LEN });
+          } catch (gzipErr) {
+            const code = (gzipErr as NodeJS.ErrnoException).code;
+            if (code === 'ERR_BUFFER_TOO_LARGE') {
+              throw new CloudChatError(`Connect frame inflates past the ${MAX_FRAME_LEN} byte cap`, 'frame_too_large');
+            }
+            // Corrupt compressed frame — surface as a CloudChatError instead
+            // of falling through and re-parsing raw gzip bytes as proto
+            // (which used to misparse silently downstream).
+            throw new CloudChatError(`Connect frame gunzip failed: ${(gzipErr as Error).message}`);
+          }
+        }
+        const eos = (flags & 0x02) !== 0;
+
+        if (eos) {
+          sawEos = true;
+          // Trailer: {} on success, {"error":{code,message}} on failure.
+          const text = payload.toString('utf8');
+          if (text && text.includes('"error"')) {
+            let code: string | undefined;
+            let message = text;
+            try {
+              const j = JSON.parse(text) as { error?: { code?: string; message?: string } };
+              code = j.error?.code;
+              if (j.error?.message) message = j.error.message;
+            } catch { /* keep raw */ }
+            const traceMatch = message.match(TRACE_ID_RE);
+            trailerError = { code, message, traceId: traceMatch?.[1] };
+          }
+          continue;
+        }
+        yield* decodeChatFrame(payload);
+      }
+    }
+  } finally {
+    // Always clear the idle timer. The previous "clear on normal exit
+    // only" path leaked a 120s setTimeout into the event loop on any
+    // throw (idle timeout, gunzip error, trailer error, etc), keeping
+    // the process from exiting promptly.
+    if (idleTimer) clearTimeout(idleTimer);
+    // Cancel the underlying body stream on any non-clean exit so the TCP
+    // connection is released. `releaseLock` alone leaves the body in a
+    // dangling state; we have to call `cancel` on the response body
+    // itself (cancel-via-reader requires holding the lock). Fire and
+    // forget — there's nothing meaningful to do if cancel rejects.
+    try { reader.releaseLock(); } catch { /* */ }
+    try { void resp.body?.cancel(); } catch { /* */ }
+  }
+
+  if (trailerError) {
+    // Cognition uses `permission_denied: "an internal error occurred (trace
+    // ID: …)"` as a catch-all for "your account can't run this model" — same
+    // root cause issue #14 reported. The pre-flight above catches this when
+    // the catalog disagrees with the call, but the catalog can lag (a model
+    // that was enabled at fetch time may have been gated between then and
+    // now) or be missing (network failure caused a fall-through). When the
+    // raw trailer is this exact shape, swap in a message that names the
+    // model and explains the likely cause rather than re-passing
+    // Cognition's opaque text. The cloud's original message is appended in
+    // parens so users (and bug reports) still have it verbatim.
+    // Both codes carry this shape. Cognition uses `invalid_argument` for a
+    // request it could not accept and `permission_denied` for one it would not,
+    // and the message body is the same opaque sentence either way.
+    const isOpaqueDenial =
+      (trailerError.code === 'permission_denied' || trailerError.code === 'invalid_argument') &&
+      /an internal error occurred/i.test(trailerError.message);
+    if (isOpaqueDenial) {
+      const enriched =
+        `Cognition denied this request for model "${req.modelUid}" with the opaque ` +
+        `"an internal error occurred" message, which it uses for both a malformed ` +
+        `request and a refused one. In practice this has meant the request, not ` +
+        `the account: the same sentence came back for every turn until the ` +
+        `CompletionConfiguration tag map was corrected, and a temperature of ` +
+        `exactly 0 still produces it. Check the request before the plan — ` +
+        `tests/providers/devin-hardening.test.ts pins the field layout the ` +
+        `service accepts. If the request is unchanged and this is new, the ` +
+        `account's model access is the next thing to check. ` +
+        `(cloud trace ID: ${trailerError.traceId ?? 'n/a'})`;
+      throw new CloudChatError(enriched, trailerError.code, trailerError.traceId);
+    }
+    // Cognition also returns `permission_denied` when a tool description
+    // contains a blocklisted phrase that the sanitizer above did not catch
+    // (e.g. Cognition added a new phrase). Surface a clear message so the
+    // user knows to check tool descriptions rather than suspect auth/tier.
+    // Only blame the blocklist when tools were actually sent. Asserting it for
+    // every permission_denied sent users to inspect a tool table that had
+    // nothing to do with an ordinary ACL or tier denial.
+    if (trailerError.code === 'permission_denied' && (req.tools?.length ?? 0) > 0) {
+      const enriched =
+        `Cognition denied this request (permission_denied). If tool descriptions ` +
+        `are present, a blocklisted phrase may have triggered this — see the ` +
+        `COGNITION_BLOCKLIST_REWRITES table in cloud-direct/chat.ts. ` +
+        // Keep the cloud's own sentence. Replacing it outright is what made the
+        // two Codex entries in that table expensive to find: the message named
+        // the table but dropped the only text that could have said whether this
+        // was a phrase match at all.
+        `(cloud message: ${trailerError.message}) ` +
+        `(cloud trace ID: ${trailerError.traceId ?? 'n/a'})`;
+      throw new CloudChatError(enriched, trailerError.code, trailerError.traceId);
+    }
+    throw new CloudChatError(trailerError.message, trailerError.code, trailerError.traceId);
+  }
+  // Truncation detection: the cloud always terminates a successful stream
+  // with an EOS trailer. If we hit `done` from the body reader without one,
+  // the connection dropped mid-frame and any bytes still in the queue are
+  // garbage. Previously those leftover bytes were silently discarded and
+  // the consumer saw a clean stop with no error — looked like the model
+  // had finished. Now we surface it.
+  detachBodyCancel();
+  if (req.signal?.aborted) {
+    // The caller cancelled. The missing EOS trailer is the expected consequence
+    // of that cancellation, not evidence that the cloud dropped the response.
+    return;
+  }
+  if (!sawEos) {
+    throw new CloudChatError(
+      `Cloud stream ended without EOS trailer (${queuedBytes} bytes orphaned). ` +
+      `Connection likely dropped mid-response.`,
+      'truncated_stream',
+    );
+  }
+}
+
+/**
+ * Back-compat: yield text content only (drops tool calls). The plugin uses
+ * streamChatEvents directly when it needs to surface tool_calls.
+ */
+export async function* streamChat(req: CloudChatRequest): AsyncGenerator<string> {
+  for await (const ev of streamChatEvents(req)) {
+    if (ev.kind === 'text') yield ev.text;
+  }
+}
+
+// `parseConnectFrames` is no longer needed by streamChat itself, but exported
+// from wire.ts for one-shot callers + tests.
+void parseConnectFrames;
diff --git a/src/adapters/devin/cloud-direct/index.ts b/src/adapters/devin/cloud-direct/index.ts
new file mode 100644
index 0000000000..98dfcea9de
--- /dev/null
+++ b/src/adapters/devin/cloud-direct/index.ts
@@ -0,0 +1,65 @@
+/*
+ * Derived from rsvedant/opencode-windsurf-auth (src/cloud-direct/), MIT licensed.
+ *
+ * MIT License
+ * Copyright (c) 2026 Vedant
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+/**
+ * Public surface of the cloud-direct module.
+ *
+ * Usage:
+ *   import { streamChat } from './cloud-direct/index.js';
+ *
+ *   for await (const delta of streamChat({
+ *     apiKey: creds.apiKey,
+ *     apiServerUrl: creds.apiServerUrl,
+ *     modelUid: 'swe-1-6',
+ *     messages: [{ role: 'user', content: 'hi' }],
+ *   })) {
+ *     process.stdout.write(delta);
+ *   }
+ */
+
+export {
+  streamChat,
+  streamChatEvents,
+  allocateCascadeId,
+  CloudChatError,
+  type CloudChatRequest,
+  type ChatHistoryItem,
+  type CloudChatEvent,
+  type ToolDef,
+} from './chat.js';
+
+export {
+  mintUserJwt,
+  getCachedUserJwt,
+  clearCachedUserJwt,
+  CloudAuthError,
+} from './auth.js';
+
+export {
+  getCachedCatalog,
+  clearCachedCatalog,
+  ModelNotAvailableError,
+  type ModelCatalogEntry,
+  type CacheEntry,
+} from './catalog.js';
diff --git a/src/adapters/devin/cloud-direct/metadata.ts b/src/adapters/devin/cloud-direct/metadata.ts
new file mode 100644
index 0000000000..b371abe06a
--- /dev/null
+++ b/src/adapters/devin/cloud-direct/metadata.ts
@@ -0,0 +1,134 @@
+/*
+ * Derived from rsvedant/opencode-windsurf-auth (src/cloud-direct/), MIT licensed,
+ * Copyright (c) 2026 Vedant. The full notice is in ./index.ts.
+ */
+/**
+ * `exa.codeium_common_pb.Metadata` proto builder.
+ *
+ * Field numbers come from src/plugin/discovery.ts (which reads the bundled
+ * extension.js for live numbers). For cloud-direct we hard-code the canonical
+ * set of fields the LS always populates — the IDE-extracted dynamic numbers
+ * would help if Windsurf renumbers, but we don't have a way to refresh those
+ * without the bundled extension.js path being present.
+ *
+ * Captured from real LS upstream traffic via mitm reverse-proxy. See
+ * docs/CLOUD_DIRECT.md → "The exact captured request body (annotated)".
+ */
+
+import {
+  encodeMessage,
+  encodeString,
+  encodeTimestampBody,
+  encodeVarintField,
+} from './wire.js';
+import { randomBytes } from 'node:crypto';
+
+/**
+ * extension_version + ide_version sent to the cloud. It MUST be a string the
+ * cloud recognizes as a real client release: an unknown version comes back as
+ * an opaque "an internal error occurred", with no hint that the version is what
+ * it objected to.
+ *
+ * Pinned to the version the shipped desktop client reports
+ * (`product.json` -> `windsurfVersion`) rather than to anything of ours. The
+ * previous pin of "2.0.0" predates the Devin rebrand and no longer chats.
+ * `OPENCODEX_DEVIN_CLIENT_VERSION` overrides it, which is the escape hatch when
+ * Cognition retires a version before this constant is updated.
+ */
+const WINDSURF_VERSION_STRING = process.env.OPENCODEX_DEVIN_CLIENT_VERSION?.trim() || '3.9.19';
+
+/**
+ * Identity the hosted chat RPC expects, which is not the desktop client's.
+ * GetChatMessage is calibrated against a different client name and version, and
+ * sending the IDE's own strings is one of the ways the request comes back as an
+ * opaque "an internal error occurred".
+ */
+const CLOUD_CHAT_CLIENT_NAME = 'chisel';
+const CLOUD_CHAT_CLIENT_VERSION = process.env.OPENCODEX_DEVIN_CHAT_CLIENT_VERSION?.trim() || '2026.8.18';
+const CLOUD_CHAT_OS = 'windows';
+
+/**
+ * Metadata #31 is a device fingerprint, and the server checks its shape rather
+ * than its value: 732 hex characters (366 bytes). Anything shorter — including
+ * absent — is rejected with the same opaque internal error, and a fresh random
+ * value per request is accepted, so nothing here identifies the machine.
+ */
+const DEVICE_FINGERPRINT_BYTES = 366;
+
+export interface MetadataInput {
+  /** Persistent api_key from OAuth (`devin-session-token$<JWT>`). */
+  apiKey: string;
+  /**
+   * Fresh user_jwt from GetUserJwt. The catalog RPC uses it; the hosted chat
+   * path does not need it and only sends it when an operator opts in.
+   */
+  userJwt?: string;
+  /** UUID — one per opencode session is fine. */
+  sessionId: string;
+  /** Monotonic, milliseconds since epoch. */
+  requestId: bigint;
+  /** UUID — one per RPC call. */
+  triggerId: string;
+  /** Optional override for the version string. Cosmetic. */
+  windsurfVersion?: string;
+  /** Optional override for the host OS string. */
+  osName?: string;
+  /**
+   * Emit the exact field set the hosted chat RPC accepts.
+   *
+   * GetChatMessage validates this message far more strictly than
+   * GetCascadeModelConfigs does, which is why the catalog has always worked
+   * while chat did not. The shape is seven identity fields, the optional
+   * user_jwt, and the fingerprint — the telemetry fields this module otherwise
+   * sends (request_id, session_id, ls_timestamp, trigger_id, plan_name,
+   * ide_type) are not part of it.
+   */
+  cloudChatShape?: boolean;
+  /** Override for Metadata #31; a random fingerprint is generated when absent. */
+  deviceHex?: string;
+}
+
+function osString(): string {
+  switch (process.platform) {
+    case 'darwin': return 'darwin';
+    case 'linux': return 'linux';
+    case 'win32': return 'windows';
+    default: return String(process.platform);
+  }
+}
+
+export function buildMetadata(input: MetadataInput): Buffer {
+  const version = input.windsurfVersion ?? WINDSURF_VERSION_STRING;
+  const os = input.osName ?? osString();
+  if (input.cloudChatShape) {
+    const clientVersion = input.windsurfVersion ?? CLOUD_CHAT_CLIENT_VERSION;
+    return Buffer.concat([
+      encodeString(1, CLOUD_CHAT_CLIENT_NAME),
+      encodeString(2, clientVersion),
+      encodeString(3, input.apiKey),
+      encodeString(4, 'en'),
+      encodeString(5, input.osName ?? CLOUD_CHAT_OS),
+      encodeString(7, clientVersion),
+      encodeString(12, CLOUD_CHAT_CLIENT_NAME),
+      ...(input.userJwt ? [encodeString(21, input.userJwt)] : []),
+      encodeString(31, input.deviceHex ?? randomBytes(DEVICE_FINGERPRINT_BYTES).toString('hex')),
+    ]);
+  }
+  const parts: Buffer[] = [
+    encodeString(1, 'windsurf'),                     // ide_name
+    encodeString(2, version),                         // extension_version
+    encodeString(3, input.apiKey),                    // api_key
+    encodeString(4, 'en'),                            // locale
+    encodeString(5, os),                              // os
+    encodeString(7, version),                         // ide_version
+    encodeVarintField(9, input.requestId),            // request_id (uint64 monotonic)
+    encodeString(10, input.sessionId),                // session_id
+    encodeString(12, 'windsurf'),                     // extension_name
+    encodeMessage(16, encodeTimestampBody()),         // ls_timestamp (google.protobuf.Timestamp)
+    encodeString(25, input.triggerId),                // trigger_id
+    encodeString(26, 'Unset'),                        // plan_name
+    encodeString(28, 'windsurf'),                     // ide_type
+  ];
+  if (input.userJwt) parts.push(encodeString(21, input.userJwt));   // user_jwt
+  return Buffer.concat(parts);
+}
diff --git a/src/adapters/devin/cloud-direct/wire.ts b/src/adapters/devin/cloud-direct/wire.ts
new file mode 100644
index 0000000000..cc8b732eb1
--- /dev/null
+++ b/src/adapters/devin/cloud-direct/wire.ts
@@ -0,0 +1,206 @@
+/*
+ * Derived from rsvedant/opencode-windsurf-auth (src/cloud-direct/), MIT licensed,
+ * Copyright (c) 2026 Vedant. The full notice is in ./index.ts.
+ */
+/**
+ * Manual protobuf + Connect-RPC streaming envelope helpers.
+ *
+ * Connect-RPC streaming wire format (HTTPS POST body):
+ *   ┌─────────────┬────────────────┬──────────────┐
+ *   │ flags 1byte │ length 4B BE   │   payload    │
+ *   └─────────────┴────────────────┴──────────────┘
+ *   flags bit 0x01 = payload is gzip-compressed
+ *   flags bit 0x02 = end-of-stream (trailer frame — JSON {error} or empty {})
+ *
+ * All `Get*` methods on `exa.api_server_pb.ApiServerService` that the
+ * language_server calls upstream use this format, content-type
+ * `application/connect+proto`, with `Connect-Protocol-Version: 1`.
+ *
+ * Kept tiny and dependency-free — same philosophy as src/plugin/protobuf.ts.
+ */
+
+import * as zlib from 'zlib';
+
+// ----------------------------------------------------------------------------
+// Proto wire encode
+// ----------------------------------------------------------------------------
+
+export function encodeVarint(value: number | bigint): Buffer {
+  const v0 = BigInt(value);
+  // Reject negatives at the boundary. Proto3 spec encodes signed types as
+  // 10-byte sign-extended varints; we don't support that here and the
+  // current call sites never need it (tags, lengths, request ids — all
+  // strictly positive). The old loop body would have terminated with
+  // `Number(-1n)` = -1, producing a malformed single 0xFF byte that the
+  // server would misparse silently. Throw instead so future regressions
+  // surface immediately.
+  if (v0 < 0n) {
+    throw new RangeError(`encodeVarint: negative input not supported (got ${value})`);
+  }
+  const bytes: number[] = [];
+  let v = v0;
+  while (v > 127n) {
+    bytes.push(Number(v & 0x7fn) | 0x80);
+    v >>= 7n;
+  }
+  bytes.push(Number(v));
+  return Buffer.from(bytes);
+}
+
+export function encodeTag(fieldNum: number, wire: number): Buffer {
+  return encodeVarint((fieldNum << 3) | wire);
+}
+
+export function encodeString(fieldNum: number, s: string): Buffer {
+  const buf = Buffer.from(s, 'utf8');
+  return Buffer.concat([encodeTag(fieldNum, 2), encodeVarint(buf.length), buf]);
+}
+
+export function encodeMessage(fieldNum: number, body: Buffer): Buffer {
+  return Buffer.concat([encodeTag(fieldNum, 2), encodeVarint(body.length), body]);
+}
+
+export function encodeVarintField(fieldNum: number, v: number | bigint): Buffer {
+  return Buffer.concat([encodeTag(fieldNum, 0), encodeVarint(v)]);
+}
+
+export function encodeFixed64Field(fieldNum: number, v: number): Buffer {
+  const b = Buffer.alloc(8);
+  b.writeDoubleLE(v, 0);
+  return Buffer.concat([encodeTag(fieldNum, 1), b]);
+}
+
+export function encodeTimestampBody(): Buffer {
+  const now = Date.now();
+  const seconds = Math.floor(now / 1000);
+  const nanos = (now % 1000) * 1_000_000;
+  return Buffer.concat([
+    encodeVarintField(1, seconds),
+    nanos > 0 ? encodeVarintField(2, nanos) : Buffer.alloc(0),
+  ]);
+}
+
+// ----------------------------------------------------------------------------
+// Proto wire decode
+// ----------------------------------------------------------------------------
+
+export function decodeVarint(buf: Buffer, offset: number): [bigint, number] {
+  let res = 0n;
+  let shift = 0n;
+  let i = offset;
+  while (i < buf.length) {
+    const b = buf[i++];
+    res |= BigInt(b & 0x7f) << shift;
+    if (!(b & 0x80)) return [res, i];
+    shift += 7n;
+  }
+  throw new Error('truncated varint');
+}
+
+export interface ProtoField {
+  num: number;
+  wire: number;
+  /** varint → bigint, fixed → 8/4 byte Buffer, length-delim → payload Buffer. */
+  value: bigint | Buffer;
+}
+
+export function* iterFields(buf: Buffer): Generator<ProtoField> {
+  let i = 0;
+  while (i < buf.length) {
+    const [tagBig, ai] = decodeVarint(buf, i);
+    i = ai;
+    const tag = Number(tagBig);
+    const num = tag >> 3;
+    const wire = tag & 0x7;
+    if (wire === 0) {
+      const [v, bi] = decodeVarint(buf, i);
+      i = bi;
+      yield { num, wire, value: v };
+    } else if (wire === 1) {
+      // Bounds-check: a truncated frame mustn't yield a short fixed64 slice
+      // that downstream readers treat as a full 8-byte value. Stop iterating
+      // cleanly instead.
+      if (i + 8 > buf.length) return;
+      yield { num, wire, value: buf.slice(i, i + 8) };
+      i += 8;
+    } else if (wire === 2) {
+      const [n, ci] = decodeVarint(buf, i);
+      i = ci;
+      const len = Number(n);
+      // Bounds-check: when the declared length runs past the buffer, the
+      // frame is corrupt or truncated. Returning short-buffered slices to
+      // downstream parsers used to misparse silently (M12).
+      if (len < 0 || i + len > buf.length) return;
+      yield { num, wire, value: buf.slice(i, i + len) };
+      i += len;
+    } else if (wire === 5) {
+      if (i + 4 > buf.length) return;
+      yield { num, wire, value: buf.slice(i, i + 4) };
+      i += 4;
+    } else if (wire === 3 || wire === 4) {
+      // Wire types 3 (start group) and 4 (end group) are deprecated in
+      // proto3 but show up in some Codeium server-generated messages. They
+      // carry no length info; the safe behavior is to stop iterating
+      // gracefully rather than tear down the whole frame parse.
+      return;
+    } else {
+      // Unknown wire type — bail rather than misalign.
+      return;
+    }
+  }
+}
+
+// ----------------------------------------------------------------------------
+// Connect-streaming envelope
+// ----------------------------------------------------------------------------
+
+/**
+ * Wrap `body` (a serialized proto message) in a Connect-streaming envelope.
+ * If `compress` is true, gzip the payload and set the 0x01 flag.
+ */
+export function frameConnectStream(body: Buffer, compress = true): Buffer {
+  let payload = body;
+  let flags = 0;
+  if (compress) {
+    payload = zlib.gzipSync(body);
+    flags |= 0x01;
+  }
+  const header = Buffer.alloc(5);
+  header[0] = flags;
+  header.writeUInt32BE(payload.length, 1);
+  return Buffer.concat([header, payload]);
+}
+
+export interface ConnectFrame {
+  flags: number;
+  /** Decompressed payload (gzip handled here if flags & 0x01). */
+  payload: Buffer;
+  /** Frame is the trailer (end-of-stream). */
+  eos: boolean;
+}
+
+/**
+ * Parse all Connect-streaming frames out of a response body.
+ *
+ * Returns array of decoded frames. Each frame's payload is already gzip-decoded
+ * if the compression flag was set.
+ */
+export function parseConnectFrames(buf: Buffer): ConnectFrame[] {
+  const out: ConnectFrame[] = [];
+  let i = 0;
+  while (i + 5 <= buf.length) {
+    const flags = buf[i];
+    const len = buf.readUInt32BE(i + 1);
+    if (i + 5 + len > buf.length) break;
+    let payload = buf.slice(i + 5, i + 5 + len);
+    if (flags & 0x01) {
+      // Compressed frame. If gunzip fails the frame is genuinely corrupt
+      // — surfacing as a thrown error beats parsing raw gzip bytes as proto
+      // (which previously produced misleading "yielded bad wire type" downstream).
+      payload = zlib.gunzipSync(payload);
+    }
+    out.push({ flags, payload, eos: (flags & 0x02) !== 0 });
+    i += 5 + len;
+  }
+  return out;
+}
diff --git a/src/adapters/devin/live-models.ts b/src/adapters/devin/live-models.ts
new file mode 100644
index 0000000000..08160213dc
--- /dev/null
+++ b/src/adapters/devin/live-models.ts
@@ -0,0 +1,133 @@
+/**
+ * Live Devin / Cognition model discovery via GetCascadeModelConfigs.
+ *
+ * The live catalog is the source of truth for the model roster. The endpoint
+ * returns effort-suffixed variants (e.g. `gpt-5-6-sol-high`); we collapse those
+ * to base ids so the picker stays clean and the adapter appends the effort
+ * suffix at request time. `DEVIN_STATIC_MODELS` is only a degraded-mode
+ * fallback for when there is no API key or discovery fails.
+ */
+import { getCachedCatalog, type ModelCatalogEntry } from "./cloud-direct";
+
+const DEFAULT_HOST = "https://server.codeium.com";
+
+/**
+ * Degraded-mode fallback shown when there is no API key or live discovery
+ * fails. The live catalog overrides this whenever discovery succeeds.
+ */
+export const DEVIN_STATIC_MODELS = [
+  "swe-1-7",
+  "swe-1-7-lightning",
+  "gpt-5-6-sol",
+  "gpt-5-6-luna",
+  "gpt-5-6-terra",
+  "claude-opus-4-8",
+  "claude-fable-5-1",
+  "claude-sonnet-5",
+  "glm-5-2",
+  "kimi-k2-7",
+  "grok-4-5",
+] as const;
+
+/**
+ * Degraded-mode context windows, used only when live discovery cannot run.
+ *
+ * Every number here was read from a live `GetCascadeModelConfigs` response
+ * (`ClientModelConfig` field #18) rather than from documentation, because
+ * Cognition publishes none: the Devin CLI and Desktop model pages, the SWE-2
+ * and SWE-1.7 announcements, and the Windsurf model reference all state model
+ * names without a context window. The only published numbers are long-context
+ * pricing thresholds, which are a different quantity and were not used.
+ *
+ * The previous copy of this table was wrong for nine of its eleven rows — the
+ * three Claude models were listed at 200k against an actual 1M, `grok-4-5` at
+ * 256k against 500k, and the GPT rows at 1.05M against 1M — because it was
+ * assembled from each model's upstream vendor window instead of what Cognition
+ * actually serves. Measure the catalog when updating this; do not carry a
+ * number over from the model's original vendor.
+ */
+export const DEVIN_MODEL_CONTEXT_WINDOWS: Record<string, number> = {
+  "swe-2": 262_000,
+  "swe-1-7": 262_000,
+  "swe-1-7-lightning": 202_752,
+  "swe-1-6": 200_000,
+  "gpt-5-6-sol": 1_000_000,
+  "gpt-5-6-luna": 1_000_000,
+  "gpt-5-6-terra": 1_000_000,
+  "gpt-6-astra": 1_000_000,
+  "claude-opus-4-8": 1_000_000,
+  "claude-opus-5": 1_000_000,
+  "claude-fable-5-1": 1_000_000,
+  "claude-sonnet-5": 1_000_000,
+  "glm-5-2": 200_000,
+  "glm-5-3": 1_048_576,
+  "kimi-k2-7": 262_144,
+  "kimi-k3": 1_048_576,
+  "gemini-3-8-flash": 1_048_576,
+  "grok-4-5": 500_000,
+  "grok-4-6": 500_000,
+};
+
+/**
+ * Trailing tokens that the Cognition catalog appends as effort/variant
+ * suffixes. Stripped to collapse suffixed UIDs to their base id.
+ */
+const EFFORT_TOKENS = new Set([
+  "low", "medium", "high", "xhigh", "max", "none", "fast", "priority", "1m",
+]);
+
+/** Collapse an effort-suffixed UID to its base id (e.g. `gpt-5-6-sol-high` → `gpt-5-6-sol`). */
+export function collapseDevinModelUid(uid: string): string {
+  const parts = uid.split("-");
+  while (parts.length > 1 && EFFORT_TOKENS.has(parts[parts.length - 1]!)) {
+    parts.pop();
+  }
+  return parts.join("-");
+}
+
+export type DevinUsableModelsResult =
+  | { ok: true; models: string[]; contextWindows: Record<string, number> }
+  | { ok: false; error: "auth" | "http" | "empty" | "unknown"; detail?: string };
+
+/**
+ * Fetch the live model roster from Cognition's `GetCascadeModelConfigs` and
+ * collapse effort-suffixed variants to base ids. The returned list is the
+ * authoritative model roster for the signed-in account.
+ */
+export async function fetchDevinUsableModels(opts: {
+  apiKey: string;
+  baseUrl?: string;
+  signal?: AbortSignal;
+}): Promise<DevinUsableModelsResult> {
+  try {
+    const host = (opts.baseUrl || DEFAULT_HOST).replace(/\/$/, "");
+    const catalog = await getCachedCatalog(opts.apiKey, host, opts.signal);
+    if (!catalog) return { ok: false, error: "empty" };
+    const bases = new Set<string>();
+    const contextWindows: Record<string, number> = {};
+    for (const entry of catalog.byUid.values()) {
+      if (entry.disabled) continue;
+      // Skip internal enum constants (e.g. MODEL_GPT_5_2_LOW, MODEL_PRIVATE_*).
+      // Real chat model UIDs are lowercase dashed strings (swe-1-7, gpt-5-6-sol).
+      if (entry.modelUid.startsWith("MODEL_")) continue;
+      const base = collapseDevinModelUid(entry.modelUid);
+      bases.add(base);
+      if (entry.contextWindow && entry.contextWindow > 0) {
+        // Variants of one base can disagree: the opt-in `-1m` rows report a
+        // larger window than the plain row of the same base, and both collapse
+        // here because `1m` is an effort token. Keep the smallest, because the
+        // base id routes to the plain variant — advertising the long-context
+        // number would promise a window the request the picker actually sends
+        // cannot use.
+        const seen = contextWindows[base];
+        contextWindows[base] = seen === undefined ? entry.contextWindow : Math.min(seen, entry.contextWindow);
+      }
+    }
+    if (bases.size === 0) return { ok: false, error: "empty" };
+    return { ok: true, models: [...bases].sort(), contextWindows };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (/unauth|401|invalid token|login/i.test(message)) return { ok: false, error: "auth", detail: message };
+    return { ok: false, error: "unknown", detail: message };
+  }
+}
diff --git a/src/adapters/google.ts b/src/adapters/google.ts
index 9e1b46307e..7fcc88ba59 100644
--- a/src/adapters/google.ts
+++ b/src/adapters/google.ts
@@ -109,7 +109,7 @@ function stripAntigravityRejectedClaudeSdkParagraph(systemText: string): string
  * Unknown ids return `undefined` deliberately. An earlier revision returned a 16,384 floor for
  * anything unmatched, which silently truncated aliases, gateway ids, and any model added after
  * this table was written — the operator asked for N tokens and got 16,384 with no signal. A cap
- * we cannot justify is worse than no cap: `structure/02_config-and-codex-home.md` is explicit
+ * we cannot justify is worse than no cap: `structure/config.md` is explicit
  * that an explicit request value wins, so an unrecognized model passes through untouched and the
  * upstream remains the authority on its own limit.
  *
diff --git a/src/adapters/openai-chat.ts b/src/adapters/openai-chat.ts
index 4ba654487c..e338d845ad 100644
--- a/src/adapters/openai-chat.ts
+++ b/src/adapters/openai-chat.ts
@@ -96,7 +96,14 @@ function openAIChatTransport(provider: OcxProviderConfig): {
   };
   if (hasCredential) headers.Authorization = `Bearer ${provider.apiKey}`;
   if (provider.headers) Object.assign(headers, provider.headers);
-  return { url: openaiChatCompletionsUrl(provider.baseUrl), headers, hasCredential };
+  // A configured relative path wins, mirroring how the Responses adapter honours
+  // `responsesPath`. An upstream can serve both wires under different prefixes, and a
+  // per-model wire override only swaps the adapter, so without this the opted-in Chat
+  // request would be sent to the Responses base with `/chat/completions` appended.
+  const url = provider.chatCompletionsPath === undefined
+    ? openaiChatCompletionsUrl(provider.baseUrl)
+    : `${provider.baseUrl.replace(/\/$/, "")}${provider.chatCompletionsPath}`;
+  return { url, headers, hasCredential };
 }
 
 /**
@@ -140,6 +147,16 @@ export function buildOpenAIChatPassthroughRequest(
   // ingress enforces exactly that. A prefix match here would strip response_format from
   // `<listed>:<tag>` siblings the operator never opted out, silently returning prose.
   if (provider.noStructuredOutputModels?.includes(modelId)) delete body.response_format;
+  // Narrower neighbour: the model takes `json_object` but rejects `json_schema`. Downgrade
+  // rather than drop, so a caller that asked for JSON still gets JSON. The type check also
+  // makes the kill switch above win without an else — after its `delete` there is no type
+  // left to match.
+  const passthroughFormat = body.response_format;
+  if (provider.noJsonSchemaModels?.includes(modelId)
+      && typeof passthroughFormat === "object" && passthroughFormat !== null
+      && (passthroughFormat as { type?: unknown }).type === "json_schema") {
+    body.response_format = { type: "json_object" };
+  }
 
   // Run the same complete Fast policy as the translated Chat path, including explicit
   // fastMode and foreign-tier handling. On inherited canonical Fast, the passthrough still
@@ -1582,15 +1599,19 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
         if (textFormat?.type === "json_object") {
           body.response_format = { type: "json_object" };
         } else if (textFormat?.type === "json_schema") {
-          body.response_format = {
-            type: "json_schema",
-            json_schema: {
-              name: textFormat.name ?? "response",
-              ...(textFormat.description !== undefined ? { description: textFormat.description } : {}),
-              ...(textFormat.schema !== undefined ? { schema: textFormat.schema } : {}),
-              ...(textFormat.strict !== undefined ? { strict: textFormat.strict } : {}),
-            },
-          };
+          // Same downgrade as the passthrough path: the schema is dropped because the
+          // upstream rejects it, but the JSON-mode request itself survives.
+          body.response_format = provider.noJsonSchemaModels?.includes(parsed.modelId)
+            ? { type: "json_object" }
+            : {
+              type: "json_schema",
+              json_schema: {
+                name: textFormat.name ?? "response",
+                ...(textFormat.description !== undefined ? { description: textFormat.description } : {}),
+                ...(textFormat.schema !== undefined ? { schema: textFormat.schema } : {}),
+                ...(textFormat.strict !== undefined ? { strict: textFormat.strict } : {}),
+              },
+            };
         }
       }
 
diff --git a/src/adapters/openai-responses.ts b/src/adapters/openai-responses.ts
index c4aa523ee6..30e1c14c85 100644
--- a/src/adapters/openai-responses.ts
+++ b/src/adapters/openai-responses.ts
@@ -1,4 +1,5 @@
 import { normalizeRoutedAgentMessages } from "./routed-agent-messages";
+import { stripBracketedModelSuffix } from "./openai-chat";
 import { normalizeOpenCodeGoAdditionalTools } from "./opencode-go-additional-tools";
 import { isXaiResponsesDestination } from "../providers/xai-transport";
 import { createHash } from "node:crypto";
@@ -2541,7 +2542,21 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
         actualServiceTier === null ? null : "service-tier",
         actualServiceTier,
       );
-      const body = JSON.stringify(finalBody);
+      // The Responses adapter is passthrough: it forwards `parsed._rawBody` rather than
+      // rebuilding the body from `parsed.modelId`, and the router writes the routed id into
+      // that raw body. So a provider whose upstream rejects bracketed ids has to be honoured
+      // here, on the serialized body, not on the parsed selector. One place covers both the
+      // HTTP and the WebSocket outbound, because the WS path transports this same request
+      // instead of rebuilding it.
+      const body = JSON.stringify(
+        provider.modelSuffixBracketStrip
+          && finalBody !== null
+          && typeof finalBody === "object"
+          && !Array.isArray(finalBody)
+          && typeof (finalBody as { model?: unknown }).model === "string"
+          ? { ...(finalBody as Record<string, unknown>), model: stripBracketedModelSuffix((finalBody as { model: string }).model) }
+          : finalBody,
+      );
       const releaseBodyObservation = translatorBudget.observeExternallyCapped(
         "passthrough_serialization",
         new TextEncoder().encode(body).byteLength,
diff --git a/src/adapters/registry.ts b/src/adapters/registry.ts
index d8edbead92..69cb11ad13 100644
--- a/src/adapters/registry.ts
+++ b/src/adapters/registry.ts
@@ -6,6 +6,8 @@ import { createCodeBuddyAdapter } from "./codebuddy/adapter";
 import { createQoderAdapter } from "./qoder/adapter";
 import { createCommandCodeAdapter } from "./command-code";
 import { createCursorAdapter } from "./cursor";
+import { createDevinCliAdapter } from "./devin-cli/adapter";
+import { createDevinAdapter } from "./devin";
 import { createGoogleAdapter } from "./google";
 import { createKiroAdapter } from "./kiro";
 import { createMimoFreeAdapter } from "./mimo-free";
@@ -19,6 +21,16 @@ export type AdapterCacheRetention = "none" | "short" | "long";
 
 export interface AdapterFactoryContext {
   cacheRetention?: AdapterCacheRetention;
+  /**
+   * The configured provider row this adapter serves.
+   *
+   * Needed when one adapter backs two provider ids whose credentials differ:
+   * `devin` and `devin-cli` share a transport and a token format but sign in to
+   * different accounts and can sit on different Cognition tenants, and the tenant
+   * is recorded on the credential rather than in the registry. Optional, and
+   * every other adapter ignores it.
+   */
+  providerId?: string;
 }
 
 export type AdapterWire =
@@ -30,7 +42,9 @@ export type AdapterWire =
   | "openai-responses"
   | "google"
   | "kiro"
-  | "cursor";
+  | "cursor"
+  | "devin-cli"
+  | "devin";
 
 export type AdapterMutationContract =
   | "codex-owned"
@@ -112,6 +126,16 @@ export const ADAPTER_REGISTRY = {
     mutation: "codex-owned-with-gated-native-fallback",
     create: (provider: OcxProviderConfig, _context: AdapterFactoryContext) => createCursorAdapter(provider),
   },
+  "devin-cli": {
+    wire: "devin-cli",
+    mutation: "codex-owned",
+    create: (provider: OcxProviderConfig, _context: AdapterFactoryContext) => createDevinCliAdapter(provider),
+  },
+  devin: {
+    wire: "devin",
+    mutation: "codex-owned",
+    create: (provider: OcxProviderConfig, context: AdapterFactoryContext) => createDevinAdapter(provider, context),
+  },
   "mimo-free": {
     contractParent: "openai-chat",
     create: (provider: OcxProviderConfig, _context: AdapterFactoryContext) => createMimoFreeAdapter(provider),
diff --git a/src/bridge.ts b/src/bridge.ts
index 20e7c3fe09..3f5f529d3f 100644
--- a/src/bridge.ts
+++ b/src/bridge.ts
@@ -1293,7 +1293,10 @@ export function bridgeToResponsesSSE(
               if (currentReasoning) closeCurrentReasoning();
               if (currentRawReasoning) closeCurrentRawReasoning();
               flushHiddenRawReasoning();
-              if (currentToolCall) closeCurrentToolCall();
+              if (currentToolCall) {
+                if (isTruncatedStopReason(event.stopReason)) failCurrentToolCall();
+                else closeCurrentToolCall();
+              }
               if (currentWebSearch) closeCurrentWebSearch("completed", []);
               releasePendingWebSources();
               // Redacted-only turns (or hidden thinking without a trailing signature event) still
@@ -2055,7 +2058,10 @@ function buildResponseJSONWithBudget(
   // must one left open by a stream that stopped without any terminal at all. That case previously
   // fell through to "completed", handing back a function_call whose arguments were half-written
   // JSON, inside a turn also marked completed.
-  if (currentToolCallId) flushToolCall(errorEvent || incompleteEvent || !sawTerminal ? "incomplete" : "completed");
+  if (currentToolCallId) {
+    flushToolCall(errorEvent || incompleteEvent || !sawTerminal || isTruncatedStopReason(rawStopReason)
+      ? "incomplete" : "completed");
+  }
   if (batchKiroRedacted) {
     // pushOutput reserves the item itself and releases the retained raw blob it replaces.
     pushOutput({
diff --git a/src/claude/inbound-cache-stabilize.ts b/src/claude/inbound-cache-stabilize.ts
new file mode 100644
index 0000000000..e085dd7c4c
--- /dev/null
+++ b/src/claude/inbound-cache-stabilize.ts
@@ -0,0 +1,130 @@
+/**
+ * Claude Code appends growing `<total_tokens>…</total_tokens>` footers (and
+ * occasional TaskCreate nudges) into system text that becomes Responses
+ * `instructions`. That churn breaks Muse/Go prefix cache on the instructions
+ * prefix even when tools stay stable. Strip dynamics from instructions;
+ * surface the latest notice on `input` instead.
+ *
+ * Relocation is identified by harness shape: only a trailing, unfenced,
+ * canonical notice at the end of instructions is moved. An unmatched fence
+ * opener covers through EOF. No match → the original string is returned
+ * byte-for-byte. The matcher is content identity only; `translateAnthropicRequest`
+ * requires `claudeCode.stabilizePromptCache: true` before this helper runs. Claude Code
+ * writes `<total_tokens>N tokens left</total_tokens>`.
+ *
+ * TaskCreate nudge text has drifted across Claude Code builds; match the
+ * known exact paragraphs (legacy + 2.1.263 "tracking progress" form) as
+ * trailing alternatives so a mid-session nudge cannot pin older footers
+ * above it and flip `instructions` after a previously stable peel.
+ */
+
+const TOTAL_NOTICE_RE = /^<total_tokens>[0-9]+ tokens left<\/total_tokens>$/;
+
+/** Legacy Claude Code TaskCreate reminder (pre-"tracking progress"). */
+const TASKCREATE_NUDGE_LEGACY =
+  "The task tools haven't been used recently. If you're working on tasks that would benefit from tracking, consider using TaskCreate to add them. Only use these if relevant to the current work. This is just a gentle reminder - ignore if not applicable.";
+
+/**
+ * Claude Code 2.1.263+ TaskCreate reminder observed on hitrate S/T4
+ * (FREEZE-DIFF + tip0847 pilots). Mentions TaskUpdate and stale-list cleanup.
+ */
+const TASKCREATE_NUDGE_CC_2_1_263 =
+  "The task tools haven't been used recently. If you're working on tasks that would benefit from tracking progress, consider using TaskCreate to add new tasks and TaskUpdate to update task status (set to in_progress when starting, completed when done). Also consider cleaning up the task list if it has become stale. Only use these if relevant to the current work. This is just a gentle reminder - ignore if not applicable.";
+
+interface FenceRange {
+  start: number;
+  end: number;
+}
+
+const FENCE_OPEN_RE = /^( {0,3})(`{3,}|~{3,})/;
+const FENCE_CLOSE_RE = /^( {0,3})(`{3,}|~{3,})[ \t]*$/;
+
+/**
+ * Markdown fence ranges. An unmatched opener covers through EOF: unfinished
+ * fenced examples are code content, not a harness suffix. A closer must be a
+ * standalone fence line (no info string) of the same character and at least
+ * the opener's length.
+ */
+function fencedRanges(source: string): FenceRange[] {
+  const ranges: FenceRange[] = [];
+  let offset = 0;
+  let openAt: number | null = null;
+  let openFence = "";
+  while (offset <= source.length) {
+    const nl = source.indexOf("\n", offset);
+    const lineEnd = nl === -1 ? source.length : nl;
+    const line = source.slice(offset, lineEnd).replace(/\r$/, "");
+    if (openAt === null) {
+      const open = FENCE_OPEN_RE.exec(line);
+      if (open) {
+        openAt = offset;
+        openFence = open[2]!;
+      }
+    } else {
+      const close = FENCE_CLOSE_RE.exec(line);
+      if (
+        close
+        && close[2]![0] === openFence[0]
+        && close[2]!.length >= openFence.length
+      ) {
+        ranges.push({ start: openAt, end: lineEnd });
+        openAt = null;
+        openFence = "";
+      }
+    }
+    if (nl === -1) break;
+    offset = nl + 1;
+  }
+  if (openAt !== null) ranges.push({ start: openAt, end: source.length });
+  return ranges;
+}
+
+/** A backwards cursor consumes each line and fence range at most once. */
+export function stabilizeClaudeInstructionsForPromptCache(
+  instructions: string,
+): { instructions: string; dynamicNotice: string | null } {
+  const ranges = fencedRanges(instructions);
+  let fenceIndex = ranges.length - 1;
+  let end = instructions.length;
+  let latestTotal: string | null = null;
+  let latestNudge: string | null = null;
+  let peeled = false;
+
+  for (;;) {
+    // This is speculative: a failed candidate must not trim the retained prefix.
+    let lineEnd = end;
+    while (lineEnd > 0 && instructions[lineEnd - 1] === "\n") {
+      lineEnd--;
+      if (lineEnd > 0 && instructions[lineEnd - 1] === "\r") lineEnd--;
+    }
+    if (lineEnd === 0) break;
+    const lineStart = instructions.lastIndexOf("\n", lineEnd - 1) + 1;
+    let contentStart = lineStart;
+    let contentEnd = lineEnd;
+    while (contentStart < contentEnd && (instructions[contentStart] === " " || instructions[contentStart] === "\t")) contentStart++;
+    while (contentEnd > contentStart && (instructions[contentEnd - 1] === " " || instructions[contentEnd - 1] === "\t")) contentEnd--;
+    const notice = instructions.slice(contentStart, contentEnd);
+    const total = TOTAL_NOTICE_RE.test(notice);
+    const nudge = notice === TASKCREATE_NUDGE_LEGACY || notice === TASKCREATE_NUDGE_CC_2_1_263;
+    if (!total && !nudge) break;
+
+    while (fenceIndex >= 0 && ranges[fenceIndex]!.start > contentStart) fenceIndex--;
+    if (fenceIndex >= 0 && contentStart < ranges[fenceIndex]!.end) break;
+    if (total && latestTotal === null) latestTotal = notice;
+    if (nudge && latestNudge === null) latestNudge = notice;
+    peeled = true;
+
+    // Commit only the recognized notice and its immediately preceding LF/CRLF separators.
+    end = lineStart;
+    while (end > 0 && instructions[end - 1] === "\n") {
+      end--;
+      if (end > 0 && instructions[end - 1] === "\r") end--;
+    }
+  }
+
+  if (!peeled) return { instructions, dynamicNotice: null };
+  const noticeParts: string[] = [];
+  if (latestTotal) noticeParts.push(latestTotal);
+  if (latestNudge) noticeParts.push(latestNudge);
+  return { instructions: instructions.slice(0, end), dynamicNotice: noticeParts.join("\n\n") };
+}
diff --git a/src/claude/inbound.ts b/src/claude/inbound.ts
index 35f4865b94..e3664bf01c 100644
--- a/src/claude/inbound.ts
+++ b/src/claude/inbound.ts
@@ -17,6 +17,7 @@ export { resolveInboundModel, effortForThinkingBudget, effortFromOutputConfig, e
 import { AnthropicRequestError, isRec, type Rec } from "./inbound-records";
 import { resolveInboundModel, effortForThinkingBudget, effortFromOutputConfig, formatFromOutputConfig } from "./inbound-model-options";
 import { systemToInstructions, toolsToResponses, toolChoiceToResponses } from "./inbound-content-options";
+import { stabilizeClaudeInstructionsForPromptCache } from "./inbound-cache-stabilize";
 import { decodeReasoningEnvelope, encodeReasoningEnvelope, OCX_REASONING_PREFIX } from "../responses/reasoning-envelope";
 import { createTranslatorBudget, type TranslatorBudget } from "../lib/translator-budget";
 
@@ -298,7 +299,10 @@ export interface ClaudeInboundTranslation {
  * Translate an Anthropic Messages request body into a /v1/responses request body.
  * Throws AnthropicRequestError (-> 400 invalid_request_error) on malformed input.
  */
-export function anthropicToResponsesBody(raw: unknown, cc?: OcxClaudeCodeConfig): Rec {
+export function anthropicToResponsesBody(
+  raw: unknown,
+  cc?: OcxClaudeCodeConfig,
+): Rec {
   return anthropicToResponsesTranslation(raw, cc).body;
 }
 
@@ -307,7 +311,11 @@ export function anthropicToResponsesBody(raw: unknown, cc?: OcxClaudeCodeConfig)
  * OUT-OF-BODY tuple (audit 133 R3#1 — an in-body marker would leak upstream through
  * the native Responses forward and 400).
  */
-export function anthropicToResponsesTranslation(raw: unknown, cc?: OcxClaudeCodeConfig, budget?: TranslatorBudget): ClaudeInboundTranslation {
+export function anthropicToResponsesTranslation(
+  raw: unknown,
+  cc?: OcxClaudeCodeConfig,
+  budget?: TranslatorBudget,
+): ClaudeInboundTranslation {
   const activeBudget = budget ?? createTranslatorBudget();
   try {
     return translateAnthropicRequest(raw, cc, activeBudget);
@@ -316,7 +324,11 @@ export function anthropicToResponsesTranslation(raw: unknown, cc?: OcxClaudeCode
   }
 }
 
-function translateAnthropicRequest(raw: unknown, cc: OcxClaudeCodeConfig | undefined, budget: TranslatorBudget): ClaudeInboundTranslation {
+function translateAnthropicRequest(
+  raw: unknown,
+  cc: OcxClaudeCodeConfig | undefined,
+  budget: TranslatorBudget,
+): ClaudeInboundTranslation {
   if (!isRec(raw)) throw new AnthropicRequestError("request body must be a JSON object");
   if (typeof raw.model !== "string" || raw.model.length === 0) {
     throw new AnthropicRequestError("model is required");
@@ -357,7 +369,32 @@ function translateAnthropicRequest(raw: unknown, cc: OcxClaudeCodeConfig | undef
     stream: raw.stream === true,
   };
 
-  if (systemParts.length > 0) body.instructions = systemParts.join("\n\n");
+  const joinedSystem = systemParts.length > 0 ? systemParts.join("\n\n") : "";
+  const stabilizePromptCache = cc?.stabilizePromptCache === true;
+  // Desktop fallback hashes raw systemParts unless the caller opted into
+  // harness cleanup. Opt-in then hashes the same string as body.instructions.
+  let cacheSystem: string | string[] = systemParts;
+  if (joinedSystem) {
+    if (stabilizePromptCache) {
+      // Claude Code appends growing <total_tokens>N tokens left</total_tokens>
+      // footers (and occasional TaskCreate nudges) into system text. That churn
+      // breaks Muse/Go prefix cache on the Responses instructions prefix even
+      // when tools stay stable. Relocation is caller-opted, not inferred from
+      // a matching suffix or metadata.user_id.
+      const stabilized = stabilizeClaudeInstructionsForPromptCache(joinedSystem);
+      if (stabilized.instructions) body.instructions = stabilized.instructions;
+      if (stabilized.dynamicNotice) {
+        input.push({
+          type: "message",
+          role: "user",
+          content: [{ type: "input_text", text: stabilized.dynamicNotice }],
+        });
+      }
+      cacheSystem = stabilized.instructions;
+    } else {
+      body.instructions = joinedSystem;
+    }
+  }
 
   const tools = toolsToResponses(raw.tools);
   if (tools) body.tools = tools;
@@ -395,11 +432,14 @@ function translateAnthropicRequest(raw: unknown, cc: OcxClaudeCodeConfig | undef
     // Exact-prefix matching still isolates content; the key only steers routing
     // affinity. Callers must NOT synthesize a session_id header from this fallback
     // (audit 133 R2#3).
+    // Outside opt-in, hash the raw systemParts array (pre-stabilize Desktop
+    // key). Opt-in hashes the same string used for body.instructions so the
+    // key tracks the cacheable prefix after peel.
     body.prompt_cache_key = createHash("sha256")
       .update(canonicalJson({
         version: 2,
         model: body.model,
-        system: systemParts,
+        system: cacheSystem,
         tools: Array.isArray(body.tools) ? body.tools : [],
       }))
       .digest("hex").slice(0, 32);
diff --git a/src/cli/account-auth.ts b/src/cli/account-auth.ts
index 9ecc637a7a..73838f9da8 100644
--- a/src/cli/account-auth.ts
+++ b/src/cli/account-auth.ts
@@ -37,6 +37,7 @@ const USAGE = `Usage:
   ocx account code <provider> [--flow <flow-id>] [--json]   (reads the code from stdin)
   ocx account cancel <provider> [--flow <flow-id>] [--json]
   ocx account reset-credits <account-id|main> [--consume --yes [--operation-id <uuid>]] [--json]
+  ocx account grok-reset-coupons [<account-id>] [--consume --yes [--token-id <token-id>] [--operation-id <uuid>]] [--json]
 
 --device runs the OpenAI device-code login instead of the browser callback: use
 it when the proxy has no browser or nothing can reach localhost:1455, such as a
@@ -49,8 +50,20 @@ visible to anyone who can run ps:
   pbpaste | ocx account code <provider> --flow <flow-id>
   ocx account login <provider> --code -   (same, for the login flow)`;
 
+/**
+ * The Codex account pool answers to three spellings, and a user reaches for whichever
+ * one they already have a word for. `ocx login codex` routes here as well (dispatch.ts):
+ * the pool is deliberately not an `ocx login` provider -- it keeps its own account
+ * ledger and runs its browser flow inside the proxy -- but that is an implementation
+ * boundary, not something a user should have to know before they can log in.
+ */
 const CODEX_NAMES = new Set(["openai", "codex", "chatgpt"]);
 
+/** True for every spelling that means "the Codex account pool" rather than an OAuth provider. */
+export function isCodexAccountLoginName(name: string): boolean {
+  return CODEX_NAMES.has(name.trim().toLowerCase());
+}
+
 interface LoginStart {
   url?: string;
   flowId?: string;
@@ -100,7 +113,12 @@ async function login(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const id = takeOption(args, "--id");
   const suppliedCode = takeOptionWithSyntax(args, "--code");
   if (!provider) throw new CliUsageError("provider is required", USAGE);
-  rejectArgs(args, USAGE);
+  // A bare leftover here is plausibly the authorization code itself: this flow takes one
+  // through --code, and a user who pastes it as a positional would otherwise see it echoed
+  // back in the usage error. `ocx login codex` reaches this parser too, so the paste lands
+  // one word away from a command people run constantly. Flag-shaped leftovers stay visible,
+  // because a mistyped flag is exactly what the message has to name.
+  rejectArgs(args, USAGE, { redactValues: true });
   // kimi, nous, and github-copilot are already device flows, so --device is a
   // true statement about them and is accepted as a no-op rather than an error.
   // Anything else has no device grant at all and must fail loudly.
@@ -284,12 +302,53 @@ async function resetCredits(argv: string[], deps: RuntimeApiDeps): Promise<void>
   printData(result, wantsJson);
 }
 
+async function grokResetCoupons(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  // The account id is optional here (the server falls back to the selected xAI
+  // account), so a flag-shaped first token must not be swallowed as the id:
+  // `grok-reset-coupons --consume` has to reach the --yes gate, not become a
+  // read of account "--consume".
+  const rawId = args[0]?.startsWith("--") ? undefined : args.shift()?.trim();
+  const wantsJson = takeFlag(args, "--json");
+  const consume = takeFlag(args, "--consume");
+  const yes = takeFlag(args, "--yes");
+  // Before rejectArgs: takeOption splices its two tokens out of `args`.
+  const tokenId = takeOption(args, "--token-id");
+  const operationId = takeOption(args, "--operation-id");
+  if (consume && !yes) throw new CliUsageError("consuming a Grok reset coupon requires --yes", USAGE);
+  if (operationId !== undefined && !consume) {
+    throw new CliUsageError("--operation-id requires --consume", USAGE);
+  }
+  if (tokenId !== undefined && !consume) {
+    throw new CliUsageError("--token-id requires --consume", USAGE);
+  }
+  if (operationId !== undefined && !isCodexResetCreditOperationId(operationId)) {
+    throw new CliUsageError("--operation-id must be a UUIDv4", USAGE);
+  }
+  rejectArgs(args, USAGE);
+  const accountId = rawId ? (rawId === "main" ? "__main__" : rawId) : undefined;
+  const result = consume
+    ? await runtimeRequest("/api/grok/reset-coupons/consume", {
+      method: "POST",
+      // Spread, not `operationId: undefined`: the server distinguishes an absent
+      // key from a caller who asked for a stable idempotency identity.
+      body: JSON.stringify({ accountId, tokenId, ...(operationId === undefined ? {} : { operationId }) }),
+    }, deps)
+    : await runtimeRequest(
+      `/api/grok/reset-coupons${accountId ? `?accountId=${encodeURIComponent(accountId)}` : ""}`,
+      {},
+      deps,
+    );
+  printData(result, wantsJson);
+}
+
 export async function handleAccountAuthCommand(sub: string, argv: string[], deps: RuntimeApiDeps = {}): Promise<number | null> {
   let action: (() => Promise<void>) | undefined;
   if (sub === "login" || sub === "reauth") action = () => login(sub === "reauth" ? [...argv, "--reauth"] : argv, deps);
   else if (sub === "code") action = () => code(argv, deps);
   else if (sub === "cancel") action = () => cancel(argv, deps);
   else if (sub === "reset-credits") action = () => resetCredits(argv, deps);
+  else if (sub === "grok-reset-coupons") action = () => grokResetCoupons(argv, deps);
   if (!action) return null;
   return runCliAction(action);
 }
diff --git a/src/cli/account-extended.ts b/src/cli/account-extended.ts
index a6fa3b707c..18fca00fb7 100644
--- a/src/cli/account-extended.ts
+++ b/src/cli/account-extended.ts
@@ -399,14 +399,22 @@ export async function cmdAutoSwitch(args: string[], deps: AccountDeps): Promise<
     const storedThreshold = typeof stored === "number" && Number.isInteger(stored) && stored >= 0 && stored <= 100
       ? stored : null;
     const poolEnabled = typeof settings.enabled === "boolean" ? settings.enabled : null;
-    const inert = settings.inert === true ? true : null;
-    // This CLI understands only the current inert generic threshold contract.
-    const enabled = false;
+    // Three states, not two. `true` is stored-but-not-applied, `false` is applied by the
+    // shared kernel, and absent is a server that does not speak this field at all. Collapsing
+    // false into absent would render the live feature as an unknown capability.
+    const inert = typeof settings.inert === "boolean" ? settings.inert : null;
+    // A stored threshold only steers selection once the pool consumes it, which is exactly
+    // what `inert: false` reports.
+    const enabled = inert === false && storedThreshold !== null;
     if (wantsJson) {
       console.log(JSON.stringify({ provider: name, autoSwitchThreshold: storedThreshold, enabled, poolEnabled, inert }, null, 2));
     } else {
       const value = storedThreshold === null ? "unset" : `${storedThreshold}%`;
-      console.log(`auto-switch: ${inert === true ? "inactive" : "unavailable"} (stored threshold ${value}; ${inert === true ? "not applied by this pool" : "threshold support is unknown"})`);
+      const state = inert === false ? (enabled ? "on" : "off") : inert === true ? "inactive" : "unavailable";
+      const why = inert === false
+        ? (enabled ? "applied by this pool" : "no threshold stored")
+        : inert === true ? "not applied by this pool" : "threshold support is unknown";
+      console.log(`auto-switch: ${state} (stored threshold ${value}; ${why})`);
     }
     return 0;
   }
@@ -839,21 +847,15 @@ export async function cmdPauseExhausted(args: string[], deps: AccountDeps): Prom
 }
 
 /**
- * Two pools expose strategy and sticky, and they are NOT reached the same way:
+ * One transport, because there is now one contract.
  *
- * |  | Codex pool | Anthropic pool |
- * |---|---|---|
- * | read | `GET /api/codex-auth/active` | `GET /api/oauth/accounts/pool?provider=` |
- * | write | `PUT /api/codex-auth/pool-strategy` | `PUT /api/oauth/accounts/pool` |
- * | keys | `accountPoolStrategy`/`accountPoolStickyLimit` | `strategy`/`stickyLimit` |
- * | body | bare field | field **plus** a mandatory `provider` |
+ * This used to be a table of the differences between the Codex and Anthropic pools -- different
+ * read path, different write path, different response keys, and a `provider` field mandatory on
+ * one body and forbidden on the other. That table existed only because the two contracts
+ * disagreed; `/api/pool/settings` answers with the same keys for every kind, so the table
+ * collapses to a single shape and the asymmetry it encoded is gone rather than relocated.
  *
- * Omitting `provider` from the Anthropic write body earns a 400
- * (`oauth-account-routes.ts:344`), so the asymmetry has to be encoded somewhere. Encoding it
- * here keeps ONE verb pair working on both pools. The alternative the plan left open -- a second
- * `provider-strategy`/`provider-sticky` pair -- would double the surface an operator must learn
- * to express one idea, and a CLI that can steer one pool and not the other is exactly the trap
- * this unit exists to remove.
+ * The legacy paths still work and still have their own goldens. Nothing here reads them.
  */
 interface PoolTransport {
   readPath: string;
@@ -865,18 +867,10 @@ interface PoolTransport {
   writeBody: (field: "strategy" | "stickyLimit", value: unknown) => Record<string, unknown>;
 }
 
-const CODEX_POOL_TRANSPORT: PoolTransport = {
-  readPath: "/api/codex-auth/active",
-  writePath: "/api/codex-auth/pool-strategy",
-  strategyKey: "accountPoolStrategy",
-  stickyKey: "accountPoolStickyLimit",
-  writeBody: (field, value) => ({ [field]: value }),
-};
-
-function anthropicPoolTransport(provider: string): PoolTransport {
+function unifiedPoolTransport(provider: string): PoolTransport {
   return {
-    readPath: `/api/oauth/accounts/pool?provider=${encodeURIComponent(provider)}`,
-    writePath: "/api/oauth/accounts/pool",
+    readPath: `/api/pool/settings?provider=${encodeURIComponent(provider)}`,
+    writePath: "/api/pool/settings",
     strategyKey: "strategy",
     stickyKey: "stickyLimit",
     writeBody: (field, value) => ({ provider, [field]: value }),
@@ -892,8 +886,7 @@ function poolTransportFor(
   classified: { type: "codex" | "oauth" | "api-key" },
   name: string,
 ): PoolTransport | string {
-  if (classified.type === "codex") return CODEX_POOL_TRANSPORT;
-  if (classified.type === "oauth") return anthropicPoolTransport(name);
+  if (classified.type === "codex" || classified.type === "oauth") return unifiedPoolTransport(name);
   return `pool settings apply to OAuth account pools, not the API-key provider "${name}"`;
 }
 
diff --git a/src/cli/account.ts b/src/cli/account.ts
index 041e99830b..4a8c6a0427 100644
--- a/src/cli/account.ts
+++ b/src/cli/account.ts
@@ -60,6 +60,7 @@ const ACCOUNT_USAGE = `Usage:
   ocx account code <provider> [--flow <flow-id>] [--json]   (reads the code from stdin)
   ocx account cancel <provider> [--flow <flow-id>] [--json]
   ocx account reset-credits <account-id|main> [--consume --yes] [--json]
+  ocx account grok-reset-coupons [<account-id>] [--consume --yes] [--token-id <token-id>] [--json]
   ocx account main <doctor|list|register|add|switch|recover> ...
 
 List and switch provider accounts and API-key pools (masked output only).
@@ -355,7 +356,7 @@ export async function cmdAccount(args: string[], deps: AccountDeps = {}): Promis
       const { cmdNativeMainAccount } = await import("./account-main");
       return await cmdNativeMainAccount(rest, deps);
     }
-    if (["login", "reauth", "code", "cancel", "reset-credits"].includes(sub ?? "")) {
+    if (["login", "reauth", "code", "cancel", "reset-credits", "grok-reset-coupons"].includes(sub ?? "")) {
       const { handleAccountAuthCommand } = await import("./account-auth");
       return await handleAccountAuthCommand(sub!, rest, deps) ?? 1;
     }
diff --git a/src/cli/capabilities.ts b/src/cli/capabilities.ts
index d9aa8d0402..63cf313676 100644
--- a/src/cli/capabilities.ts
+++ b/src/cli/capabilities.ts
@@ -259,6 +259,27 @@ export const CAPABILITIES: readonly Capability[] = [
     json: "payload",
     details: ["CLI/admin-token refreshes only observe usage. After quota recovery, a human must click Refresh quotas in the dashboard to authorize model validation. Do not mint a GUI session to work around this consent boundary."],
   },
+  {
+    command: ["account", "grok-reset-coupons"],
+    summary: "Inspect or redeem Grok billing reset coupons; redemption is journaled and idempotent.",
+    routes: [
+      { method: "GET", path: "/api/grok/reset-coupons" },
+      { method: "POST", path: "/api/grok/reset-coupons/consume" },
+    ],
+    flags: [
+      { name: "--consume", value: "boolean", summary: "Redeem one reset coupon; requires --yes." },
+      { name: "--yes", value: "boolean", summary: "Explicit confirmation required by --consume." },
+      { name: "--token-id", value: "string", summary: "Redeem a specific reset token instead of the default selection." },
+      { name: "--operation-id", value: "string", summary: "UUIDv4 making a redemption idempotent: retries replay the journaled outcome." },
+      { name: "--json", value: "boolean", summary: "Emit the coupon list or redemption result as JSON." },
+    ],
+    mutates: true,
+    json: "payload",
+    details: [
+      "Without --consume this is a read: remaining coupons and their validity windows.",
+      "The operation is journaled before the upstream call, so retrying the same --operation-id replays the recorded outcome instead of spending a second coupon.",
+    ],
+  },
   {
     command: ["usage"],
     summary: "Token and estimated-cost report over a time range.",
@@ -316,10 +337,9 @@ export const CAPABILITIES: readonly Capability[] = [
     // Both pools, because both have the setting. The Codex pool reads its applied values
     // from the active payload; the Anthropic pool has its own GET.
     routes: [
-      { method: "GET", path: "/api/codex-auth/active" },
-      { method: "PUT", path: "/api/codex-auth/pool-strategy" },
-      { method: "GET", path: "/api/oauth/accounts/pool" },
-      { method: "PUT", path: "/api/oauth/accounts/pool" },
+      { method: "GET", path: "/api/pool/settings" },
+      { method: "PUT", path: "/api/pool/settings" },
+      { method: "PATCH", path: "/api/pool/settings" },
     ],
     flags: [{ name: "--json", value: "boolean", summary: "Emit the applied strategy and sticky limit as JSON." }],
     mutates: true,
@@ -328,23 +348,45 @@ export const CAPABILITIES: readonly Capability[] = [
       "A bare invocation reads and never writes.",
       "The APPLIED value is echoed, not the requested one, so a server-side normalization stays visible.",
       "Values are not re-validated in the CLI: the server owns the strategy names and the 1-100 sticky bound.",
-      "`anthropic` owns the full pool contract. Other OAuth providers reach the same endpoint with a generic subset (enabled/strategy/autoSwitchThreshold) whose settings persist but do not yet steer selection; `sticky` and `quotaWindow` are refused for them.",
+      "One route answers for every pool kind and declares which fields that kind honours in `supported`, so an unsupported field is a stated null rather than an absence. `anthropic` alone carries `quotaWindow`. Generic-provider settings steer selection only while `pool.kernel` is on. The legacy per-pool paths still work and are unchanged.",
     ],
   },
   {
     command: ["account", "sticky"],
     summary: "Show or set how many consecutive requests stay on one account.",
+    routes: [
+      { method: "GET", path: "/api/pool/settings" },
+      { method: "PUT", path: "/api/pool/settings" },
+      { method: "PATCH", path: "/api/pool/settings" },
+    ],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the applied strategy and sticky limit as JSON." }],
+    mutates: true,
+    json: "envelope",
+    details: ["Only meaningful under the sticky-capable strategies; the pool strategy is the other half of this setting."],
+  },
+  {
+    command: ["account", "auto-switch"],
+    summary: "Show or set the usage percentage at which a pool moves to another account.",
+    // Declared here rather than riding on `account strategy`, which is what it did before the
+    // unified route existed. `auto-switch` genuinely drives these three: the Codex pool reads
+    // its applied threshold from the active payload and writes through its own route, and a
+    // generic OAuth pool reads and writes the per-provider pool settings.
     routes: [
       { method: "GET", path: "/api/codex-auth/active" },
-      { method: "PUT", path: "/api/codex-auth/pool-strategy" },
+      { method: "PUT", path: "/api/codex-auth/auto-switch" },
       { method: "GET", path: "/api/oauth/accounts/pool" },
       { method: "PUT", path: "/api/oauth/accounts/pool" },
     ],
-    flags: [{ name: "--json", value: "boolean", summary: "Emit the applied strategy and sticky limit as JSON." }],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the stored threshold and whether it is applied." }],
     mutates: true,
     json: "envelope",
-    details: ["Only meaningful under the sticky-capable strategies; the pool strategy is the other half of this setting."],
+    details: [
+      "A bare invocation reads and never writes.",
+      "`on` stores 80%, `off` stores 0%, and `threshold <n>` accepts 0-100.",
+      "For a generic OAuth pool, `inert: true` means the threshold is stored but not applied, `inert: false` means the pool is applying it, and an absent `inert` is an unknown capability.",
+    ],
   },
+
   {
     command: ["logs"],
     summary: "Recent request log rows, filterable by provider, model, conversation, account, and status.",
diff --git a/src/cli/config-command.ts b/src/cli/config-command.ts
index b06ef38d15..a063602b59 100644
--- a/src/cli/config-command.ts
+++ b/src/cli/config-command.ts
@@ -144,8 +144,8 @@ function normalizeVisionConfig(config: OcxConfig): OcxConfig {
   const vision = config.visionSidecar;
   if (!vision || vision.reasoning === undefined) return config;
   // Keep CLI import/set semantics aligned with the execution path: an omitted or blank model means
-  // the bounded OpenAI vision default, gpt-5.4-mini, not the Dashboard's web-search default.
-  const model = vision.model || "gpt-5.4-mini";
+  // the bounded OpenAI vision default, gpt-5.6-luna, not the Dashboard's web-search default.
+  const model = vision.model || "gpt-5.6-luna";
   const normalized = normalizeVisionReasoningForModel(model, vision.reasoning);
   if (normalized === undefined) delete vision.reasoning;
   else vision.reasoning = normalized;
diff --git a/src/cli/dispatch.ts b/src/cli/dispatch.ts
index 768c86bf78..bf124af303 100644
--- a/src/cli/dispatch.ts
+++ b/src/cli/dispatch.ts
@@ -302,8 +302,20 @@ const commandRunners: Record<string, CommandRunner> = {
     return Number(process.exitCode ?? 0);
   },
   login: async deps => {
+    const loginArgs = deps.args.slice(1);
+    // 'ocx login codex' is the command people type first, and until now it answered with
+    // the full provider wall because the Codex pool lives behind 'ocx account login'.
+    // Route the three Codex spellings to that flow instead of making the user discover
+    // a second noun. Everything else stays on the local OAuth/API-key path.
+    const { isCodexAccountLoginName, handleAccountAuthCommand } = await import("./account-auth");
+    if (isCodexAccountLoginName(loginArgs[0] ?? "")) {
+      // null means "unknown subcommand", which "login" never is; the coalesce exists because
+      // the shared signature serves callers that do pass an unknown one.
+      const code = await handleAccountAuthCommand("login", loginArgs, { findLiveProxy: deps.findLiveProxy });
+      return code ?? 1;
+    }
     const { handleLogin } = await import("../oauth/login-cli");
-    await handleLogin(deps.args[1]);
+    await handleLogin(loginArgs[0]);
     return 0;
   },
   logout: async deps => {
@@ -440,7 +452,7 @@ const commandRunners: Record<string, CommandRunner> = {
             },
             config,
             port: live.port,
-          }, ["mcode", "pi", "raycast"]));
+          }, ["mcode", "pi", "raycast", "omo", "cline"]));
         } catch (error) {
           console.warn(`Client integrations were not refreshed: ${error instanceof Error ? error.message : String(error)}`);
         }
diff --git a/src/cli/export-command.ts b/src/cli/export-command.ts
index 739889a026..21d62f59c7 100644
--- a/src/cli/export-command.ts
+++ b/src/cli/export-command.ts
@@ -1,8 +1,10 @@
 /**
  * `ocx export --client <id>` — print a client config for the live proxy.
  *
- * Eight clients, four formats: OpenCode and Pi are JSON; OMP, Hermes, Gajae and
- * MiniMax Code are YAML; OpenClaw is JSON5; Kimi is TOML.
+ * Fourteen clients, five formats. The accepted list is `EXPORT_CLIENT_IDS`, not
+ * this comment: OpenCode, Pi, Prime, Aside, ZCode and omo are JSON; OMP,
+ * Hermes, gjc, DSH, MiniMax Code and Raycast are YAML; OpenClaw is JSON5; Kimi
+ * is TOML.
  *
  * Two consumers, one payload (devlog 260731_client_config_export/020):
  *
@@ -58,16 +60,6 @@ export interface ExportCommandDeps extends RuntimeApiDeps {
   configImpl?: () => OcxConfig;
 }
 
-/**
- * `/api/models` row plus the modality list Pi consumes. The launcher's row type predates
- * the Pi exporter and stops at the fields OpenCode needs.
- */
-type ExportProxyModelRow = OpencodeProxyModelRow & {
-  inputModalities?: string[];
-  reasoningEfforts?: string[];
-  defaultReasoningEffort?: string;
-};
-
 /**
  * Export rows from proxy `/api/models` rows.
  *
@@ -78,20 +70,13 @@ type ExportProxyModelRow = OpencodeProxyModelRow & {
  * row as the model itself: a second lookup over the raw rows would let a hidden or disabled
  * duplicate donate its ladder to the visible entry.
  *
- * Only modalities are re-joined by `namespaced`, because the catalog type does not carry them.
+ * Modalities need no such lookup: `opencodeCatalogFromProxyRows` carries them on the catalog
+ * entry, so the clients that filter them are handed the same filtered, deduped row.
  */
 export function exportModelsFromProxyRows(
-  rows: readonly ExportProxyModelRow[],
+  rows: readonly OpencodeProxyModelRow[],
   config: OcxConfig,
 ): ExportModel[] {
-  const modalities = new Map<string, string[]>();
-  for (const row of rows) {
-    const namespaced = row.namespaced?.trim();
-    if (!namespaced || modalities.has(namespaced)) continue;
-    if (Array.isArray(row.inputModalities) && row.inputModalities.length > 0) {
-      modalities.set(namespaced, [...row.inputModalities]);
-    }
-  }
   return opencodeCatalogFromProxyRows(rows, config).map(entry => {
     const model: ExportModel = {
       namespaced: entry.namespaced,
@@ -106,8 +91,9 @@ export function exportModelsFromProxyRows(
       model.reasoningEfforts = [...entry.reasoningEfforts];
     }
     if (entry.defaultReasoningEffort) model.defaultReasoningEffort = entry.defaultReasoningEffort;
-    const input = modalities.get(entry.namespaced);
-    if (input) model.inputModalities = [...input];
+    if (entry.inputModalities && entry.inputModalities.length > 0) {
+      model.inputModalities = [...entry.inputModalities];
+    }
     return model;
   });
 }
@@ -186,7 +172,7 @@ export async function handleExportCommand(argv: string[], deps: ExportCommandDep
       }
       built = { document: exported.config, text: exported.text };
     } else {
-      const rows = await runtimeRequest<ExportProxyModelRow[]>("/api/models", {}, { ...deps, baseUrl: root });
+      const rows = await runtimeRequest<OpencodeProxyModelRow[]>("/api/models", {}, { ...deps, baseUrl: root });
       if (!Array.isArray(rows)) {
         throw new RuntimeApiError("Management API returned an unexpected /api/models payload.", 502, rows);
       }
diff --git a/src/cli/help.ts b/src/cli/help.ts
index 764029b63e..8608e5789d 100644
--- a/src/cli/help.ts
+++ b/src/cli/help.ts
@@ -52,7 +52,7 @@ Usage:
   ocx doctor --recover-zero-byte-coordinator --yes
                               Back up a proven zero-byte Codex coordinator after stopping the proxy
   ocx debug <scope>           provider/usage/injection/claude on|off|status|reset
-  ocx login <provider>        OAuth or API-key provider login
+  ocx login <provider>        OAuth or API-key provider login (ocx login codex for Codex/ChatGPT)
   ocx logout <provider>       Remove a stored OAuth login
   ocx gui [pair --origin <browser-origin> [--json]]
                               Open the dashboard or create a single-use remote pairing grant
@@ -81,7 +81,7 @@ Usage:
   ocx memory [--json]         Alias of ocx observe memory
   ocx api-key <sub>           Alias of ocx access key
   ocx access <sub>            External API keys and endpoint information
-  ocx export --client <id>    Print a client config wired to the running proxy (13 clients)
+  ocx export --client <id>    Print a client config wired to the running proxy (15 clients)
   ocx integration client <sub> Enable, disable, inspect or roll back a client integration
   ocx grok <sub>              Grok Build model selection and apply
   ocx system <sub>            Runtime settings, startup, sync, OpenCodex updates, and Codex CLI inspection
diff --git a/src/cli/opencode.ts b/src/cli/opencode.ts
index adcdea1095..09ea024746 100644
--- a/src/cli/opencode.ts
+++ b/src/cli/opencode.ts
@@ -98,6 +98,8 @@ export interface OpencodeProxyModelRow {
   displayName?: string;
   displayNameSource?: "operator" | "provider" | "fallback";
   contextWindow?: number;
+  /** Declared input modalities from `/api/models`; carried into opencode model capabilities. */
+  inputModalities?: string[];
   /** Declared effort ladder from `/api/models`; carried into opencode model variants. */
   reasoningEfforts?: string[];
   /** Declared default effort from `/api/models`. */
@@ -396,6 +398,9 @@ export function opencodeCatalogFromProxyRows(
       id: row.id,
       contextWindow: row.contextWindow,
       displayName: row.displayNameSource === "fallback" ? undefined : row.displayName,
+      ...(Array.isArray(row.inputModalities) && row.inputModalities.length > 0
+        ? { inputModalities: [...row.inputModalities] }
+        : {}),
       ...(typeof row.fastRowAvailable === "boolean" ? { fastRowAvailable: row.fastRowAvailable } : {}),
       ...(Array.isArray(row.reasoningEfforts) && row.reasoningEfforts.length > 0
         ? { reasoningEfforts: [...row.reasoningEfforts] }
diff --git a/src/cli/registry.ts b/src/cli/registry.ts
index f219043254..91eab8723b 100644
--- a/src/cli/registry.ts
+++ b/src/cli/registry.ts
@@ -152,7 +152,16 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "Env default: OCX_DEBUG=1 (legacy OCX_DEBUG_FRAMES still works)",
     ],
   },
-  { name: "login", usage: "ocx login <provider>", summary: "OAuth or API-key login for a provider." },
+  {
+    name: "login",
+    usage: "ocx login <provider>",
+    summary: "OAuth or API-key login for a provider.",
+    details: [
+      "Codex/ChatGPT: ocx login codex runs the Codex account-pool login (same flow as ocx account login codex).",
+      "That one needs a running proxy; the OAuth and API-key providers log in locally.",
+      "'chatgpt' and 'openai' are the same route; an OpenAI platform API key is 'ocx login openai-apikey'.",
+    ],
+  },
   { name: "logout", usage: "ocx logout <provider>", summary: "Remove a stored provider login." },
   {
     name: "gui",
@@ -212,7 +221,7 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   },
   {
     name: "account",
-    usage: "ocx account <list|current|use|refresh|auto-switch|priority|login|reauth|code|cancel|remove|add-key|reset-credits|main> ...",
+    usage: "ocx account <list|current|use|refresh|auto-switch|priority|login|reauth|code|cancel|remove|add-key|reset-credits|grok-reset-coupons|main> ...",
     summary: "List and switch provider accounts and API-key pools (GUI parity).",
     details: [
       "list [provider]     Codex account pool, OAuth accounts and API keys (identifiers shown masked as the API returns them).",
@@ -225,6 +234,7 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "add-key <provider> [--label <label>]  Add a key read only from piped stdin.",
       "login/reauth/code/cancel  Run browser or manual-code auth from a headless shell.",
       "reset-credits <id|main> [--consume --yes]  Inspect or consume Codex reset credits.",
+      "grok-reset-coupons [<id>] [--consume --yes] Inspect or redeem Grok reset coupons.",
       "main <subcommand>     Manage the physical native Codex login separately from Pool routing.",
       "Switching the active account takes effect immediately; running threads move on their next request, and in-flight requests keep the account they captured.",
       "A selection-order change applies from the next unbound request and never moves a bound thread.",
@@ -327,11 +337,12 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   { name: "api-key", usage: "ocx api-key <list|create|rotate|remove> ...", summary: "Alias of ocx access key." },
   {
     name: "export",
-    usage: "ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|prime|aside|raycast> [--json] [--out <path>] [--force]",
-    summary: "Print a client config (OpenCode, Pi, OMP, Hermes, OpenClaw, Kimi Code, Gajae Code, DeepSeek Harness, MiniMax Code, ZCode, Prime Agent, Aside, Raycast) wired to the running proxy.",
+    usage: "ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|prime|aside|raycast|omo|cline> [--json] [--out <path>] [--force]",
+    summary: "Print a client config (OpenCode, Pi, OMP, Hermes, OpenClaw, Kimi Code, gjc, DeepSeek Harness, MiniMax Code, ZCode, Prime Agent, Aside, Raycast, omo, Cline) wired to the running proxy.",
     details: [
       "--json prints the generated document as JSON on stdout; use --out for the client's native format.",
       "--out <path> writes the native config there and refuses to replace an existing file without --force.",
+      "Cline exports a two-document bundle: settings for providers.json and catalog for sibling models.json. Use integration client enable --client cline for a journaled write.",
       "The config never contains a real key; it carries a documented env reference or a non-secret loopback placeholder.",
       "The destination path is printed for merging by hand — ocx never writes your real client config.",
     ],
diff --git a/src/clients/config-export.ts b/src/clients/config-export.ts
index 6a94b74d70..2aac798de4 100644
--- a/src/clients/config-export.ts
+++ b/src/clients/config-export.ts
@@ -21,7 +21,7 @@
  */
 import { homedir } from "node:os";
 import { existsSync, readFileSync } from "node:fs";
-import { isAbsolute, join, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { shouldInjectApiAuthHeader, standaloneCodexRoutingTarget } from "../codex/inject";
 import { FORMAT_MEDIA_TYPE, serializeDocument, type ConfigFormat } from "../integrations/serialize";
 import { canonicalizeReasoningEfforts } from "../reasoning-effort";
@@ -42,11 +42,12 @@ export { buildRaycastClientConfig, summarizeRaycast, buildRaycastContribution }
 
 import type { OpencodeLaunchEnv, OpencodeCatalogModel, ExportContext, PiModelEntry, ManagedContribution, ManagedFragment, ExportClientId, ExportClientSpec } from "./config-export/contracts";
 import { OPENCODE_API_KEY_ENV_REF, OPENCODE_PROVIDER_BLOCK_DEFAULT_CONFIG, OPENCODE_CONFIG_SCHEMA, OPENCODE_PROVIDER_ID, PI_API_DIALECT, LOOPBACK_API_KEY_PLACEHOLDER, HERMES_API_KEY_ENV_REF, OPENCLAW_API_KEY_ENV_REF, GAJAE_API_KEY_ENV, OPENCODE_API_KEY_ENV, HERMES_API_KEY_ENV, OPENCLAW_API_KEY_ENV } from "./config-export/constants";
-import { exportModelLabel, authoritativeContextWindow, outputBudgetFor, normalizeExportModels, inputModalitiesForClient, proxyAdmissionHeaders, singleFragment } from "./config-export/model-metadata";
+import { exportModelLabel, authoritativeContextWindow, outputBudgetFor, normalizeExportModels, inputModalitiesForClient, opencodeModelCapabilities, proxyAdmissionHeaders, singleFragment } from "./config-export/model-metadata";
 import { buildOmpClientConfig, summarizeOmp, buildOmpContribution } from "./config-export/omp";
 import { buildDshClientConfig, summarizeDsh, buildDshContribution } from "./config-export/dsh";
 import { buildMcodeClientConfig, summarizeMcode, buildMcodeContribution } from "./config-export/mcode";
 import { buildZcodeClientConfig, summarizeZcode, buildZcodeContribution } from "./config-export/zcode";
+import { buildClineClientConfig, summarizeCline, buildClineContribution } from "./config-export/cline";
 import { buildRaycastClientConfig, summarizeRaycast, buildRaycastContribution } from "./config-export/raycast";
 
 
@@ -54,6 +55,14 @@ import { buildRaycastClientConfig, summarizeRaycast, buildRaycastContribution }
 export interface OpencodeModelEntry {
   name: string;
   limit?: { context: number; output: number };
+  /**
+   * opencode's own capability fields, derived from the catalog row's declared input
+   * modalities. Written only when the row declares at least one — an entry without them is
+   * what opencode already treats as text-only, and omitting them keeps an undeclared model
+   * byte-identical to what shipped before.
+   */
+  attachment?: boolean;
+  modalities?: { input: string[]; output: string[] };
 }
 
 /**
@@ -458,6 +467,51 @@ export function primeConfigPath(env: OpencodeLaunchEnv = process.env, home: stri
   return join(primeAgentDir(env, home), "models.json");
 }
 
+/**
+ * omo resolves its agent directory from THREE variables, in its own order:
+ * `OMO_CODING_AGENT_DIR`, then `SENPI_CODING_AGENT_DIR`, then
+ * `PI_CODING_AGENT_DIR`, falling back to `~/.omo/agent`. That is not an
+ * inference from the family resemblance — `bin/lib/agent-dir.js` publishes the
+ * list as `AGENT_DIR_ENV_NAMES` and the launcher pins the first two to whatever
+ * it resolves before spawning senpi, so the engine can never disagree with it.
+ *
+ * The order is load-bearing rather than cosmetic. A user with both
+ * `PI_CODING_AGENT_DIR` and `OMO_CODING_AGENT_DIR` set runs omo out of the omo
+ * one; checking Pi's first would have us write a catalog omo never reads.
+ *
+ * Each variable reports under its OWN name, because telling someone that
+ * `PI_CODING_AGENT_DIR` is relative when they set `OMO_CODING_AGENT_DIR` sends
+ * them to the wrong line of their shell profile. An empty or whitespace value
+ * falls through to the next name, which is what omo's own `.trim()`-then-test
+ * loop does.
+ *
+ * One divergence is deliberate: omo `resolve()`s a relative override against its
+ * own cwd and does not expand `~`. We refuse the relative form and do expand
+ * `~`, exactly as Pi, Prime, MCode and ZCode already do, because a background
+ * proxy and a foreground client have different working directories and would
+ * otherwise disagree about which file is named.
+ *
+ * Consequence worth knowing: a user who sets only `PI_CODING_AGENT_DIR` has Pi
+ * and omo reading ONE `models.json`. Both clients emit the same provider block
+ * through the same builder so the bytes agree; what cannot be shared is the
+ * ownership record, since two enabled clients would claim one file. That is
+ * omo's contract, not ours to paper over.
+ */
+export function omoAgentDir(env: OpencodeLaunchEnv = process.env, home: string = homedir()): string {
+  const omo = env.OMO_CODING_AGENT_DIR?.trim();
+  if (omo) return absoluteClientPath(omo, home, "OMO_CODING_AGENT_DIR");
+  const senpi = env.SENPI_CODING_AGENT_DIR?.trim();
+  if (senpi) return absoluteClientPath(senpi, home, "SENPI_CODING_AGENT_DIR");
+  const pi = env.PI_CODING_AGENT_DIR?.trim();
+  if (pi) return absoluteClientPath(pi, home, "PI_CODING_AGENT_DIR");
+  return join(home, ".omo", "agent");
+}
+
+/** omo's canonical custom-provider catalog, read by the senpi engine it wraps. */
+export function omoConfigPath(env: OpencodeLaunchEnv = process.env, home: string = homedir()): string {
+  return join(omoAgentDir(env, home), "models.json");
+}
+
 /**
  * Aside's state root. Unlike every other client here, Aside ships NO variable
  * that relocates it: its CLI carries `ASIDE_DAEMON_BASE_URL`,
@@ -614,13 +668,30 @@ export function opencodeProviderBlocks(
     if (context !== undefined) {
       entry.limit = { context, output: outputBudgetFor(context) };
     }
+    // `attachment` / `modalities` are fields of opencode's V1 model schema — the shape its
+    // published config.json defines and the one its loader reads (verified against opencode
+    // 1.18.30, src/provider/provider.ts: `model.attachment ?? …` / `model.modalities?.input`).
+    // They ride on both generations anyway: the two blocks are two spellings of one model list,
+    // and the V2 model schema (capabilities.{tools,input,output}, which opencode fills by
+    // migrating this same `modalities` field) ignores keys it does not define — its loader
+    // decodes with `onExcessProperty: "ignore"`. Same values on both, so a merge cannot make
+    // the two entries disagree.
+    const capabilities = opencodeModelCapabilities(model.inputModalities);
+    if (capabilities) {
+      entry.attachment = capabilities.attachment;
+      entry.modalities = capabilities.modalities;
+    }
     v1Models[key] = entry;
     const variants = opencodeEffortVariants(model);
-    // Own `limit` object, not a shared reference: the two blocks are serialized and reasoned
-    // about separately, and an in-place edit of one must never move the other.
+    // Own `limit` and `modalities` objects, not shared references: the two blocks are
+    // serialized and reasoned about separately, and an in-place edit of one must never move
+    // the other.
     v2Models[key] = {
       ...entry,
       ...(entry.limit ? { limit: { ...entry.limit } } : {}),
+      ...(entry.modalities
+        ? { modalities: { input: [...entry.modalities.input], output: [...entry.modalities.output] } }
+        : {}),
       ...(variants ? { variants } : {}),
     };
   }
@@ -1109,6 +1180,44 @@ function buildAsideContribution(ctx: ExportContext): ManagedContribution {
   return singleFragment("aside", ["providers", OPENCODE_PROVIDER_ID], doc.providers[OPENCODE_PROVIDER_ID]);
 }
 
+/**
+ * omo is the Pi document again, and this time the engine was checked rather
+ * than inferred: `omo-ai@beta` is a launcher around `@code-yeongyu/senpi`, and
+ * senpi's compiled validator accepts what `buildPiClientConfig` emits verbatim —
+ * the keyed `providers`, the `models` ARRAY whose identity is `id`, the
+ * `openai-completions` dialect, the loopback placeholder, and the
+ * `thinkingLevelMap` levels. Evidence:
+ * `devlog/_plan/260912_omo_client_integration/001_omo_contract.md`.
+ *
+ * The flag is passed HERE as well as in the spec's `build`, which is the one
+ * thing Prime and Aside do not do. They pass the default on both paths, so they
+ * are consistent; passing it on only one would make `ocx export --client omo`
+ * emit a `compat` block while enable and refresh wrote a file without it, and
+ * the two would drift apart at the first refresh.
+ */
+function buildOmoContribution(ctx: ExportContext): ManagedContribution {
+  const doc = buildPiClientConfig(ctx, true);
+  return singleFragment("omo", ["providers", OPENCODE_PROVIDER_ID], doc.providers[OPENCODE_PROVIDER_ID]);
+}
+
+/** Cline's shared SDK store; command-local --config must be mirrored by the env override. */
+export function clineConfigPath(env: OpencodeLaunchEnv = process.env, home: string = homedir()): string {
+  const explicit = env.CLINE_PROVIDER_SETTINGS_PATH?.trim();
+  const data = env.CLINE_DATA_DIR?.trim();
+  const root = env.CLINE_DIR?.trim();
+  const path = explicit ? absoluteClientPath(explicit, home, "CLINE_PROVIDER_SETTINGS_PATH")
+    : join(data ? absoluteClientPath(data, home, "CLINE_DATA_DIR")
+      : join(root ? absoluteClientPath(root, home, "CLINE_DIR") : join(home, ".cline"), "data"), "settings", "providers.json");
+  if (basename(path).toLowerCase() === "models.json") {
+    throw new ClientPathError("CLINE_PROVIDER_SETTINGS_PATH must differ from the sibling models.json catalog");
+  }
+  return path;
+}
+
+export function clineSettingsDir(env: OpencodeLaunchEnv = process.env, home: string = homedir()): string {
+  return dirname(clineConfigPath(env, home));
+}
+
 export const EXPORT_CLIENTS: Record<ExportClientId, ExportClientSpec> = {
   opencode: {
     id: "opencode",
@@ -1297,6 +1406,49 @@ export const EXPORT_CLIENTS: Record<ExportClientId, ExportClientSpec> = {
     // remote bind would be a plaintext secret on disk. Refuse instead.
     loopbackOnly: true,
   },
+  /*
+   * Appended rather than filed beside the other Pi-family clients on purpose.
+   * `EXPORT_CLIENT_IDS` is `Object.keys(EXPORT_CLIENTS)`, so this object's
+   * insertion order IS the public order, and three tests assert it exactly. The
+   * existing sequence is landing order — `pi` second, `prime` eleventh — not a
+   * grouping, so appending is the edit that leaves the other thirteen alone.
+   */
+  omo: {
+    id: "omo",
+    // Not a bare `models.json`: same Downloads-folder collision argument as
+    // `prime-models.json` and `aside-models.json`.
+    filename: "omo-models.json",
+    destination: env => omoConfigPath(env),
+    apiKeyEnv: "",
+    exportHint: "omo reads a non-secret placeholder from models.json; loopback needs no key.",
+    build: ctx => buildPiClientConfig(ctx, true),
+    format: "json",
+    summarize: summarizePi,
+    buildContribution: buildOmoContribution,
+    /*
+     * Loopback-only for OMP's and Prime's reason, NOT Pi's and Aside's. senpi's
+     * provider block does accept a `headers` map and does interpolate `$ENV` in
+     * its values, so unlike Aside there is somewhere the dedicated admission
+     * header could live. What does not exist is a builder that emits one:
+     * `buildPiClientConfig` writes no headers at all, which is why `pi` is
+     * loopback-only too. Teaching the shared builder to emit them would change
+     * four clients at once, so remote wiring is deferred and a non-loopback bind
+     * refuses rather than generating a config that 401s.
+     */
+    loopbackOnly: true,
+  },
+  cline: {
+    id: "cline",
+    filename: "cline-config-bundle.json",
+    destination: env => clineConfigPath(env),
+    apiKeyEnv: "",
+    exportHint: "Cline CLI bundle: settings goes in providers.json, catalog in sibling models.json. Stop Cline before enabling/syncing/restoring, then restart. Select --provider opencodex; the default provider stays unchanged. Loopback only.",
+    build: buildClineClientConfig,
+    format: "json",
+    summarize: summarizeCline,
+    buildContribution: buildClineContribution,
+    loopbackOnly: true,
+  },
 };
 
 export const EXPORT_CLIENT_IDS: readonly ExportClientId[] = Object.keys(EXPORT_CLIENTS) as ExportClientId[];
diff --git a/src/clients/config-export/cline.ts b/src/clients/config-export/cline.ts
new file mode 100644
index 0000000000..82398de788
--- /dev/null
+++ b/src/clients/config-export/cline.ts
@@ -0,0 +1,71 @@
+import type { ExportContext, ManagedContribution } from "./contracts";
+import { LOOPBACK_API_KEY_PLACEHOLDER, OPENCODE_PROVIDER_ID } from "./constants";
+import { authoritativeContextWindow, exportModelLabel, inputModalitiesForClient, normalizeExportModels } from "./model-metadata";
+
+/** Cline CLI/shared SDK schema at cline/cline cfe9cadab996 (2026-09-12). */
+export interface ClineModel {
+  name: string;
+  contextWindow?: number;
+  modalities?: { input: string[]; output: string[] };
+  supportsVision?: boolean;
+}
+
+export function buildClineClientConfig(ctx: ExportContext) {
+  const models: Record<string, ClineModel> = {};
+  for (const model of normalizeExportModels(ctx.models)) {
+    const input = inputModalitiesForClient("pi", model.inputModalities);
+    if (input === null) continue;
+    const contextWindow = authoritativeContextWindow(model.contextWindow);
+    models[model.namespaced] = {
+      name: exportModelLabel(model),
+      ...(contextWindow === undefined ? {} : { contextWindow }),
+      ...(model.inputModalities?.length ? {
+        modalities: { input, output: ["text"] },
+        supportsVision: input.includes("image"),
+      } : {}),
+    };
+  }
+  const connection = { baseUrl: ctx.baseUrl, protocol: "openai-responses", client: "openai" } as const;
+  return {
+    settings: {
+      version: 1,
+      modes: {},
+      providers: {
+        [OPENCODE_PROVIDER_ID]: {
+          settings: { provider: OPENCODE_PROVIDER_ID, ...connection, apiKey: LOOPBACK_API_KEY_PLACEHOLDER },
+          // Required by Cline's schema; a stable generation sentinel keeps export deterministic.
+          // The operation's actual time belongs to the OpenCodex journal.
+          updatedAt: "1970-01-01T00:00:00.000Z",
+          tokenSource: "manual",
+        },
+      },
+    },
+    catalog: {
+      version: 1,
+      providers: {
+        [OPENCODE_PROVIDER_ID]: {
+          provider: { name: "OpenCodex", ...connection },
+          models,
+        },
+      },
+    },
+  };
+}
+
+export type ClineGeneratedConfig = ReturnType<typeof buildClineClientConfig>;
+
+export function summarizeCline(document: unknown) {
+  const models = Object.values((document as ClineGeneratedConfig | undefined)?.catalog?.providers?.[OPENCODE_PROVIDER_ID]?.models ?? {});
+  return { modelCount: models.length, modelsWithoutLimits: models.filter(model => model.contextWindow === undefined).length };
+}
+
+export function buildClineContribution(ctx: ExportContext): ManagedContribution {
+  const document = buildClineClientConfig(ctx);
+  return {
+    clientId: "cline",
+    fragments: [
+      { path: ["settings", "providers", OPENCODE_PROVIDER_ID], value: document.settings.providers[OPENCODE_PROVIDER_ID] },
+      { path: ["catalog", "providers", OPENCODE_PROVIDER_ID], value: document.catalog.providers[OPENCODE_PROVIDER_ID] },
+    ],
+  };
+}
diff --git a/src/clients/config-export/contracts.ts b/src/clients/config-export/contracts.ts
index c888a4c257..5ed2626180 100644
--- a/src/clients/config-export/contracts.ts
+++ b/src/clients/config-export/contracts.ts
@@ -38,6 +38,13 @@ export interface OpencodeCatalogModel {
   id?: string;
   contextWindow?: number;
   displayName?: string;
+  /**
+   * Declared input modalities, carried verbatim from `/api/models`. Serialized as opencode's
+   * per-model `attachment` + `modalities`, because opencode gates attachments CLIENT-side:
+   * without them every `opencodex` model is text-only in its picker and an image never
+   * reaches the proxy or the vision sidecar (#4286).
+   */
+  inputModalities?: readonly string[];
   /** Declared effort ladder. Exported as opencode model variants where the client reads them. */
   reasoningEfforts?: readonly string[];
   /**
@@ -94,7 +101,9 @@ export type ExportClientId =
   | "zcode"
   | "prime"
   | "aside"
-  | "raycast";
+  | "raycast"
+  | "omo"
+  | "cline";
 
 export interface ExportClientSpec {
   id: ExportClientId;
diff --git a/src/clients/config-export/model-metadata.ts b/src/clients/config-export/model-metadata.ts
index 7b24390341..5c69af92ca 100644
--- a/src/clients/config-export/model-metadata.ts
+++ b/src/clients/config-export/model-metadata.ts
@@ -72,6 +72,39 @@ export function inputModalitiesForClient(
   return kept.length > 0 ? kept : null;
 }
 
+/**
+ * Input modalities opencode's model schema accepts (opencode.ai/config.json, both
+ * `modalities.input` and `modalities.output`). Wider than our internal `text | image | audio`
+ * vocabulary, so unlike Pi and Gajae this filter can only drop a value no current ingress
+ * produces: `/api/custom-models`, `ocx models add` and the catalog writer all normalize to
+ * the internal three. It exists so a future ingress cannot do to opencode what `audio` did
+ * to Gajae, whose loader rejected the whole config file over one out-of-enum value.
+ */
+const OPENCODE_INPUT_MODALITIES: ReadonlySet<string> = new Set(["text", "audio", "image", "video", "pdf"]);
+
+/**
+ * opencode's per-model capability fields for one catalog row, or `undefined` when the row
+ * declares nothing.
+ *
+ * `undefined` rather than `{ input: ["text"] }`: opencode already computes an entry without
+ * capabilities as text-only, and leaving the keys out keeps every model that declares
+ * nothing byte-identical to what shipped before. A declared list is carried across as-is, so
+ * an audio-only row keeps `attachment: true` instead of being rewritten to text it cannot
+ * read — the same call Pi's exporter makes, in the opposite direction.
+ */
+export function opencodeModelCapabilities(
+  modalities: readonly string[] | undefined,
+): { attachment: boolean; modalities: { input: string[]; output: string[] } } | undefined {
+  const input: string[] = [];
+  for (const value of modalities ?? []) {
+    if (OPENCODE_INPUT_MODALITIES.has(value) && !input.includes(value)) input.push(value);
+  }
+  if (input.length === 0) return undefined;
+  // `attachment` is what opencode's client gates pasting on; `modalities` refines it into
+  // which kinds. Output is always text — nothing in the catalog declares otherwise.
+  return { attachment: input.some(value => value !== "text"), modalities: { input, output: ["text"] } };
+}
+
 /**
  * Label shared by every client: `"<displayName|id> (<native|provider|routed>)"`. The
  * provider suffix is what makes two same-named models from different upstreams
diff --git a/src/clients/config-export/zcode.ts b/src/clients/config-export/zcode.ts
index d8ec37ff1a..edd200beba 100644
--- a/src/clients/config-export/zcode.ts
+++ b/src/clients/config-export/zcode.ts
@@ -6,9 +6,18 @@ import { OPENCODE_PROVIDER_ID, LOOPBACK_API_KEY_PLACEHOLDER } from "./constants"
 
 
 /**
- * ZCode's `~/.zcode/v2/config.json` provider entry (observed schema, validated
- * live against ZCode 3.7.7 / 3.8.1). `kind: "openai-compatible"` selects the
- * OpenAI Chat Completions protocol, which the proxy serves at `/v1/chat/completions`.
+ * ZCode's `~/.zcode/v2/config.json` provider entry (observed schema, validated live
+ * against ZCode 3.7.7 / 3.8.1 and re-extracted from 3.11.2's bundle).
+ * `kind: "openai"` selects the OpenAI Responses protocol, which the proxy serves at
+ * `/v1/responses`. ZCode's own dispatch is the authority: its
+ * `getDefaultModelProviderEndpointPathForKind` maps `anthropic` to `/v1/messages`,
+ * `openai` to `/responses`, and `openai-compatible` to `/chat/completions`.
+ *
+ * Responses is the only surface the proxy speaks natively. The Chat and Anthropic
+ * inbounds translate their body into a Responses shape and replay it through
+ * `handleResponses`, then translate the stream back, so the previous
+ * `openai-compatible` wiring paid two translations per turn and reshaped tool-call
+ * deltas and reasoning blocks on the way through.
  * `apiKeyRequired` keeps ZCode's UI from prompting for a key it does not need on
  * loopback; the serialized key is always the non-secret loopback placeholder.
  */
@@ -30,7 +39,7 @@ export interface ZcodeModelEntry {
 
 export interface ZcodeProviderBlock {
   name: "OpenCodex";
-  kind: "openai-compatible";
+  kind: "openai";
   enabled: true;
   source: "custom";
   options: {
@@ -46,11 +55,12 @@ export interface ZcodeGeneratedConfig {
 }
 
 /**
- * ZCode dials the OpenAI Chat Completions surface (`openai-compatible`), which
- * appends `/chat/completions` to `baseURL`. We supply `baseURL` with the `/v1`
- * suffix so requests land on `/v1/chat/completions`. Model ids are the proxy's canonical
- * `provider/id` selectors, which `/v1/chat/completions` resolves directly. Context
- * limits follow the authoritative-window rule: a model without one ships
+ * ZCode dials the OpenAI Responses surface (`openai`), which appends `/responses` to
+ * `baseURL`. We supply `baseURL` with the `/v1` suffix so requests land on
+ * `/v1/responses`; ZCode's `normalizeModelProviderBaseUrlForKind` strips only the
+ * `/responses` suffix for this kind, so the `/v1` root survives. Model ids are the
+ * proxy's canonical `provider/id` selectors, which `/v1/responses` resolves directly.
+ * Context limits follow the authoritative-window rule: a model without one ships
  * without `limit` rather than guessing. Modalities are ZCode's observed
  * `text`-floor vocabulary; image-capable rows advertise image input.
  */
@@ -73,8 +83,9 @@ export function buildZcodeClientConfig(ctx: ExportContext): ZcodeGeneratedConfig
       entry.limit = { context };
     }
     // `none` is a Codex omit-sentinel, not a ZCode picker option. Keep catalog
-    // `ultra` when present: ZCode forwards the selected variant as
-    // `reasoning_effort`. Set `defaultVariant` only when it survives that filter.
+    // `ultra` when present: ZCode forwards the selected variant to the wire field its
+    // kind uses — `reasoning.effort` on `openai`, which is what `/v1/responses` reads
+    // natively. Set `defaultVariant` only when it survives that filter.
     const efforts = sanitizeCodexReasoningEfforts(model.reasoningEfforts)
       ?.filter(effort => effort !== "none");
     if (efforts && efforts.length > 0) {
@@ -91,7 +102,7 @@ export function buildZcodeClientConfig(ctx: ExportContext): ZcodeGeneratedConfig
     provider: {
       [OPENCODE_PROVIDER_ID]: {
         name: "OpenCodex",
-        kind: "openai-compatible",
+        kind: "openai",
         enabled: true,
         source: "custom",
         options: {
diff --git a/src/codex/account-store.ts b/src/codex/account-store.ts
index 4e8d5c513e..285db1708c 100644
--- a/src/codex/account-store.ts
+++ b/src/codex/account-store.ts
@@ -751,8 +751,13 @@ export async function forceRefreshCodexPoolToken(
   };
 }
 
-export async function getValidCodexToken(id: string): Promise<CodexTokenResult> {
-  const result = await resolveCodexToken(id);
+export async function getValidCodexToken(
+  id: string,
+  options: { signal?: AbortSignal } = {},
+): Promise<CodexTokenResult> {
+  // Cancellation ends THIS caller's wait. A shared refresh already in flight keeps running for
+  // whoever else awaits it, which is what `awaitOwnCancellation` inside the resolver preserves.
+  const result = await resolveCodexToken(id, undefined, options.signal);
   return {
     accessToken: result.accessToken,
     chatgptAccountId: result.chatgptAccountId,
diff --git a/src/codex/auth-context.ts b/src/codex/auth-context.ts
index 2cb97df2e9..f362a2893a 100644
--- a/src/codex/auth-context.ts
+++ b/src/codex/auth-context.ts
@@ -1023,7 +1023,7 @@ export async function resolveCodexAuthContext(
   }
 
   try {
-    const token = await getValidCodexToken(accountId);
+    const token = await getValidCodexToken(accountId, { signal: options.signal });
     assertCodexAccountValidationReady(accountId);
     return {
       kind: "pool",
diff --git a/src/codex/catalog/effort.ts b/src/codex/catalog/effort.ts
index f54792b2ec..7aa0f006dc 100644
--- a/src/codex/catalog/effort.ts
+++ b/src/codex/catalog/effort.ts
@@ -59,9 +59,10 @@ export function nativeEffortClamp(slug: string, effort: string | undefined): str
     : [];
   if (levels.length === 0) {
     // Not snapshot-covered. gpt-5.6 natives have a REAL max rung (ensureGpt56ReasoningLevels
-    // restores it even off-snapshot) -> never clamp. Every other bare native (gpt-5.5/5.4/
-    // 5.4-mini/5.3-codex-spark and future old-ladder slugs) really stops at xhigh — the
-    // ChatGPT backend error names exactly none..xhigh — so clamp the synthetic top tier.
+    // restores it even off-snapshot) -> never clamp. Every other bare native (gpt-5.5,
+    // 5.3-codex-spark, a retired slug a client still asks for, and future old-ladder slugs)
+    // really stops at xhigh — the ChatGPT backend error names exactly none..xhigh — so clamp
+    // the synthetic top tier.
     return isGpt56NativeSlug(slug) ? null : "xhigh";
   }
   const supported = levels.flatMap(l => typeof l.effort === "string" ? [l.effort] : []);
diff --git a/src/codex/catalog/metadata.ts b/src/codex/catalog/metadata.ts
index f239ce48b1..0b16e7d7bb 100644
--- a/src/codex/catalog/metadata.ts
+++ b/src/codex/catalog/metadata.ts
@@ -48,6 +48,7 @@ import {
   NATIVE_OPENAI_MODELS,
   SELF_DESCRIBED_NATIVE_OPENAI_MODELS,
   SUPPORTED_NATIVE_OPENAI_SLUGS,
+  RETIRED_NATIVE_OPENAI_MODELS,
   hasNativeOpenAiCapabilityMetadata,
   isNativeOpenAiCapabilityAliasModel,
   nativeOpenAiAliasPresentation,
@@ -63,6 +64,7 @@ export {
   NATIVE_OPENAI_MODELS,
   SELF_DESCRIBED_NATIVE_OPENAI_MODELS,
   SUPPORTED_NATIVE_OPENAI_SLUGS,
+  RETIRED_NATIVE_OPENAI_MODELS,
   hasNativeOpenAiCapabilityMetadata,
   isNativeOpenAiCapabilityAliasModel,
   nativeOpenAiAliasPresentation,
@@ -120,8 +122,7 @@ export function isUnsupportedOpenAiNativeSlug(slug: string): boolean {
  *
  * This is an OPERATING CAP, not the hard ceiling — the same shape upstream uses. The live
  * catalog reports `context_window: 272000` against a `max_context_window: 872000` for these
- * slugs, and gpt-5.4 runs 272,000 against 1,000,000: the advertised window is always well
- * inside what the model can take.
+ * slugs: the advertised window is always well inside what the model can take.
  *
  * The hard ceiling here was measured on 2026-08-17 against a real Codex-login account:
  * `POST /backend-api/codex/responses` admitted 921,508 input tokens and refused 922,013 with
@@ -162,7 +163,6 @@ const NATIVE_GPT56_FAMILY = new Set<string>([
 
 export const NATIVE_OPENAI_CONTEXT_OVERRIDES: Record<string, { contextWindow?: number; maxContextWindow?: number; maxInputTokens?: number }> = {
   "gpt-5.5": { contextWindow: 272_000, maxContextWindow: 272_000 },
-  "gpt-5.4": { contextWindow: 1_000_000, maxContextWindow: 1_000_000 },
   "gpt-5.3-codex-spark": { contextWindow: 100_000, maxContextWindow: 100_000 },
   "gpt-5.6-sol": { contextWindow: NATIVE_GPT56_CONTEXT_WINDOW, maxContextWindow: NATIVE_GPT56_MAX_INPUT_TOKENS, maxInputTokens: NATIVE_GPT56_MAX_INPUT_TOKENS },
   "gpt-5.6-terra": { contextWindow: NATIVE_GPT56_CONTEXT_WINDOW, maxContextWindow: NATIVE_GPT56_MAX_INPUT_TOKENS, maxInputTokens: NATIVE_GPT56_MAX_INPUT_TOKENS },
@@ -537,7 +537,7 @@ function upstreamNativeEntryForSlug(slug: string): RawEntry | undefined {
   const sourceSlug = nativeOpenAiCapabilitySourceSlug(slug);
   // A self-described native returns its OWN pinned row; the alias-cloning branch below stays
   // reserved for slugs that genuinely borrow another model's identity. The allowlist is explicit
-  // rather than "has a pinned entry", which would also admit gpt-5.5/gpt-5.4/gpt-5.4-mini into
+  // rather than "has a pinned entry", which would also admit gpt-5.5/gpt-5.2/codex-auto-review into
   // the sync-replacement authority this map carries.
   if (!sourceSlug.startsWith("gpt-5.6-") && !SELF_DESCRIBED_NATIVE_OPENAI_MODELS.has(slug)) {
     return undefined;
@@ -696,6 +696,10 @@ function hasNativeCatalogRowShape(entry: RawEntry): boolean {
 function observedAccountBoundNativeSlug(entry: RawEntry): string | undefined {
   const accountBound = trustedAccountBoundNativeCatalogSlug(entry);
   const slug = accountBound ?? (typeof entry.slug === "string" ? entry.slug : "");
+  // A retired native is refused at this one choke point rather than at each call site: every
+  // observation path funnels through here, and an admitted retired slug comes back as a real
+  // catalog row — bare or account-qualified — with capabilities synthesized from the template.
+  if (RETIRED_NATIVE_OPENAI_MODELS.has(slug)) return undefined;
   if (!isAccountBoundOpenAiNativeSlug(slug)
     || (entry.supported_in_api !== true && !(slug === NATIVE_RESERVE_MODEL && entry.supported_in_api === false))
     || (slug === NATIVE_RESERVE_MODEL && entry[RESERVE_METADATA_SOURCE_FIELD] !== undefined
diff --git a/src/codex/catalog/native-models.ts b/src/codex/catalog/native-models.ts
index 691849fbdd..c7bee6d1f8 100644
--- a/src/codex/catalog/native-models.ts
+++ b/src/codex/catalog/native-models.ts
@@ -72,9 +72,11 @@ const NATIVE_OPENAI_CAPABILITY_SOURCES: Readonly<Record<string, string>> = Objec
  *
  * Membership authorizes `upstreamNativeEntryForSlug` to return the pinned entry directly. It is
  * an explicit list, not a structural `PINNED_UPSTREAM_MODELS.has(slug)` predicate: the pin also
- * holds `gpt-5.5`, `gpt-5.4` and `gpt-5.4-mini`, and admitting those into
+ * holds `gpt-5.5`, `gpt-5.2` and `codex-auto-review`, and admitting those into
  * `UPSTREAM_NATIVE_ENTRIES` would newly authorize replacing their persisted catalog rows during
- * sync — an invariant that map's own comment reserves for the GPT-5.6 family.
+ * sync — an invariant that map's own comment reserves for the GPT-5.6 family. The snapshot
+ * keeps rows this runtime does not expose, which is exactly why presence in the pin cannot be
+ * the predicate: `gpt-5.4` and `gpt-5.4-mini` are still pinned after their retirement.
  */
 export const SELF_DESCRIBED_NATIVE_OPENAI_MODELS: ReadonlySet<string> = new Set([
   NATIVE_GPT6_ASTRA_MODEL,
@@ -153,7 +155,7 @@ export function nativeOpenAiAliasPresentation(slug: string): { displayName: stri
  * Devlog: 260816_codexrs_multiagent_v2_and_history_perf/011 §4-bis.
  */
 export const NATIVE_OPENAI_MODELS = [
-  "gpt-5.5", "gpt-5.4", "gpt-5.4-mini", "gpt-5.3-codex-spark",
+  "gpt-5.5", "gpt-5.3-codex-spark",
   "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna",
   NATIVE_DAYBREAK_BLUE_MODEL,
   NATIVE_GPT6_ASTRA_MODEL,
@@ -161,6 +163,24 @@ export const NATIVE_OPENAI_MODELS = [
 
 export const SUPPORTED_NATIVE_OPENAI_SLUGS = new Set(NATIVE_OPENAI_MODELS);
 
+/**
+ * Natives this runtime used to ship that upstream has since retired.
+ *
+ * Leaving `NATIVE_OPENAI_MODELS` is not enough on its own. An account-bound observation admits
+ * any native it sees that is NOT already in `SUPPORTED_NATIVE_OPENAI_SLUGS` — that is how a
+ * genuinely new upstream model reaches one entitled account before this repo knows about it. A
+ * retired slug fails that same membership test, so a stale `selector/gpt-5.4` row persisted in a
+ * user's catalog or models cache would be re-observed as an unknown native and synthesized
+ * straight back into the picker, one sync after the removal took it out.
+ *
+ * This set is the difference between the two cases: unknown-and-new is admitted, known-and-dead
+ * is refused. It is deliberately explicit rather than a version heuristic, because the only
+ * thing that makes a slug retired is upstream withdrawing it.
+ */
+export const RETIRED_NATIVE_OPENAI_MODELS: ReadonlySet<string> = new Set([
+  "gpt-5.4", "gpt-5.4-mini",
+]);
+
 /**
  * Natives that retain the physical main account as a read-free sentinel during a native-main
  * drain, instead of reading as unavailable and letting the subagent fallback chain advance.
@@ -172,7 +192,7 @@ export const SUPPORTED_NATIVE_OPENAI_SLUGS = new Set(NATIVE_OPENAI_MODELS);
  * flipped false — letting a drain silently rewrite the operator's configured subagent model.
  *
  * It is an explicit list rather than `SUPPORTED_NATIVE_OPENAI_SLUGS`, which would have widened
- * the sentinel to `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini` and `gpt-5.3-codex-spark` as well. Those
+ * the sentinel to `gpt-5.5` and `gpt-5.3-codex-spark` as well. Those
  * models were never covered, and widening would turn "fell back and answered" into a
  * maintenance error for the most commonly configured fallback slug in the repo. Membership is
  * the set the drain behaviour was actually reasoned about: the account-gated natives plus the
diff --git a/src/codex/catalog/parsing.ts b/src/codex/catalog/parsing.ts
index 8430622092..06747a8553 100644
--- a/src/codex/catalog/parsing.ts
+++ b/src/codex/catalog/parsing.ts
@@ -183,6 +183,23 @@ export const ROUTED_MODEL_COMPATIBILITY_EXCLUSIONS = new Set([
   // Issue #2330: OpenCode Go models absent from current documentation or returning terminal HTTP 400 errors.
   "opencode-go/mimo-v2-omni",
   "opencode-go/mimo-v2-pro",
+  /*
+   * DeepSeek retired `deepseek-v4-pro` on 2026-09-14 04:00 UTC and routes its requests to
+   * V4.1-Flash (api-docs.deepseek.com/news/news260910). Deleting the registry rows removes
+   * the model on providers that publish a static roster, but every provider below discovers
+   * its models live — there, a deleted row does not remove anything, it only strips the
+   * context window, the effort ladder and the text-only hint, so the retired model would
+   * keep appearing with its capabilities broken. Excluding the slug is what actually takes
+   * it out of the routed catalog.
+   */
+  "command-code/deepseek-deepseek-v4-pro",
+  "commandcode/deepseek-deepseek-v4-pro",
+  "orcarouter/deepseek-deepseek-v4-pro",
+  "cline-pass/cline-pass-deepseek-v4-pro",
+  "baseten/deepseek-ai-DeepSeek-V4-Pro",
+  "digitalocean/deepseek-v4-pro",
+  "qoder/DeepSeek-V4-Pro",
+  "codebuddy/deepseek-v4-pro",
 ]);
 
 export function isRoutedModelCompatibilityExcluded(slug: string): boolean {
@@ -501,7 +518,8 @@ export function applyNativeOpenAiContextOverride(entry: RawEntry, limits?: Nativ
   }
   // providerContextCaps.openai is a ceiling for native OpenAI rows regardless of where the
   // advertised window came from (#1430): preserved rows without a hardcoded override (e.g.
-  // gpt-5.4-mini) must stay under the cap too, and auto-compaction follows the capped window.
+  // gpt-5.3-codex-spark) must stay under the cap too, and auto-compaction follows the capped
+  // window.
   // The per-model window narrows the same rows for the same reason.
   const currentContext = typeof entry.context_window === "number" ? entry.context_window : undefined;
   const cappedContext = narrowNativeMaxContextWindow(nativeSlug, currentContext, limits);
diff --git a/src/codex/catalog/provider-fetch.ts b/src/codex/catalog/provider-fetch.ts
index cf4e4dddef..68910ce0eb 100644
--- a/src/codex/catalog/provider-fetch.ts
+++ b/src/codex/catalog/provider-fetch.ts
@@ -54,6 +54,7 @@ import { fetchCursorUsableModels } from "../../adapters/cursor/live-models";
 import { recordLiveCursorClaudeModels, recordLiveCursorMaxModeModels } from "../../adapters/cursor/catalog";
 import { fetchQoderModels } from "../../adapters/qoder/live-models";
 import { resolveQoderProfile } from "../../adapters/qoder/profiles";
+import { fetchDevinUsableModels } from "../../adapters/devin/live-models";
 import { isCanonicalOpenAiForwardProvider, OPENAI_API_PROVIDER_ID, OPENAI_CODEX_PROVIDER_ID } from "../../providers/openai-tiers";
 import {
   COMBO_NAMESPACE,
@@ -1699,6 +1700,62 @@ async function fetchProviderModelsWithAuth(
       stale ? applyConfigHintsToCachedModels(name, prov, stale, contextCap, metadataModelIdCaseFold, captured.effectiveAlias) : configured,
     ), "degraded");
   }
+  if (prov.adapter === "devin") {
+    if (!apiKey) return observed(configured, "degraded");
+    const cachedDevin = getFreshCached(name, ttlMs);
+    if (cachedDevin) {
+      return observed(
+        withConfiguredRetention(applyConfigHintsToCachedModels(name, prov, cachedDevin)),
+        "authoritative",
+      );
+    }
+    if (isModelsFetchCoolingDown(name)) {
+      const cooling = getStaleCached(name);
+      return observed(
+        withConfiguredRetention(
+          cooling ? applyConfigHintsToCachedModels(name, prov, cooling) : configured,
+        ),
+        "degraded",
+      );
+    }
+    const liveResult = await fetchDevinUsableModels({ apiKey, baseUrl: prov.baseUrl });
+    if (liveResult.ok) {
+      // Live catalog is the source of truth — use the discovered base models
+      // directly, not a filtered subset of the static seed.
+      //
+      // That extends to the context window. Cognition publishes no window
+      // anywhere, so the per-account catalog is the only first-party number,
+      // and the shipped static table is a degraded-mode guess that was wrong
+      // for nine of its eleven rows. The live value is applied first and the
+      // config hints run after it, so an explicit per-model override and an
+      // enabled Context cap still win — this only replaces the number nobody
+      // chose.
+      const result = liveResult.models.map((id) => {
+        const liveWindow = liveResult.contextWindows[id];
+        return {
+          id,
+          provider: name,
+          ...(liveWindow ? { contextWindow: liveWindow } : {}),
+          ...catalogHintsFromProviderConfig(name, prov, id, contextCap, metadataModelIdCaseFold, captured.effectiveAlias),
+        } as CatalogModel;
+      });
+      const forCache = withConfiguredRetention(result, { retainComboTargets: false });
+      if (!setCached(name, forCache, Date.now(), cacheGeneration)) {
+        return observed(withConfiguredRetention(configured), "degraded");
+      }
+      markProviderDiscoveryOk(name, liveResult.models.length);
+      return observed(withConfiguredRetention(forCache), "authoritative");
+    }
+    if (isCurrentCacheGeneration()) {
+      markModelsFetchFailure(name);
+      markProviderDiscoveryFailed(name, { reason: liveResult.error === "auth" ? "provider" : "invalid_response" });
+    }
+    const stale = getStaleCached(name);
+    return observed(
+      withConfiguredRetention(stale ? applyConfigHintsToCachedModels(name, prov, stale) : configured),
+      "degraded",
+    );
+  }
   if (prov.adapter === "cursor") {
     if (!apiKey) return observed(configured, "degraded");
     // Cursor uses a bespoke GetUsableModels RPC (not /models), returning the full effort-suffixed
diff --git a/src/codex/catalog/sync.ts b/src/codex/catalog/sync.ts
index 074d9ddef0..2f756663ad 100644
--- a/src/codex/catalog/sync.ts
+++ b/src/codex/catalog/sync.ts
@@ -260,7 +260,7 @@ export function finishUpstreamNativeEntry(clone: RawEntry, priority: number, con
   if (priority !== 9) clone.priority = priority;
   applyNativeOpenAiContextOverride(clone, contextCap);
   // GPT-5.6 natives keep their exact upstream ladders (e.g. luna has max but no ultra).
-  // Older natives (gpt-5.5 / 5.4 / 5.4-mini / 5.3-codex-spark) get mock max + ultra
+  // Older natives (gpt-5.5 / 5.3-codex-spark) get mock max + ultra
   // (wire-clamped to xhigh). Ultra is always advertised regardless of v2 toggle.
   if (!isGpt56NativeSlug(String(clone.slug ?? ""))) ensureUltraReasoningLevel(clone);
   return ensureStrictCatalogFields(normalizeServiceTiers(clone));
diff --git a/src/codex/context-compat.ts b/src/codex/context-compat.ts
new file mode 100644
index 0000000000..e78a456163
--- /dev/null
+++ b/src/codex/context-compat.ts
@@ -0,0 +1,97 @@
+/** Backend path and opt-in config compatibility for native Codex history/notes. */
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { getCodexHome } from "./paths";
+
+export const CONTEXT_BACKEND_PREFIX = "/backend-api/codex";
+
+/** The single definition of the opt-in, shared by injection and the runtime gate. */
+export function contextExperimentalEnabled(configContent: string): boolean {
+  let parsed: { features?: { context_management?: { experimental_mode?: boolean } } };
+  try {
+    parsed = Bun.TOML.parse(configContent) as typeof parsed;
+  } catch {
+    // Injection tolerates incomplete user config; malformed TOML is not an opt-in.
+    return false;
+  }
+  return parsed.features?.context_management?.experimental_mode === true;
+}
+
+let activation: { key: string; active: boolean } | undefined;
+
+/**
+ * Whether this proxy may serve the context relay at all, decided by opencodex reading Codex own
+ * config rather than by anything a caller sends.
+ *
+ * Rewriting the injected base URL is what makes the feature REACHABLE, and gating only that would
+ * leave the ownership registry and both endpoint prefixes live for anyone who can already reach
+ * the data plane. An opt-in that a direct POST walks around is not an opt-in, so the same
+ * predicate guards recording and dispatch. An absent, unreadable or malformed config is not an
+ * opt-in. The result is cached against the config identity and re-read when the file changes, so
+ * turning the feature off takes effect without a restart and steady-state traffic does not parse
+ * TOML per request.
+ */
+export function contextRelayActivated(configPath?: string): boolean {
+  let key: string;
+  let path: string;
+  try {
+    // Resolved here, not in a default parameter: those are evaluated before the body, so a
+    // CODEX_HOME that became unreadable while the proxy runs would throw past this try. This
+    // function is now on the model path, where that would abort a turn upstream already served.
+    path = configPath ?? join(getCodexHome(), "config.toml");
+    const seen = statSync(path);
+    key = `${path}:${seen.mtimeMs}:${seen.size}:${String(seen.ino)}`;
+  } catch {
+    activation = undefined;
+    return false;
+  }
+  if (activation?.key === key) return activation.active;
+  let active = false;
+  try {
+    active = contextExperimentalEnabled(readFileSync(path, "utf8"));
+  } catch {
+    // A readable stat with an unreadable body caches false under that identity, so the feature
+    // stays off until the content itself changes. Fail-closed is the right direction here.
+    active = false;
+  }
+  activation = { key, active };
+  return active;
+}
+
+/** Test seam: the cache is keyed by config identity, which a temp home reuses across cases. */
+export function resetContextRelayActivationForTests(): void {
+  activation = undefined;
+}
+
+const CONTEXT_ENDPOINTS = new Set([
+  "alpha/history/v2/list_windows", "alpha/history/v2/list_items",
+  "alpha/history/v2/read_item", "alpha/history/v2/search_contents",
+  "alpha/notes/v2/thread_hint", "alpha/notes/v2/list_files_by_prefix",
+  "alpha/notes/v2/read_file", "alpha/notes/v2/search_contents",
+  "alpha/notes/v2/append_to_file", "alpha/notes/v2/write_file",
+]);
+
+export function contextEndpoint(path: string): string | undefined {
+  const endpoint = path.startsWith("/v1/") ? path.slice(4) : "";
+  return CONTEXT_ENDPOINTS.has(endpoint) ? endpoint : undefined;
+}
+
+/** Alias only the data-plane prefix. Existing auth/origin and route gates still run. */
+export function codexCompatibleUrl(rawUrl: string): URL {
+  const url = new URL(rawUrl);
+  if (url.pathname === CONTEXT_BACKEND_PREFIX || url.pathname.startsWith(CONTEXT_BACKEND_PREFIX + "/")) {
+    url.pathname = "/v1" + url.pathname.slice(CONTEXT_BACKEND_PREFIX.length);
+  }
+  return url;
+}
+
+/** Change only marker-managed built-in routing, and only with an explicit context opt-in. */
+export function contextCompatibleBaseLine(content: string, line: string): string {
+  if (!contextExperimentalEnabled(content)) return line;
+  const match = /^openai_base_url = "([^"]+)"$/.exec(line);
+  if (!match) return line;
+  const url = new URL(match[1]);
+  if (url.pathname !== "/v1" || !["127.0.0.1", "localhost", "[::1]"].includes(url.hostname)) return line;
+  url.pathname = CONTEXT_BACKEND_PREFIX;
+  return `openai_base_url = "${url.href}"`;
+}
diff --git a/src/codex/context-owner.ts b/src/codex/context-owner.ts
new file mode 100644
index 0000000000..eb38620131
--- /dev/null
+++ b/src/codex/context-owner.ts
@@ -0,0 +1,201 @@
+import { createHmac, randomBytes } from "node:crypto";
+import type { CodexAuthContext } from "./auth-context";
+import { MAIN_CODEX_ACCOUNT_ID } from "./account-id";
+import { nativeUserIdClaims } from "./reserve-availability";
+
+export type ContextSessionOwner = Readonly<
+  | { kind: "stored"; accountId: string; physicalIdentity: string; userIdentity?: string;
+      callerCredentialIdentity: string; ambiguous: boolean }
+  | { kind: "caller"; physicalIdentity?: string; userIdentity?: string;
+      callerCredentialIdentity: string; ambiguous: boolean }
+>;
+
+const TTL_MS = 24 * 60 * 60_000;
+const MAX_ENTRIES = 2048;
+const MAX_BYTES = 1024 * 1024;
+const salt = randomBytes(32);
+type Entry = { owner: ContextSessionOwner; destination: string; touchedAt: number; bytes: number };
+const owners = new Map<string, Entry>();
+let totalBytes = 0;
+
+function digest(domain: string, value: string): string {
+  return createHmac("sha256", salt).update(domain).update("\0").update(value).digest("hex");
+}
+
+function validId(value: string | null | undefined): value is string {
+  return typeof value === "string" && /^[A-Za-z0-9._:-]{1,512}$/.test(value);
+}
+
+function destinationIdentity(destination: string): string | undefined {
+  if (!destination || destination.length > 4096) return undefined;
+  try {
+    const url = new URL(destination);
+    if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.hash) return undefined;
+    return digest("destination", url.href.replace(/\/+$/, ""));
+  } catch { return undefined; }
+}
+
+function physicalIdentity(headers: Headers): string | undefined {
+  const account = headers.get("chatgpt-account-id");
+  return validId(account) ? digest("physical-account", account) : undefined;
+}
+
+/**
+ * The stable person behind an accepted credential, when the token says so.
+ *
+ * `chatgpt-account-id` names a WORKSPACE, and two people in one workspace send the same value.
+ * Ownership therefore also binds the user claim carried by the credential that upstream actually
+ * accepted. The claim is read without signature verification, which is why upstream acceptance
+ * remains the evidence and a conflicting pair of claims fails closed instead of picking one.
+ */
+function stableUserIdentity(headers: Headers): { identity?: string; conflict: boolean } {
+  const authorization = headers.get("authorization");
+  if (!authorization || authorization.length > 32_768 || !/^Bearer [^\s]+$/i.test(authorization)) {
+    return { conflict: false };
+  }
+  const claims = nativeUserIdClaims(authorization.slice(7));
+  if (claims.conflict) return { conflict: true };
+  return { ...(claims.userId ? { identity: digest("native-user", claims.userId) } : {}), conflict: false };
+}
+
+function callerCredentialIdentity(headers: Headers): string | undefined {
+  const authorization = headers.get("authorization");
+  if (!authorization || authorization.length > 32_768 || !/^Bearer [^\s]+$/i.test(authorization)) return undefined;
+  const account = headers.get("chatgpt-account-id");
+  if (account !== null && !validId(account)) return undefined;
+  return digest("caller-credential", JSON.stringify([authorization.slice(7), account]));
+}
+
+/**
+ * Whether two accepted observations describe the same owner.
+ *
+ * A proven stable user may present a refreshed credential. Without that proof on BOTH sides the
+ * only continuity evidence left is the credential itself, because a workspace id is shared by
+ * everyone in the organization and would otherwise let one member rebind another session.
+ */
+function sameOwnerIdentity(prior: ContextSessionOwner, next: ContextSessionOwner): boolean {
+  if (prior.kind !== next.kind) return false;
+  if (prior.physicalIdentity !== next.physicalIdentity) return false;
+  return prior.userIdentity !== undefined && next.userIdentity !== undefined
+    ? prior.userIdentity === next.userIdentity
+    : prior.callerCredentialIdentity === next.callerCredentialIdentity;
+}
+
+function remove(key: string): void {
+  const prior = owners.get(key);
+  if (!prior) return;
+  owners.delete(key);
+  totalBytes -= prior.bytes;
+}
+
+function sweep(now: number): void {
+  for (const [key, entry] of owners) {
+    if (now < entry.touchedAt || now - entry.touchedAt >= TTL_MS) remove(key);
+  }
+}
+
+/** Called only after a model attempt was accepted by its actual destination. */
+export function recordContextSessionOwner(
+  principalId: string | undefined, inboundHeaders: Headers, destination: string, auth: CodexAuthContext,
+  outboundHeaders: Headers, substituteMainCredential: boolean, now = Date.now(),
+): void {
+  // Ownership is partitioned per admission principal. Without one there is no caller identity to
+  // own anything, so nothing is recorded rather than creating an entry any local process matches.
+  if (!principalId || !Number.isFinite(now)) return;
+  // A malformed explicit parent must not fall back to an unrelated local session.
+  const root = inboundHeaders.get("x-codex-parent-thread-id") ?? inboundHeaders.get("session-id");
+  if (!validId(root)) return;
+  const destinationKey = destinationIdentity(destination);
+  const credential = callerCredentialIdentity(outboundHeaders);
+  if (!destinationKey || !credential) return;
+  const physical = physicalIdentity(outboundHeaders);
+  const user = stableUserIdentity(outboundHeaders);
+  if (user.conflict) {
+    // An accepted credential naming two different users is evidence of nobody. Whatever entry
+    // this session already had stops being trustworthy at that moment.
+    markContextSessionAmbiguous(principalId, root, now);
+    return;
+  }
+  let owner: ContextSessionOwner;
+  if (auth.kind !== "main" || substituteMainCredential) {
+    if (!physical) return;
+    if (auth.kind !== "main" && (!validId(auth.accountId)
+      || auth.chatgptAccountId !== outboundHeaders.get("chatgpt-account-id"))) return;
+    // Direct proxy-bearer substitution has no token snapshot in its `main` context;
+    // its accepted outbound identity is still evidence for the stored main slot.
+    owner = { kind: "stored", accountId: auth.kind === "main" ? MAIN_CODEX_ACCOUNT_ID : auth.accountId,
+      physicalIdentity: physical, ...(user.identity ? { userIdentity: user.identity } : {}),
+      callerCredentialIdentity: credential, ambiguous: false };
+  } else {
+    owner = { kind: "caller", ...(physical ? { physicalIdentity: physical } : {}),
+      ...(user.identity ? { userIdentity: user.identity } : {}),
+      callerCredentialIdentity: credential, ambiguous: false };
+  }
+  sweep(now);
+  const key = digest("root-session", `${principalId}\u0000${root}`);
+  const prior = owners.get(key);
+  if (prior) {
+    // Same workspace, different person is exactly the case a workspace id cannot see, and a
+    // credential proving nobody must not inherit an entry just by sharing that id.
+    if (prior.owner.ambiguous || prior.destination !== destinationKey
+      || !sameOwnerIdentity(prior.owner, owner)) {
+      owner = { ...prior.owner, ambiguous: true };
+    }
+  }
+  const ownerDestination = prior?.destination ?? destinationKey;
+  const bytes = Buffer.byteLength(JSON.stringify([key, ownerDestination, owner]), "utf8");
+  remove(key);
+  owners.set(key, { owner: Object.freeze(owner), destination: ownerDestination, touchedAt: now, bytes });
+  totalBytes += bytes;
+  while (owners.size > MAX_ENTRIES || totalBytes > MAX_BYTES) {
+    const oldest = owners.keys().next().value;
+    if (oldest === undefined) break;
+    remove(oldest);
+  }
+}
+
+/** Missing/expired/evicted ownership is unknown; never infer it from active routing. */
+export function getContextSessionOwner(
+  principalId: string | undefined, sessionId: string, destination: string, now = Date.now(),
+): ContextSessionOwner | undefined {
+  if (!principalId || !validId(sessionId) || !Number.isFinite(now)) return undefined;
+  const destinationKey = destinationIdentity(destination);
+  if (!destinationKey) return undefined;
+  sweep(now);
+  const key = digest("root-session", `${principalId}\u0000${sessionId}`);
+  const entry = owners.get(key);
+  if (!entry || entry.destination !== destinationKey) return undefined;
+  owners.delete(key);
+  entry.touchedAt = now;
+  owners.set(key, entry);
+  return entry.owner;
+}
+
+/** Compare only already-materialized headers; this function never reads credentials. */
+export function contextSessionOwnerMatches(owner: ContextSessionOwner, headers: Headers): boolean {
+  if (owner.ambiguous) return false;
+  const user = stableUserIdentity(headers);
+  if (user.conflict) return false;
+  if (owner.physicalIdentity !== physicalIdentity(headers)) return false;
+  if (owner.userIdentity !== user.identity) return false;
+  // A stored credential was minted by this proxy for the account it selected, so a proven user
+  // may present a refreshed token. A caller-supplied bearer is not ours: it becomes this
+  // session credential only when a model turn was accepted with it, so history has to present
+  // exactly that credential rather than any token carrying the same claims.
+  return owner.kind === "stored" && owner.userIdentity !== undefined
+    ? true
+    : owner.callerCredentialIdentity === callerCredentialIdentity(headers);
+}
+
+/** Poison an entry whose accepted evidence stopped being coherent. */
+function markContextSessionAmbiguous(principalId: string, root: string | null, now: number): void {
+  if (!validId(root)) return;
+  const key = digest("root-session", principalId + "\u0000" + root);
+  const prior = owners.get(key);
+  if (!prior || prior.owner.ambiguous) return;
+  owners.set(key, { ...prior, owner: Object.freeze({ ...prior.owner, ambiguous: true }), touchedAt: now });
+}
+
+export function clearContextSessionOwnersForTests(): void {
+  owners.clear(); totalBytes = 0;
+}
diff --git a/src/codex/history-provider.ts b/src/codex/history-provider.ts
index d7f1832e8f..1e25cf715e 100644
--- a/src/codex/history-provider.ts
+++ b/src/codex/history-provider.ts
@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, statSync, unlinkSync, writeSync } from "node:fs";
+import { closeSync, constants, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, statSync, unlinkSync, writeSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { zstdDecompressSync } from "node:zlib";
 import { Database } from "bun:sqlite";
@@ -75,14 +75,21 @@ function openStateDb(stateDbPath: string): Database {
  * rollout's updated_at), and forcing it backwards could hide a real edit from list ordering.
  */
 function appendRolloutLine(path: string, line: string): Buffer {
-  const fd = openSync(path, "a");
+  assertLegacyHistoryRecord(line);
+  // No O_CREAT: a disappeared target is not an invitation to recreate history.
+  const fd = openSync(path, constants.O_RDWR | constants.O_APPEND);
   const buf = Buffer.from(line.endsWith("\n") ? line : `${line}\n`, "utf8");
   try {
+    assertLegacyHistoryWritable(path, fd);
+    historyAppendHooks?.beforeWrite?.(path);
+    assertHistoryDescriptorIdentity(path, fd);
     let offset = 0;
     while (offset < buf.length) {
       offset += writeSync(fd, buf, offset, buf.length - offset, null);
     }
     try { fsyncSync(fd); } catch { /* best-effort durability */ }
+    historyAppendHooks?.afterWrite?.(path);
+    assertHistoryDescriptorIdentity(path, fd);
   } finally {
     closeSync(fd);
   }
@@ -186,21 +193,38 @@ function readFirstLineProviderValue(path: string, expectedId: string): string |
   }
 }
 
-function patchFirstLineProviderInPlace(path: string, expectedId: string, provider: string): FirstLineProviderResult {
-  if (!existsSync(path)) return "unsafe";
+function patchFirstLineProviderInPlace(
+  path: string, expectedId: string, provider: string,
+  expectedIdentity: { dev: number | bigint; ino: number | bigint },
+): FirstLineProviderResult {
+  historyAppendHooks?.beforeFirstLineOpen?.(path);
   const fd = openSync(path, "r+");
   try {
+    const assertIdentity = (): void => {
+      assertHistoryDescriptorIdentity(path, fd);
+      const held = fstatSync(fd);
+      if (held.dev !== expectedIdentity.dev || held.ino !== expectedIdentity.ino) {
+        throw new CodexHistoryIntegrityError("history_rollout_identity_changed");
+      }
+    };
+    assertIdentity();
+    assertLegacyHistoryWritable(path, fd);
     const firstLine = readFirstRolloutLine(fd);
     if (firstLine === null) return "unsafe";
     const plan = planFirstLineProvider(firstLine, expectedId, provider);
     if (plan.state === "unsafe") return "unsafe";
     if (plan.state === "current") return "current";
     const out = Buffer.from(plan.patchedLine, "utf8");
+    historyAppendHooks?.beforeFirstLineWrite?.(path);
+    assertIdentity();
+    assertLegacyHistoryWritable(path, fd);
     let offset = 0;
     while (offset < out.length) {
       offset += writeSync(fd, out, offset, out.length - offset, offset);
     }
     try { fsyncSync(fd); } catch { /* best-effort durability */ }
+    historyAppendHooks?.afterFirstLineWrite?.(path);
+    assertIdentity();
     return "patched";
   } finally {
     closeSync(fd);
@@ -221,6 +245,109 @@ class CodexHistoryIntegrityError extends Error {
   }
 }
 
+/** Paginated ordinals and projection offsets belong to Codex's live writer.
+ * O_APPEND does not allocate an ordinal or update that writer's in-memory cursor.
+ * Refuse before changing the DB, manifest, or first-line provider; never guess N+1.
+ */
+function assertLegacyHistoryRecord(line: string): void {
+  let value: unknown;
+  try { value = JSON.parse(line); } catch { throw new CodexHistoryIntegrityError("history_rollout_record_invalid"); }
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new CodexHistoryIntegrityError("history_rollout_record_invalid");
+  }
+  const record = value as Record<string, unknown>;
+  const payload = record.payload;
+  if (Object.hasOwn(record, "ordinal") || (payload !== null && typeof payload === "object" && (payload as Record<string, unknown>).history_mode === "paginated")) {
+    throw new CodexHistoryIntegrityError("history_paginated_requires_native_writer");
+  }
+}
+
+function assertHistoryDescriptorIdentity(path: string, fd: number): void {
+  const held = fstatSync(fd);
+  let current: ReturnType<typeof lstatSync>;
+  try { current = lstatSync(path); } catch { throw new CodexHistoryIntegrityError("history_rollout_identity_changed"); }
+  if (!current.isFile() || current.isSymbolicLink() || current.dev !== held.dev || current.ino !== held.ino) {
+    throw new CodexHistoryIntegrityError("history_rollout_identity_changed");
+  }
+}
+
+let historyAppendHooks: {
+  beforeWrite?: (path: string) => void;
+  afterWrite?: (path: string) => void;
+  beforeFirstLineOpen?: (path: string) => void;
+  beforeFirstLineWrite?: (path: string) => void;
+  afterFirstLineWrite?: (path: string) => void;
+} | undefined;
+export function setHistoryAppendHooksForTests(hooks: typeof historyAppendHooks): void { historyAppendHooks = hooks; }
+
+function assertLegacyHistoryWritable(path: string, heldFd?: number): void {
+  if (!path || !existsSync(path)) return;
+  const fd = heldFd ?? openSync(path, "r");
+  try {
+    assertHistoryDescriptorIdentity(path, fd);
+    const first = readFirstRolloutLine(fd);
+    if (!first) throw new CodexHistoryIntegrityError("history_rollout_record_invalid");
+    assertLegacyHistoryRecord(first);
+  } finally {
+    if (heldFd === undefined) closeSync(fd);
+  }
+}
+
+/** A store with history_mode can migrate legacy rows while Codex is running.
+ * Refuse the entire external mutation, not only rows already marked paginated.
+ */
+function assertLegacyHistoryStore(db: Database): void {
+  const columns = db.query<{ name: string }, []>("PRAGMA table_info(threads)").all();
+  if (columns.some(column => column.name === "history_mode")) {
+    throw new CodexHistoryIntegrityError("history_paginated_requires_native_writer");
+  }
+}
+
+/** Read-only preflight before the injector changes provider definitions.
+ * Native paginated history cannot participate in the legacy relabel protocol.
+ * Returning a refusal preserves the existing config as well as the rollout.
+ */
+export function preflightCodexHistoryInjection(
+  providerTableMode: boolean,
+  resumeHistory: boolean,
+  stateDbPath?: string,
+): string | null {
+  let db: Database | undefined;
+  try {
+    const resolvedPath = stateDbPath ?? resolveCodexStateDbPath();
+    // A partially restored row may already be native while its manifest still
+    // owns work. Match the restore worker's target set before removing routing.
+    const restoreEntries = providerTableMode ? []
+      : Object.values(readBackup(historyBackupPathFor(resolvedPath), resolvedPath).manifest.entries);
+    if (!existsSync(resolvedPath)) {
+      return restoreEntries.length > 0 ? "history_state_database_missing" : null;
+    }
+    db = new Database(resolvedPath, { readonly: true });
+    const columns = db.query<{ name: string }, []>("PRAGMA table_info(threads)").all();
+    const paginatedColumn = columns.some(column => column.name === "history_mode");
+    if (paginatedColumn && restoreEntries.length > 0) return "history_paginated_requires_native_writer";
+    for (const entry of restoreEntries) assertLegacyHistoryWritable(entry.rolloutPath);
+    const rows = db.query<{ rollout_path: string; history_mode: string | null }, []>(`
+      SELECT rollout_path, ${paginatedColumn ? "history_mode" : "NULL AS history_mode"}
+      FROM threads
+      WHERE ${providerTableMode
+        ? resumeHistory ? "model_provider IN ('openai', 'opencodex')" : "0"
+        : "model_provider = 'opencodex'"}
+    `).all();
+    for (const row of rows) {
+      if (paginatedColumn || row.history_mode === "paginated") return "history_paginated_requires_native_writer";
+      assertLegacyHistoryWritable(row.rollout_path);
+    }
+    return null;
+  } catch (error) {
+    return error instanceof CodexHistoryIntegrityError
+      ? error.message
+      : "history_injection_preflight_unavailable";
+  } finally {
+    db?.close();
+  }
+}
+
 function integrityFailureResult(error: CodexHistoryIntegrityError): CodexHistorySyncResult {
   return {
     rows: error.progress.rows,
@@ -1026,6 +1153,7 @@ function updateSessionMeta(
   } = {},
 ): SessionMetaUpdateResult {
   if (!path || !existsSync(path)) return { changed: false, durableProvider: false };
+  const validatedIdentity = lstatSync(path);
   if (options.expectedFileIdentity !== undefined
     && historyFileIdentity(path) !== options.expectedFileIdentity) {
     return { changed: false, durableProvider: false, conflict: true };
@@ -1040,6 +1168,11 @@ function updateSessionMeta(
   if (!latest) return { changed: false, durableProvider: false };
   const record = latest.record;
 
+  assertLegacyHistoryWritable(path);
+  if (Object.hasOwn(record, "ordinal") || record.payload.history_mode === "paginated") {
+    throw new CodexHistoryIntegrityError("history_paginated_requires_native_writer");
+  }
+
   const latestProvider = typeof record.payload.model_provider === "string" && record.payload.model_provider
     ? record.payload.model_provider
     : "openai";
@@ -1094,8 +1227,9 @@ function updateSessionMeta(
     let firstLine: FirstLineProviderResult = "current";
     if (patch.provider !== undefined) {
       try {
-        firstLine = patchFirstLineProviderInPlace(path, expectedId, patch.provider);
-      } catch {
+        firstLine = patchFirstLineProviderInPlace(path, expectedId, patch.provider, validatedIdentity);
+      } catch (error) {
+        if (error instanceof CodexHistoryIntegrityError) throw error;
         firstLine = "unsafe";
       }
     }
@@ -1122,8 +1256,9 @@ function updateSessionMeta(
   let firstLine: FirstLineProviderResult = "current";
   if (patch.provider !== undefined) {
     try {
-      firstLine = patchFirstLineProviderInPlace(path, expectedId, patch.provider);
-    } catch {
+      firstLine = patchFirstLineProviderInPlace(path, expectedId, patch.provider, validatedIdentity);
+    } catch (error) {
+      if (error instanceof CodexHistoryIntegrityError) throw error;
       firstLine = "unsafe";
     }
     if (options.requireDurableProvider && firstLine === "unsafe") {
@@ -1151,6 +1286,8 @@ function relabelAllRoutedHistoryToOpenai(db: Database): { rows: number; files: n
     `)
     .all();
 
+  if (rows.length > 0) assertLegacyHistoryStore(db);
+  for (const row of rows) assertLegacyHistoryWritable(row.rollout_path);
   let files = 0;
   for (const row of rows) {
     try {
@@ -1158,8 +1295,8 @@ function relabelAllRoutedHistoryToOpenai(db: Database): { rows: number; files: n
         provider: "openai",
         source: row.source === "exec" ? "cli" : undefined,
       }).changed) files++;
-    } catch {
-      /* explicit legacy recovery still relabels the DB when an old rollout is missing */
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException)?.code !== "ENOENT") throw error;
     }
   }
 
@@ -1302,6 +1439,8 @@ function syncCodexHistoryProviderUnsafe(provider: CodexHistoryProvider, stateDbP
       `)
       .all();
 
+    if (openaiRows.length + execRows.length > 0) assertLegacyHistoryStore(db);
+    for (const row of [...openaiRows, ...execRows]) assertLegacyHistoryWritable(row.rollout_path);
     const manifest = readBackup(backupPath, stateDbPath).manifest;
     for (const row of [...openaiRows, ...execRows]) rememberOriginal(manifest, row);
     writeBackup(backupPath, manifest, stateDbPath);
@@ -1367,15 +1506,15 @@ function syncCodexHistoryProviderUnsafe(provider: CodexHistoryProvider, stateDbP
       for (const row of openaiRows) {
         try {
           if (updateSessionMeta(row.rollout_path, row.id, { provider: "opencodex" }).changed) files++;
-        } catch {
-          /* keep DB migration moving; the manifest still carries exact original metadata */
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException)?.code !== "ENOENT") throw error;
         }
       }
       for (const row of execRows) {
         try {
           if (updateSessionMeta(row.rollout_path, row.id, { source: "cli" }).changed) files++;
-        } catch {
-          /* keep DB migration moving; the manifest still carries exact original metadata */
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException)?.code !== "ENOENT") throw error;
         }
       }
     });
@@ -1409,9 +1548,12 @@ function restoreCodexHistoryProvider(stateDbPath: string, backupPath: string): C
   const manifest = backup.manifest;
   const entries = Object.values(manifest.entries);
 
+  for (const entry of entries) assertLegacyHistoryWritable(entry.rolloutPath);
+
   const db = openStateDb(stateDbPath);
   try {
     if (entries.length === 0) return { rows: 0, files: 0 };
+    assertLegacyHistoryStore(db);
 
     // Validate the whole manifest-to-database target set before touching a rollout. Only the
     // OpenCodex post-image (or an already-restored target from an interrupted retry) is owned by
@@ -1547,6 +1689,7 @@ function restoreCodexHistoryProvider(stateDbPath: string, backupPath: string): C
 
 export function restoreLegacyOpenaiHistory(stateDbPath = resolveCodexStateDbPath()): CodexHistorySyncResult {
   if (!existsSync(stateDbPath)) return { rows: 0, files: 0 };
+  try {
   const retried = withHistoryRetryResult(() => {
     const db = openStateDb(stateDbPath);
     try {
@@ -1556,6 +1699,10 @@ export function restoreLegacyOpenaiHistory(stateDbPath = resolveCodexStateDbPath
     }
   });
   return retried.ok ? retried.value : { rows: 0, files: 0, failed: true, failureReason: retried.reason };
+  } catch (error) {
+    if (error instanceof CodexHistoryIntegrityError) return integrityFailureResult(error);
+    throw error;
+  }
 }
 
 /**
diff --git a/src/codex/inject-coordination.ts b/src/codex/inject-coordination.ts
index 55be8b81a1..85b1e9b662 100644
--- a/src/codex/inject-coordination.ts
+++ b/src/codex/inject-coordination.ts
@@ -172,8 +172,9 @@ export interface CodexPreImages {
 function readOrNull(path: string): string | null {
   try {
     return readFileSync(path, "utf-8");
-  } catch {
-    return null;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
   }
 }
 
diff --git a/src/codex/inject.ts b/src/codex/inject.ts
index 12ae087ac4..31893a3867 100644
--- a/src/codex/inject.ts
+++ b/src/codex/inject.ts
@@ -1,3 +1,4 @@
+import { contextCompatibleBaseLine } from "./context-compat";
 import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import {
   atomicWriteFile,
@@ -46,7 +47,7 @@ import {
 } from "./journal";
 import { withCatalogWriteSerialization } from "./catalog-write-serialization";
 import { restoreCodexCatalogWithPermit } from "./catalog/sync";
-import { syncCodexHistoryProvider, type CodexHistoryFailureReason } from "./history-provider";
+import { preflightCodexHistoryInjection, syncCodexHistoryProvider, type CodexHistoryFailureReason } from "./history-provider";
 import {
   describeHistoryJobFailure,
   deriveCodexHistoryOperation,
@@ -75,6 +76,7 @@ import {
   parseTomlString,
   readRootTomlString,
   resolveCodexConfigPath,
+  resolveCodexStateDbPath,
   tomlString,
 } from "./paths";
 import { resolveEffectiveProjectModelProvider } from "./project-config-warnings";
@@ -395,7 +397,7 @@ export function setRootOpenaiBaseUrl(
   const lines = content.split("\n");
   const firstTable = lines.findIndex((l) => /^\s*\[/.test(l));
   const rootEnd = firstTable === -1 ? lines.length : firstTable;
-  const key = buildOpenaiBaseUrlLine(portOrTarget, hostname);
+  const key = contextCompatibleBaseLine(content, buildOpenaiBaseUrlLine(portOrTarget, hostname));
 
   for (let i = 0; i < rootEnd; i++) {
     if (!isRootOpenaiBaseUrlLine(lines[i])) continue;
@@ -430,7 +432,7 @@ function setRootOpenaiBaseUrlForTarget(
   const lines = content.split("\n");
   const firstTable = lines.findIndex((line) => /^\s*\[/.test(line));
   const rootEnd = firstTable === -1 ? lines.length : firstTable;
-  const key = buildOpenaiBaseUrlLineForTarget(target);
+  const key = contextCompatibleBaseLine(content, buildOpenaiBaseUrlLineForTarget(target));
   for (let index = 0; index < rootEnd; index += 1) {
     if (!isRootOpenaiBaseUrlLine(lines[index])) continue;
     const markerOwned = index > 0 && lines[index - 1].includes(OCX_SECTION_MARKER);
@@ -899,10 +901,41 @@ export interface CodexInjectResult {
   nativeSubagentDefaultsWarning?: string;
 }
 
+class CodexHistoryPreflightRefusal extends Error {}
+class CodexRestoreRefusal extends Error {
+  constructor(readonly config: CodexRestoreConfigResult) {
+    super(config.message);
+  }
+}
+let historyArtifactStageForTests: ((stage: string) => void) | undefined;
+export function setHistoryArtifactStageForTests(hook: typeof historyArtifactStageForTests): void {
+  historyArtifactStageForTests = hook;
+}
+let beforeRestoreConfigForTests: ((kind: string) => void) | undefined;
+export function setBeforeRestoreConfigForTests(hook: typeof beforeRestoreConfigForTests): void {
+  beforeRestoreConfigForTests = hook;
+}
+let beforeHistoryArtifactCommitForTests: ((kind: string) => void) | undefined;
+export function setBeforeHistoryArtifactCommitForTests(hook: typeof beforeHistoryArtifactCommitForTests): void {
+  beforeHistoryArtifactCommitForTests = hook;
+}
+
 export async function injectCodexConfig(
   port: number,
   config?: OcxConfig,
   options: InjectCodexOptions = {},
+): Promise<CodexInjectResult> {
+  try { return await injectCodexConfigImpl(port, config, options); }
+  catch (error) {
+    if (error instanceof CodexHistoryPreflightRefusal) return { success: false, message: `Codex config injection refused: ${error.message}. Existing configuration and history were preserved.` };
+    throw error;
+  }
+}
+
+async function injectCodexConfigImpl(
+  port: number,
+  config?: OcxConfig,
+  options: InjectCodexOptions = {},
 ): Promise<CodexInjectResult> {
   // Point Codex at the unauthenticated loopback listener when it is enabled (#1102).
   //
@@ -929,6 +962,10 @@ export async function injectCodexConfig(
   }
 
   const rawContent = readFileSync(CODEX_CONFIG_PATH, "utf-8");
+  const preflightTableMode = usesProviderTable(routingTarget);
+  const compactionOnly = routingTarget.clientCompaction === true
+    && routingTarget.desktopAuthless !== true
+    && routingTarget.requiresAdmissionToken !== true;
   const activeProvider = externalCodexModelProvider(rawContent);
   if (activeProvider) {
     // A launcher may have journaled before the provider manager took ownership. Never let shutdown
@@ -1138,6 +1175,29 @@ export async function injectCodexConfig(
   );
   content = applyEol(content, eol);
 
+  // Resolve storage from the normalized candidate. Owned duplicate catalog keys
+  // are repairable above and must not make this read-only preflight throw.
+  const historyPreflight = (): string | null => {
+    try {
+      return preflightCodexHistoryInjection(
+        preflightTableMode,
+        config?.syncResumeHistory !== false && !compactionOnly,
+        resolveCodexStateDbPath({ readConfig: () => content }),
+      );
+    } catch {
+      return "history_injection_preflight_unavailable";
+    }
+  };
+  const historyPreflightError = historyPreflight();
+  if (historyPreflightError) {
+    return {
+      success: false,
+      message: `Codex config injection refused: ${historyPreflightError}. `
+        + "Existing provider definitions and conversation files were preserved. "
+        + "Paginated history requires native-writer coordination; do not run legacy recovery or retry this transition blindly.",
+    };
+  }
+
   /*
    * The witness, built from the FINAL bytes. Everything it hashes is either the
    * output about to be written or evidence that can be re-read under the lock;
@@ -1228,6 +1288,12 @@ export async function injectCodexConfig(
   }
 
   const applyNativeArtifacts = (): void => {
+    beforeHistoryArtifactCommitForTests?.(eligibility.kind);
+    const historyError = historyPreflight();
+    if (historyError) throw new CodexHistoryPreflightRefusal(historyError);
+    const preImages = captureCodexPreImages();
+    try {
+    historyArtifactStageForTests?.("after-preflight");
     writeJournal({
       currentStateIsNative: journalBaselineIsNative(),
       configContent: baselineContent,
@@ -1237,6 +1303,7 @@ export async function injectCodexConfig(
     // must not gain the new injection's hash and later overwrite preserved user edits.
     if (hasUnverifiedJournalBaseline(baselineContent, readCurrentProfile())) throw new Error(unverifiedJournalMessage);
     atomicWriteFile(CODEX_CONFIG_PATH, content);
+    historyArtifactStageForTests?.("after-config");
     atomicWriteFile(CODEX_PROFILE_PATH, profileContent);
     markJournalInjectedState(content, profileContent, {
       // A root override is ours whenever we wrote one and no user-owned value won. That is
@@ -1257,6 +1324,16 @@ export async function injectCodexConfig(
       // already points at that path and therefore needs no textual rewrite.
       injectedCatalogPath: catalogPath,
     });
+    historyArtifactStageForTests?.("after-artifacts");
+    // Detect migration throughout the artifact transaction, not just at entry.
+    // This is compensation, not a native-writer lock or permission to append ordinals.
+    const finalHistoryError = historyPreflight();
+    if (finalHistoryError) throw new CodexHistoryPreflightRefusal(finalHistoryError);
+    } catch (error) {
+      const compensated = restoreCodexPreImages(preImages);
+      if (!compensated.complete) throw new CodexPartialWriteError(compensated.unrestored);
+      throw error;
+    }
   };
 
   /*
@@ -1638,6 +1715,8 @@ function hasOpencodexRouting(content: string): boolean {
 export function removeCodexConfig(
   options: { preserveProfile?: boolean } = {},
 ): { success: boolean; message: string } {
+  const historyError = preflightCodexHistoryInjection(false, false);
+  if (historyError) return { success: false, message: `Codex configuration preserved: ${historyError}. Native writer coordination is required.` };
   if (!existsSync(CODEX_CONFIG_PATH)) {
     if (!options.preserveProfile && existsSync(CODEX_PROFILE_PATH))
       unlinkSync(CODEX_PROFILE_PATH);
@@ -1837,9 +1916,29 @@ export function skippedRestoreEnvelope(success: boolean, message: string): Codex
   };
 }
 
+/** Config was attempted and failed; downstream artifacts were never attempted. */
+function failedConfigRestoreEnvelope(config: CodexRestoreConfigResult): CodexNativeRestoreResult {
+  const result = skippedRestoreEnvelope(false, config.message);
+  result.artifacts.config = config;
+  return result;
+}
+
 /** The config/profile half of a native restore, reported as one artifact. */
-function restoreCodexConfigInline(): CodexRestoreConfigResult {
+function restoreCodexConfigInline(kind = "sync"): CodexRestoreConfigResult {
+  const preImages = captureCodexPreImages();
+  const result = restoreCodexConfigInlineImpl(kind);
+  if (result.state === "failed") {
+    const compensated = restoreCodexPreImages(preImages);
+    if (!compensated.complete) throw new CodexPartialWriteError(compensated.unrestored);
+  }
+  return result;
+}
+
+function restoreCodexConfigInlineImpl(kind: string): CodexRestoreConfigResult {
   try {
+    beforeRestoreConfigForTests?.(kind);
+    const historyError = preflightCodexHistoryInjection(false, false);
+    if (historyError) return { state: "failed", changed: false, action: "failed", message: `Codex configuration and journal preserved: ${historyError}.` };
     const journal = restoreJournalState();
     if (journal.unverified) {
       return {
@@ -1912,6 +2011,17 @@ function restoreCodexCatalogArtifact(
  */
 export async function restoreNativeCodexAsync(
   options: { revalidateDesiredState?: boolean } = {},
+): Promise<CodexNativeRestoreResult> {
+  try {
+    return await restoreNativeCodexAsyncImpl(options);
+  } catch (error) {
+    if (!(error instanceof CodexRestoreRefusal)) throw error;
+    return failedConfigRestoreEnvelope(error.config);
+  }
+}
+
+async function restoreNativeCodexAsyncImpl(
+  options: { revalidateDesiredState?: boolean },
 ): Promise<CodexNativeRestoreResult> {
   const activeProvider = currentExternalCodexModelProvider();
   if (activeProvider) {
@@ -1929,8 +2039,12 @@ export async function restoreNativeCodexAsync(
   if (options.revalidateDesiredState) {
     const ownership = inspectNativeCodexOwnership();
     if (ownership.ownership === "foreign") return foreignOwnershipRestoreRefusal(ownership.reason);
+    if (shouldSyncCodexOnStart(loadConfig())) return desiredEnabledRestoreSkip();
   }
 
+  const historyError = preflightCodexHistoryInjection(false, false);
+  if (historyError) return skippedRestoreEnvelope(false, `Native restore refused: ${historyError}. Config, catalog, history and provenance were preserved.`);
+
   const eligibility = codexWriteCoordinationEligibility({
     coordinatorPath: () =>
       resolveCodexCoordinatorDatabasePath(resolveEffectiveUserIdentity(), getCodexHome()),
@@ -1980,7 +2094,9 @@ export async function restoreNativeCodexAsync(
         const preImages = captureCodexPreImages();
         let restored: CodexRestoreConfigResult;
         try {
-          restored = restoreCodexConfigInline();
+          restored = restoreCodexConfigInline(eligibility.kind);
+          // Throw inside N so the published remove transition rolls back too.
+          if (restored.state === "failed") throw new CodexRestoreRefusal(restored);
         } catch (error) {
           const compensated = restoreCodexPreImages(preImages);
           if (!compensated.complete) throw new CodexPartialWriteError(compensated.unrestored);
@@ -2021,9 +2137,10 @@ export async function restoreNativeCodexAsync(
     if (options.revalidateDesiredState && shouldSyncCodexOnStart(loadConfig())) {
       return desiredEnabledRestoreSkip();
     }
-    config = restoreCodexConfigInline();
+    config = restoreCodexConfigInline(eligibility.kind);
   }
 
+  if (config.state === "failed") return failedConfigRestoreEnvelope(config);
   const catalog = restoreCodexCatalogArtifact(options.revalidateDesiredState === true, journaledCatalogPath);
   const outcome = await runCodexHistoryJob({
     ...resolveCodexHistoryJobTarget(),
@@ -2055,8 +2172,7 @@ export async function restoreNativeCodexAsync(
   const base = catalog.removed > 0
     ? `${config.message} Catalog restored to ${catalog.kept} native model(s) (dropped ${catalog.removed} proxy-routed).`
     : config.message;
-  const success = config.state !== "failed"
-    && catalog.state !== "failed"
+  const success = catalog.state !== "failed"
     && history.state !== "failed";
   return {
     success,
@@ -2074,11 +2190,14 @@ export function restoreNativeCodex(options: { skipHistory?: boolean; revalidateD
   if (options.revalidateDesiredState && shouldSyncCodexOnStart(loadConfig())) {
     return desiredEnabledRestoreSkip();
   }
+  const historyError = preflightCodexHistoryInjection(false, false);
+  if (historyError) return skippedRestoreEnvelope(false, `Native restore refused: ${historyError}. Config, catalog, history and provenance were preserved.`);
   // Captured before the config half: a successful journal restore DELETES the journal, and
   // restoring the config can drop `model_catalog_json`. Either one would hide the routed
   // catalog we actually wrote (#1798).
   const journaledCatalogPath = journaledInjectedCatalogPath();
   const config = restoreCodexConfigInline();
+  if (config.state === "failed") return failedConfigRestoreEnvelope(config);
   const catalog = restoreCodexCatalogArtifact(options.revalidateDesiredState === true, journaledCatalogPath);
   // Design B (loopback) steady state: threads are already tagged openai, so prove the
   // no-op with a readonly probe instead of write-opening a DB the Codex app may hold
@@ -2115,7 +2234,7 @@ export function restoreNativeCodex(options: { skipHistory?: boolean; revalidateD
     ? `${config.message} Catalog restored to ${catalog.kept} native model(s) (dropped ${catalog.removed} proxy-routed).`
     : config.message;
   return {
-    success: config.state !== "failed" && catalog.state !== "failed" && history.state !== "failed",
+    success: catalog.state !== "failed" && history.state !== "failed",
     message,
     artifacts: { config, catalog, history },
   };
diff --git a/src/codex/pool-rotation.ts b/src/codex/pool-rotation.ts
index d0d032be06..09936dc8c2 100644
--- a/src/codex/pool-rotation.ts
+++ b/src/codex/pool-rotation.ts
@@ -1,295 +1,11 @@
-import type { OcxAccountPoolRotationStrategy } from "../types";
-import type { GenerationContext } from "../lib/state-store-sweeper";
-
-export const POOL_KEY_CODEX = "codex";
-export const POOL_KEY_ANTHROPIC = "anthropic";
-
-interface SelectionState {
-  activeKey?: string;
-  successes: number;
-  currentWeights: Map<string, number>;
-}
-
-const selectionState = new Map<string, SelectionState>();
-let lastReconciledGeneration = 0;
-
-const DEFAULT_STICKY_LIMIT = 1;
-const MIN_STICKY_LIMIT = 1;
-const MAX_STICKY_LIMIT = 100;
-const DEFAULT_STRATEGY: OcxAccountPoolRotationStrategy = "quota";
-const VALID_STRATEGIES = new Set<OcxAccountPoolRotationStrategy>(["quota", "round-robin", "fill-first"]);
-
-/** Selection order for an account with no stored preference: one flat tier. */
-export const DEFAULT_ACCOUNT_PRIORITY = 0;
-export const MIN_ACCOUNT_PRIORITY = -100;
-export const MAX_ACCOUNT_PRIORITY = 100;
-
-/** Strict parse for management APIs — returns null instead of defaulting. */
-export function parseAccountPoolStrategy(raw: unknown): OcxAccountPoolRotationStrategy | null {
-  if (typeof raw === "string" && VALID_STRATEGIES.has(raw as OcxAccountPoolRotationStrategy)) {
-    return raw as OcxAccountPoolRotationStrategy;
-  }
-  return null;
-}
-
-/** Strict parse for management APIs — returns null instead of defaulting. */
-export function parseAccountPoolStickyLimit(raw: unknown): number | null {
-  if (typeof raw === "number" && Number.isInteger(raw) && raw >= MIN_STICKY_LIMIT && raw <= MAX_STICKY_LIMIT) {
-    return raw;
-  }
-  return null;
-}
-
-export function normalizeAccountPoolStrategy(raw: unknown): OcxAccountPoolRotationStrategy {
-  return parseAccountPoolStrategy(raw) ?? DEFAULT_STRATEGY;
-}
-
-export function normalizeAccountPoolStickyLimit(raw: unknown): number {
-  return parseAccountPoolStickyLimit(raw) ?? DEFAULT_STICKY_LIMIT;
-}
-
-/** Strict parse for management APIs — returns null instead of defaulting. */
-export function parseAccountPriority(raw: unknown): number | null {
-  if (
-    typeof raw === "number"
-    && Number.isInteger(raw)
-    && raw >= MIN_ACCOUNT_PRIORITY
-    && raw <= MAX_ACCOUNT_PRIORITY
-  ) {
-    return raw;
-  }
-  return null;
-}
-
-export function normalizeAccountPriority(raw: unknown): number {
-  return parseAccountPriority(raw) ?? DEFAULT_ACCOUNT_PRIORITY;
-}
-
 /**
- * Narrow an already-eligible account list to the highest selection-order tier that
- * still has usable quota. Priority is an *ordering* boundary layered on top of
- * eligibility: it never admits an account the caller already filtered out, and it
- * never keeps the pool on a tier whose every member is drained.
+ * Compatibility shim. The rotation primitives moved to `src/oauth/pool-kernel.ts`
+ * so every credential kind can share them, not only Codex and Anthropic.
  *
- * Contract (each clause is load-bearing for "no behavior change when unconfigured"):
- * - one distinct priority across `ids` (the unconfigured case) returns `ids` unchanged,
- *   so today's pick sequence is preserved byte for byte;
- * - input order is preserved inside the returned tier, which keeps the `__main__`
- *   head-of-list bias and the first-index tie-break used by SWRR/lowest-usage;
- * - every tier drained returns `ids` unchanged, reproducing today's
- *   stay-put-until-429 behavior rather than inventing a pick;
- * - a `pinnedId` that is present *and* has headroom lowers the ceiling to its own
- *   tier, which is what makes a manual "use this now" survive round-robin and
- *   fill-first without any mutable selection state. A drained or absent pin is
- *   ignored, so the pin expires on its own once the account crosses the threshold.
+ * This file stays because the move is behaviour-preserving and its importers are
+ * spread across files that other work owns right now. Re-exporting keeps
+ * `routing.ts`, `auth-api.ts`, `account-priority.ts` and
+ * `state-store-registrations.ts` on their existing import path, so the extraction
+ * lands without editing any of them.
  */
-export function selectPriorityTier(
-  ids: readonly string[],
-  priorityOf: (id: string) => number,
-  hasHeadroom: (id: string) => boolean,
-  pinnedId?: string,
-): readonly string[] {
-  // Readonly out as well as in: the no-change cases return the caller's own array, so a
-  // mutating caller would corrupt its input in exactly the cases that must not change.
-  const list = ids;
-  if (list.length <= 1) return list;
-
-  const priorities = list.map(priorityOf);
-  const firstPriority = priorities[0]!;
-  if (priorities.every(priority => priority === firstPriority)) return list;
-
-  let ceiling = Number.POSITIVE_INFINITY;
-  if (pinnedId !== undefined) {
-    const pinnedIndex = list.indexOf(pinnedId);
-    if (pinnedIndex >= 0 && hasHeadroom(pinnedId)) ceiling = priorities[pinnedIndex]!;
-  }
-
-  const tiers = [...new Set(priorities)].sort((a, b) => b - a);
-  for (const tier of tiers) {
-    if (tier > ceiling) continue;
-    const members = list.filter((_, index) => priorities[index] === tier);
-    if (members.some(hasHeadroom)) return members;
-  }
-  return list;
-}
-
-function getOrCreateState(poolKey: string): SelectionState {
-  let state = selectionState.get(poolKey);
-  if (!state) {
-    state = { successes: 0, currentWeights: new Map() };
-    selectionState.set(poolKey, state);
-  }
-  return state;
-}
-
-function cloneSelectionState(state: SelectionState): SelectionState {
-  return {
-    activeKey: state.activeKey,
-    successes: state.successes,
-    currentWeights: new Map(state.currentWeights),
-  };
-}
-
-function smoothWeightedIndex(ids: readonly string[], state: SelectionState): number {
-  let best = -1;
-  let bestScore = Number.NEGATIVE_INFINITY;
-  let total = 0;
-  const weight = 1;
-  for (let i = 0; i < ids.length; i++) {
-    const id = ids[i]!;
-    const score = (state.currentWeights.get(id) ?? 0) + weight;
-    state.currentWeights.set(id, score);
-    total += weight;
-    if (score > bestScore) {
-      best = i;
-      bestScore = score;
-    }
-  }
-  if (best >= 0) {
-    const key = ids[best]!;
-    state.currentWeights.set(key, (state.currentWeights.get(key) ?? 0) - total);
-  }
-  return best;
-}
-
-/**
- * Shared pick core. Mutates `state` the same way live resolve does; callers pass
- * either the live map entry or a scratch/clone for dry-run peek.
- */
-function pickRoundRobinFromState(
-  eligibleIds: readonly string[],
-  stickyLimit: number,
-  state: SelectionState,
-  commitSticky: boolean,
-): string | null {
-  if (eligibleIds.length === 0) return null;
-
-  const limit = normalizeAccountPoolStickyLimit(stickyLimit);
-
-  if (state.activeKey && eligibleIds.includes(state.activeKey)) {
-    return state.activeKey;
-  }
-
-  if (state.activeKey) {
-    delete state.activeKey;
-    state.successes = 0;
-  }
-
-  const index = smoothWeightedIndex(eligibleIds, state);
-  if (index < 0) return null;
-
-  const picked = eligibleIds[index]!;
-  if (commitSticky && limit > 1) {
-    state.activeKey = picked;
-    state.successes = 0;
-  }
-  return picked;
-}
-
-export function pickRoundRobinAccount(
-  poolKey: string,
-  eligibleIds: readonly string[],
-  stickyLimit: number,
-): string | null {
-  return pickRoundRobinFromState(eligibleIds, stickyLimit, getOrCreateState(poolKey), true);
-}
-
-/**
- * Dry-run of {@link pickRoundRobinAccount}: returns the same account resolve would
- * pick without advancing ring weights, activeKey, or successes.
- */
-export function peekRoundRobinAccount(
-  poolKey: string,
-  eligibleIds: readonly string[],
-  stickyLimit: number,
-): string | null {
-  const live = selectionState.get(poolKey);
-  const scratch = live
-    ? cloneSelectionState(live)
-    : { successes: 0, currentWeights: new Map<string, number>() };
-  return pickRoundRobinFromState(eligibleIds, stickyLimit, scratch, false);
-}
-
-export function notePoolRotationSuccess(
-  poolKey: string,
-  accountId: string,
-  stickyLimit: number,
-): void {
-  const limit = normalizeAccountPoolStickyLimit(stickyLimit);
-  const state = selectionState.get(poolKey);
-  if (!state) return;
-  if (state.activeKey !== accountId) {
-    state.activeKey = accountId;
-    state.successes = 0;
-  }
-  state.successes += 1;
-  if (state.successes >= limit) {
-    delete state.activeKey;
-    state.successes = 0;
-  }
-}
-
-export function notePoolRotationFailure(poolKey: string, accountId: string): void {
-  const state = selectionState.get(poolKey);
-  if (state?.activeKey === accountId) {
-    delete state.activeKey;
-    state.successes = 0;
-  }
-}
-
-/**
- * Force the next sticky/RR pick onto `accountId` (manual dashboard selection).
- * Clears sticky success counters and ring weights so the seeded account is held
- * for the next new-session pick before ordinary rotation resumes.
- */
-export function seedPoolRotationAccount(poolKey: string, accountId: string): void {
-  const state = getOrCreateState(poolKey);
-  state.activeKey = accountId;
-  state.successes = 0;
-  state.currentWeights.clear();
-}
-
-export function clearPoolRotationState(poolKey?: string): void {
-  if (poolKey === undefined) {
-    selectionState.clear();
-    return;
-  }
-  selectionState.delete(poolKey);
-}
-
-export function reconcilePoolRotationState(context: GenerationContext): number {
-  if (context.generation <= lastReconciledGeneration) return 0;
-  const anthropicIds = new Set<string>();
-  for (const key of context.oauthAccountKeys) {
-    const separator = key.indexOf("\0");
-    if (separator > 0 && key.slice(0, separator) === "anthropic") {
-      anthropicIds.add(key.slice(separator + 1));
-    }
-  }
-  let removed = 0;
-  for (const [poolKey, state] of selectionState) {
-    const valid = poolKey === POOL_KEY_ANTHROPIC
-      ? anthropicIds
-      : poolKey === POOL_KEY_CODEX || poolKey.startsWith(`${POOL_KEY_CODEX}:`)
-        ? context.codexAccountIds
-        : null;
-    if (!valid) continue;
-    if (valid.size === 0) {
-      selectionState.delete(poolKey);
-      removed += 1;
-      continue;
-    }
-    if (state.activeKey && !valid.has(state.activeKey)) {
-      delete state.activeKey;
-      state.successes = 0;
-      removed += 1;
-    }
-    for (const accountId of state.currentWeights.keys()) {
-      if (valid.has(accountId)) continue;
-      state.currentWeights.delete(accountId);
-      removed += 1;
-    }
-  }
-  lastReconciledGeneration = context.generation;
-  return removed;
-}
+export * from "../oauth/pool-kernel";
diff --git a/src/codex/quota.ts b/src/codex/quota.ts
index 05a41e1295..1a6260636c 100644
--- a/src/codex/quota.ts
+++ b/src/codex/quota.ts
@@ -44,6 +44,21 @@ const MONTHLY_WINDOW_MIN_MINUTES = MONTHLY_WINDOW_MIN_SECONDS / 60;
 // Derived, never written as a literal: the header parser and the WHAM parser must not be able
 // to drift to different thresholds, which is the class of defect this pair exists to prevent.
 const WEEKLY_WINDOW_MIN_MINUTES = WEEKLY_WINDOW_MIN_SECONDS / 60;
+/**
+ * Seconds/milliseconds split for a stored reset instant: below it the value is Unix seconds,
+ * at or above it milliseconds.
+ *
+ * Both units reach storage — `normalizeResetAt` does not scale, and the GUI disambiguates by
+ * magnitude at read time — so a comparison written against one assumption is off by 1000x
+ * against the other. In the seconds-read-as-milliseconds direction every reading looks like it
+ * elapsed in 1970, which is a check that passes its own test and does nothing. Exported so
+ * `isTerminalShortWindow` in routing.ts shares this one split instead of repeating the literal.
+ */
+const RESET_AT_SECONDS_MAX = 10_000_000_000;
+
+export function resetAtToMs(resetAt: number): number {
+  return resetAt < RESET_AT_SECONDS_MAX ? resetAt * 1000 : resetAt;
+}
 
 const accountQuota = new Map<string, StoredAccountQuota>();
 let lastReconciledGeneration = 0;
@@ -221,6 +236,25 @@ function snapshotHasShort(quota: Omit<StoredAccountQuota, "updatedAt">): boolean
     || quota.shortWindowSeconds !== undefined;
 }
 
+function shortResetHasElapsed(resetAt: number | undefined, now: number): boolean {
+  if (typeof resetAt !== "number" || !Number.isFinite(resetAt) || resetAt <= 0) return false;
+  return resetAtToMs(resetAt) <= now;
+}
+
+/** Display/rotation carry expires; a reset clock cannot retract hard-lock evidence. */
+function assignCarriedShort(
+  next: StoredAccountQuota,
+  existing: StoredAccountQuota | undefined,
+  now: number,
+  policyEvidence = false,
+): void {
+  if (!existing || (!policyEvidence && shortResetHasElapsed(existing.shortResetAt, now))) return;
+  if (existing.shortPercent !== undefined) next.shortPercent = existing.shortPercent;
+  if (existing.shortObservedAt !== undefined) next.shortObservedAt = existing.shortObservedAt;
+  if (existing.shortResetAt !== undefined) next.shortResetAt = existing.shortResetAt;
+  if (existing.shortWindowSeconds !== undefined) next.shortWindowSeconds = existing.shortWindowSeconds;
+}
+
 function snapshotHasCustom(quota: Omit<StoredAccountQuota, "updatedAt">): boolean {
   return quota.customWindows !== undefined;
 }
@@ -282,10 +316,7 @@ function mergeAccountQuota(
     if (existing?.monthlyPercent !== undefined) next.monthlyPercent = existing.monthlyPercent;
     if (existing?.monthlyResetAt !== undefined) next.monthlyResetAt = existing.monthlyResetAt;
     if (existing?.monthlyIsPrimaryWindow === true) next.monthlyIsPrimaryWindow = true;
-    if (existing?.shortPercent !== undefined) next.shortPercent = existing.shortPercent;
-    if (existing?.shortObservedAt !== undefined) next.shortObservedAt = existing.shortObservedAt;
-    if (existing?.shortResetAt !== undefined) next.shortResetAt = existing.shortResetAt;
-    if (existing?.shortWindowSeconds !== undefined) next.shortWindowSeconds = existing.shortWindowSeconds;
+    assignCarriedShort(next, existing, updatedAt, policyEvidence);
     if (existing?.customWindows !== undefined) next.customWindows = existing.customWindows;
     next.resetCredits = quota.resetCredits;
     return next;
@@ -329,10 +360,10 @@ function mergeAccountQuota(
   } else {
     // Unknown usage is not a lower reading. Retain the entire known tuple: pairing
     // its percentage with new metadata would silently extend or shorten its reset.
-    if (existing?.shortPercent !== undefined) next.shortPercent = existing.shortPercent;
-    if (existing?.shortObservedAt !== undefined) next.shortObservedAt = existing.shortObservedAt;
-    if (existing?.shortResetAt !== undefined) next.shortResetAt = existing.shortResetAt;
-    if (existing?.shortWindowSeconds !== undefined) next.shortWindowSeconds = existing.shortWindowSeconds;
+    // An elapsed reset is the exception. It describes a window that has already rolled over,
+    // and carrying it republishes updatedAt, which is exactly what kept a Spark-polluted Pro
+    // row alive past the six-hour disk TTL that #4122 expected to expire it.
+    assignCarriedShort(next, existing, updatedAt, policyEvidence);
   }
 
   if (snapshotHasCustom(quota)) next.customWindows = quota.customWindows;
@@ -394,6 +425,7 @@ function notifyCodexQuotaSnapshot(accountId: string, next: StoredAccountQuota):
         scope: "codex",
         accountKey: accountId,
         windows: codexWindowObservations(snapshot),
+        retainAbsentShortWindow: true,
       });
     })
     .catch(() => {
@@ -561,14 +593,11 @@ export function updateAccountQuota(
       : {}),
     ...(existing?.weeklyResetAt !== undefined ? { weeklyResetAt: existing.weeklyResetAt } : {}),
     ...(existing?.monthlyResetAt !== undefined ? { monthlyResetAt: existing.monthlyResetAt } : {}),
-    ...(existing?.shortPercent !== undefined ? { shortPercent: existing.shortPercent } : {}),
-    ...(existing?.shortObservedAt !== undefined ? { shortObservedAt: existing.shortObservedAt } : {}),
-    ...(existing?.shortResetAt !== undefined ? { shortResetAt: existing.shortResetAt } : {}),
-    ...(existing?.shortWindowSeconds !== undefined ? { shortWindowSeconds: existing.shortWindowSeconds } : {}),
     ...(existing?.customWindows !== undefined ? { customWindows: existing.customWindows } : {}),
     ...(existing?.resetCredits !== undefined ? { resetCredits: existing.resetCredits } : {}),
     updatedAt: Date.now(),
   };
+  assignCarriedShort(quota, existing, quota.updatedAt);
 
   const nextWeeklyResetAt = normalizeResetAt(weeklyResetAt);
   const nextMonthlyResetAt = normalizeResetAt(monthlyResetAt);
diff --git a/src/codex/retired-model-migration.ts b/src/codex/retired-model-migration.ts
new file mode 100644
index 0000000000..deffe05cba
--- /dev/null
+++ b/src/codex/retired-model-migration.ts
@@ -0,0 +1,41 @@
+/**
+ * One-time migration off Codex-login models that upstream has retired.
+ *
+ * Originally this only moved the two sidecar defaults, and it was written when
+ * `gpt-5.4-mini` was merely superseded rather than withdrawn. Once OpenAI retired the
+ * model the same stored value stopped being a stale preference and became a guaranteed
+ * 404 on every web-search, vision and pool-warmup call, so the pool warmup slug joined
+ * the set.
+ *
+ * The match is exact equality, which means an explicitly chosen `gpt-5.4-mini` is
+ * rewritten too. That is deliberate: there is no configuration in which continuing to
+ * send a withdrawn model is what the operator wanted. Any other value is left alone.
+ */
+import type { OcxConfig } from "../types";
+
+/** July 9 21:00 UTC = KST July 10 06:00. */
+export const RETIRED_MODEL_MIGRATION_CUTOFF = Date.UTC(2026, 6, 9, 21, 0);
+
+const RETIRED_SIDECAR_MODEL = "gpt-5.4-mini";
+const REPLACEMENT_MODEL = "gpt-5.6-luna";
+
+/**
+ * @returns true when the config changed and the caller should persist it.
+ */
+export function runRetiredCodexModelMigration(config: OcxConfig, now = Date.now()): boolean {
+  if (now < RETIRED_MODEL_MIGRATION_CUTOFF) return false;
+  let migrated = false;
+  if (config.webSearchSidecar?.model === RETIRED_SIDECAR_MODEL) {
+    config.webSearchSidecar = { ...config.webSearchSidecar, model: REPLACEMENT_MODEL };
+    migrated = true;
+  }
+  if (config.visionSidecar?.model === RETIRED_SIDECAR_MODEL) {
+    config.visionSidecar = { ...config.visionSidecar, model: REPLACEMENT_MODEL };
+    migrated = true;
+  }
+  if (config.tokenGuardian?.codexWarmupModel === RETIRED_SIDECAR_MODEL) {
+    config.tokenGuardian = { ...config.tokenGuardian, codexWarmupModel: REPLACEMENT_MODEL };
+    migrated = true;
+  }
+  return migrated;
+}
diff --git a/src/codex/routing.ts b/src/codex/routing.ts
index a1f1f4fbd9..12c3e5e951 100644
--- a/src/codex/routing.ts
+++ b/src/codex/routing.ts
@@ -18,7 +18,7 @@ import {
   seedPoolRotationAccount,
   selectPriorityTier,
 } from "./pool-rotation";
-import { CODEX_EXHAUSTED_USAGE_PERCENT, CODEX_UNKNOWN_USAGE_SCORE, getAccountQuota } from "./quota";
+import { CODEX_EXHAUSTED_USAGE_PERCENT, CODEX_UNKNOWN_USAGE_SCORE, getAccountQuota, resetAtToMs } from "./quota";
 import { codexPlanKey, isThirtyDayOnlyCodexPlan } from "./plan";
 import {
   MAIN_CODEX_ACCOUNT_ID,
@@ -63,6 +63,25 @@ type CodexUpstreamHealth = {
   lastFailureAt?: number;
   /** Hard cooldown (quota 429). Survives a later 2xx; blocks auth + selection. */
   cooldownUntil?: number;
+  /**
+   * How long a quota refusal keeps selection away from this account (or this native quota
+   * group), as opposed to how long it is hard-blocked.
+   *
+   * The two are deliberately different lengths. {@link CODEX_MAX_RESET_DERIVED_COOLDOWN_MS}
+   * caps the hard cooldown at 15 minutes because a reset announcement is advisory and plan
+   * quota usually frees up before it — an account must stay reachable so the pool can find
+   * that out (#433). The window the refusal announced is not 15 minutes, though, so once the
+   * cooldown lapses the account is selectable again while its burst window is still spent,
+   * and the strategy picks it straight back: this proxy reads a weekly bar a burst limit never
+   * touches, so a refused account still scores as the coolest in the pool. Every request then
+   * earns the same 429 until the process restarts, which is the only thing that drops this map.
+   *
+   * So the announcement governs avoidance and the cap still governs blocking. Avoidance is soft
+   * in the {@link softAvoidUntil} sense: it reorders the pool and releases a bound thread, and
+   * the last-resort paths still reach the account when nothing else can serve, so one pessimistic
+   * announcement cannot stall routing.
+   */
+  quotaAvoidUntil?: number;
   /** When the current cooldown was recorded; origin of the probe interval clock. */
   cooldownSince?: number;
   /**
@@ -112,6 +131,12 @@ const CODEX_MAX_QUOTA_COOLDOWN_MS = 24 * 60 * 60_000;
  * the Retry-After ceiling (#433).
  */
 const CODEX_MAX_RESET_DERIVED_COOLDOWN_MS = 15 * 60_000;
+/**
+ * Ceiling on quota-refusal avoidance. Generous enough to cover a full five-hour burst window,
+ * tight enough that a weekly or monthly reset four days out cannot take an account out of
+ * rotation for the {@link CODEX_MAX_QUOTA_COOLDOWN_MS} day the Retry-After ceiling allows.
+ */
+const CODEX_MAX_QUOTA_AVOID_MS = 6 * 60 * 60_000;
 /** Minimum gap between probe leases for one cooled-down account. */
 export const CODEX_QUOTA_PROBE_INTERVAL_MS = 5 * 60_000;
 export const CODEX_FAILURE_WINDOW_MS = 5 * 60_000;
@@ -315,14 +340,30 @@ export function clearThreadAccountMapForAccount(accountId: string): void {
 }
 
 export function clearCodexUpstreamHealth(): void {
+  // Operator preferences are routing state, not health, but they live and die with the same
+  // reset points. Leaving them behind lets a selection from one context suppress the
+  // automatic cursor in the next one.
+  manualPreference.clear();
   upstreamHealth.clear();
   quotaScopedHealth.clear();
   runtimeActiveCodexAccountId = undefined;
+  // The reconcile watermark is part of this state, not something that outlives it. Keeping
+  // it across a full reset is incoherent: there is no health left to protect, yet
+  // recordCodexUpstreamOutcome would still drop a writer whose generation predates the
+  // watermark for any account missing from the equally stale live set. Left behind, it also
+  // leaks between test files, which is how it was found.
+  lastReconciledGeneration = 0;
+  liveHealthAccountIds = new Set();
 }
 
 export function clearCodexUpstreamHealthForAccount(accountId: string): void {
   upstreamHealth.delete(accountId);
   quotaScopedHealth.delete(accountId);
+  // Deletion is the third operator exit, next to pause and exclusion, and it is the one
+  // with no reconcile path behind it: once the account is gone nothing can succeed on it,
+  // so an unspent preference naming it would suppress the automatic cursor for every other
+  // account until the process restarts.
+  forgetManualPreference(accountId);
 }
 
 export function reconcileCodexRoutingHealth(context: GenerationContext): number {
@@ -338,6 +379,14 @@ export function reconcileCodexRoutingHealth(context: GenerationContext): number
     quotaScopedHealth.delete(accountId);
     removed += 1;
   }
+  // Sweep preferences the same way, for the account set this generation actually has. The
+  // delete path above is the direct route; this is the one that catches an account removed
+  // by an edit the runtime never saw. Deliberately not counted in `removed`, which reports
+  // health rows.
+  for (const [poolKey, preferred] of manualPreference) {
+    if (context.codexAccountIds.has(preferred)) continue;
+    manualPreference.delete(poolKey);
+  }
   liveHealthAccountIds = new Set(context.codexAccountIds);
   lastReconciledGeneration = context.generation;
   return removed;
@@ -405,9 +454,11 @@ export function computeCodexUsageScore(quota: {
  * A short-only reading that proves the account is blocked NOW.
  *
  * Freshness is not optional. `getAccountQuota` performs no expiry check, partial updates
- * carry the old short tuple forward, and disk hydration accepts a persisted reading for
+ * carry a still-open short tuple forward, and disk hydration accepts a persisted reading for
  * hours — so scoring 100 from `shortPercent` alone would keep excluding an account whose
- * five-hour window has since reset. That is #3029 pointed the other way: the issue is that
+ * five-hour window has since reset. Merge no longer carries an elapsed shortResetAt, but an
+ * explicit incoming elapsed tuple is still stored, and a missing reset cannot be aged there.
+ * That is #3029 pointed the other way: the issue is that
  * an exhausted account stays selected, and "a recovered account stays excluded" trades one
  * unusable pool for another.
  *
@@ -433,12 +484,9 @@ function isTerminalShortWindow(
     const age = now - observedAt;
     return age >= 0 && age <= TERMINAL_SHORT_WINDOW_FRESHNESS_MS;
   }
-  // Both units reach storage: `normalizeResetAt` does not scale, and the GUI disambiguates
-  // by magnitude at read time. A comparison written against one assumption is off by 1000x
-  // against the other, and in the seconds-read-as-milliseconds direction every terminal
-  // reading looks like it reset in 1970 — a fix that passes its own test and does nothing.
-  const resetAtMs = resetAt < 10_000_000_000 ? resetAt * 1000 : resetAt;
-  return resetAtMs > now;
+  // Seconds and milliseconds both reach storage, so the split lives in one place next to the
+  // merge that also ages a stored reset instant (`resetAtToMs`, src/codex/quota.ts).
+  return resetAtToMs(resetAt) > now;
 }
 
 export function classifyCodexUpstreamOutcome(
@@ -523,6 +571,51 @@ export function computeQuotaCooldown(meta: CodexUpstreamOutcomeMeta = {}): {
   return { until: now + CODEX_DEFAULT_QUOTA_COOLDOWN_MS, source: "default" };
 }
 
+/**
+ * When the pool should stop preferring an account after it refused on quota.
+ *
+ * The earliest window the refusal actually announced, bounded by {@link CODEX_MAX_QUOTA_AVOID_MS},
+ * and never shorter than the cooldown the same refusal produced — a Retry-After directive that
+ * outlasts every announcement still governs.
+ */
+function quotaAvoidUntilFor(meta: CodexUpstreamOutcomeMeta, now: number, cooldownUntil: number): number {
+  const values = Array.isArray(meta.resetAt) ? meta.resetAt : [meta.resetAt];
+  let announced: number | undefined;
+  for (const value of values) {
+    const timestamp = resetTimestampMs(value);
+    if (timestamp === undefined) continue;
+    const delay = timestamp - now;
+    if (delay <= 0) continue;
+    const until = now + Math.min(delay, CODEX_MAX_QUOTA_AVOID_MS);
+    if (announced === undefined || until < announced) announced = until;
+  }
+  return Math.max(cooldownUntil, announced ?? 0);
+}
+
+/** Live quota-refusal avoidance for an account, including the lane the request belongs to. */
+function codexQuotaAvoidUntil(
+  accountId: string,
+  quotaScope: CodexQuotaScope | undefined,
+  now: number,
+): number | null {
+  const live = (value: number | undefined): number | null =>
+    typeof value === "number" && Number.isFinite(value) && value > now ? value : null;
+  const account = live(upstreamHealth.get(accountId)?.quotaAvoidUntil);
+  const scoped = quotaScope === undefined
+    ? null
+    : live(scopedHealthFor(accountId, quotaScope)?.quotaAvoidUntil);
+  if (account === null) return scoped;
+  return scoped === null ? account : Math.max(account, scoped);
+}
+
+function isCodexQuotaAvoided(
+  accountId: string,
+  quotaScope: CodexQuotaScope | undefined,
+  now: number,
+): boolean {
+  return codexQuotaAvoidUntil(accountId, quotaScope, now) !== null;
+}
+
 export function computeQuotaCooldownUntil(meta: CodexUpstreamOutcomeMeta = {}): number {
   return computeQuotaCooldown(meta).until;
 }
@@ -764,6 +857,10 @@ function settleCooldownRecoveryLease(claim: CooldownRecoveryLease, recovered: bo
       cooldownSource: _source,
       probeLeaseId: _leaseId,
       probeLeaseGeneration: _leaseGeneration,
+      // "The quota window moved" is a statement about the whole refusal, so the avoidance it
+      // announced goes with the block it produced. Leaving it would make this escape hatch stop
+      // escaping: the account would still be passed over by every selection it is meant to win.
+      quotaAvoidUntil: _avoid,
       ...rest
     } = health;
     upstreamHealth.set(claim.accountId, {
@@ -871,6 +968,14 @@ export function resetCodexRoutingForManualSelection(accountId: string): void {
   clearThreadAccountMap();
   // Manual selection is the operator source of truth — drop any automatic runtime cursor.
   runtimeActiveCodexAccountId = undefined;
+  // Record the pick as an unspent one-shot on the SHARED scope only. An independent scope
+  // gets no entry on purpose: every write site the guard protects is already skipped for
+  // independent scopes, so an entry there would be state nothing reads — and state nothing
+  // reads is what the next reader mistakes for a rule.
+  //
+  // Seeding happens ONLY here. A pool-driven promote must never create or move a preference,
+  // or the pool would manufacture an operator intent nobody expressed.
+  manualPreference.set(POOL_KEY_CODEX, accountId);
   // Seed the RR ring so the next unbound new session honors the manually selected account
   // under round-robin (affinity-cleared threads / null threadId). Fill-first already follows
   // config.activeCodexAccountId, which the caller persists before invoking this.
@@ -880,11 +985,27 @@ export function resetCodexRoutingForManualSelection(accountId: string): void {
       seedPoolRotationAccount(codexPoolKeyForScope(scope), accountId);
     }
   }
+  // Quota avoidance is a preference, like the soft avoid dropped above, and an operator naming
+  // this account has overruled it. The hard cooldown is the part that survives.
+  const overrule = (health: CodexUpstreamHealth) => {
+    const { quotaAvoidUntil: _avoid, ...retained } = preservedCooldownFields(health);
+    return retained;
+  };
   const current = upstreamHealth.get(accountId);
-  if (!current) return;
-  const preserved = preservedCooldownFields(current);
-  if (Object.keys(preserved).length === 0) upstreamHealth.delete(accountId);
-  else upstreamHealth.set(accountId, { consecutiveFailures: 0, ...preserved });
+  if (current) {
+    const retained = overrule(current);
+    if (Object.keys(retained).length === 0) upstreamHealth.delete(accountId);
+    else upstreamHealth.set(accountId, { consecutiveFailures: 0, ...retained });
+  }
+  // A reset-derived refusal records its avoidance on the SCOPED map and returns before the
+  // account-wide entry is written, so naming the account has to reach that map too. Stopping
+  // at `upstreamHealth` — and returning early when it holds nothing — overruled nothing in
+  // the case that produces the avoidance this function exists to overrule.
+  for (const [scope, health] of [...(quotaScopedHealth.get(accountId) ?? [])]) {
+    const retained = overrule(health);
+    if (Object.keys(retained).length === 0) deleteScopedHealth(accountId, scope);
+    else setScopedHealth(accountId, scope, { consecutiveFailures: 0, ...retained });
+  }
 }
 
 export function getCodexAccountCooldownUntil(accountId: string, now = Date.now()): number | null {
@@ -953,18 +1074,31 @@ export function isCodexAccountInCooldown(accountId: string, now = Date.now()): b
  *   bumps it in {@link recordCodexUpstreamOutcome}, so the bump here is not load-bearing
  *   today and is kept so the invariant survives a future change that retains the lease.
  *
- * Returns false when the account carried no live cooldown (already expired or never set).
+ * Returns false when the account carried neither a live cooldown nor a live avoidance window.
+ * The window outlives the cooldown by design — the cooldown caps at fifteen minutes and the
+ * window runs up to six hours — so the moment an operator actually reaches for this escape
+ * hatch is usually after the cooldown lapsed and only the window is still keeping the account
+ * out of rotation. Refusing to look at the window then would leave the hatch shut in the one
+ * case it exists for.
  */
 export function clearCodexAccountCooldown(accountId: string, now = Date.now()): boolean {
   const clear = (health: CodexUpstreamHealth): CodexUpstreamHealth | null => {
     const cooldownUntil = health.cooldownUntil;
-    if (typeof cooldownUntil !== "number" || !Number.isFinite(cooldownUntil) || cooldownUntil <= now) return null;
+    const liveCooldown = typeof cooldownUntil === "number" && Number.isFinite(cooldownUntil) && cooldownUntil > now;
+    const avoidUntil = health.quotaAvoidUntil;
+    const liveAvoidance = typeof avoidUntil === "number" && Number.isFinite(avoidUntil) && avoidUntil > now;
+    if (!liveCooldown && !liveAvoidance) return null;
     const {
       cooldownUntil: _until,
       cooldownSince: _since,
       cooldownSource: _source,
       probeLeaseId: _leaseId,
       probeLeaseGeneration: _leaseGeneration,
+      // Same reasoning as the probe recovery above: "the quota window moved" is a statement
+      // about the whole refusal, so the avoidance it announced goes with the block it
+      // produced. Keeping it would leave this escape hatch not escaping, because selection
+      // would still pass over the account for as long as the announced window runs.
+      quotaAvoidUntil: _avoid,
       ...rest
     } = health;
     return {
@@ -1058,6 +1192,7 @@ function isCodexAccountSelectable(
   return !isCodexAccountPaused(config, accountId)
     && !isCodexAccountPlanExcluded(config, accountId)
     && getCodexQuotaHealthSnapshot(accountId, quotaScope, now) === null
+    && !isCodexQuotaAvoided(accountId, quotaScope, now)
     && !isCodexAccountSoftAvoided(accountId, now)
     && isCodexAccountUsable(config, accountId, selectionOptions);
 }
@@ -1297,6 +1432,7 @@ function getEligiblePoolAccounts(
       && (!skipFailoverReadyCandidates || !shouldFailover(config, account.id, now)))
     .filter(account => getCodexQuotaHealthSnapshot(account.id, quotaScope, now) === null)
     .filter(account => !isCodexAccountSoftAvoided(account.id, now))
+    .filter(account => !isCodexQuotaAvoided(account.id, quotaScope, now))
     .filter(account => isCodexAccountUsable(config, account.id, selectionOptions))
     .map(account => account.id);
   // The main Codex account is not stored in config.codexAccounts; include it as a
@@ -1307,6 +1443,12 @@ function getEligiblePoolAccounts(
     && (!isAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID) || hasMainAccountRefreshGrant())
     && getCodexQuotaHealthSnapshot(MAIN_CODEX_ACCOUNT_ID, quotaScope, now) === null
     && !isCodexAccountSoftAvoided(MAIN_CODEX_ACCOUNT_ID, now)
+    // The main login is not in `config.codexAccounts`, so it never passes through the
+    // filters above and this is the only place an avoidance window can exclude it. Without
+    // this the window a refusal announced applies to the pool but not to the account that
+    // earned it: the cooldown caps at fifteen minutes, the window runs up to six hours, and
+    // in between the main account returns as a first-class candidate.
+    && !isCodexQuotaAvoided(MAIN_CODEX_ACCOUNT_ID, quotaScope, now)
     && (!skipFailoverReadyCandidates || !shouldFailover(config, MAIN_CODEX_ACCOUNT_ID, now))
     && isCodexAccountUsable(config, MAIN_CODEX_ACCOUNT_ID, selectionOptions)
   ) {
@@ -1467,7 +1609,10 @@ function pickUnboundStrategyAccount(
     picked = pickRoundRobinAccount(poolKey, eligible, limit);
     if (!picked) return null;
     if (commitSharedActive) {
-      if (!isIndependentCodexQuotaScope(quotaScope)) rememberActiveCodexAccount(config, picked);
+      if (!isIndependentCodexQuotaScope(quotaScope)
+        && !manualPreferenceBlocks(codexPoolKeyForScope(quotaScope), picked)) {
+        rememberActiveCodexAccount(config, picked);
+      }
     }
     if (commitAffinity && threadId) bindThreadAffinity(threadId, picked, now, quotaScope);
     notePoolRotationSuccess(poolKey, picked, limit);
@@ -1478,7 +1623,10 @@ function pickUnboundStrategyAccount(
     picked = pickFillFirstCodexAccount(config, now, quotaScope, selectionOptions);
     if (!picked) return null;
     if (commitSharedActive) {
-      if (!isIndependentCodexQuotaScope(quotaScope)) rememberActiveCodexAccount(config, picked);
+      if (!isIndependentCodexQuotaScope(quotaScope)
+        && !manualPreferenceBlocks(codexPoolKeyForScope(quotaScope), picked)) {
+        rememberActiveCodexAccount(config, picked);
+      }
     }
     if (commitAffinity && threadId) bindThreadAffinity(threadId, picked, now, quotaScope);
     return picked;
@@ -1622,6 +1770,53 @@ export function pickAlternateCodexAccount(
 }
 
 /** Effective active: automatic runtime cursor, else operator/persisted selection. */
+/**
+ * Unspent operator selections, keyed by pool scope.
+ *
+ * Codex has no account-side equivalent of the Anthropic `selectionRevision`, so staleness
+ * cannot be detected by comparing values: a pool-driven promote legitimately moves the
+ * persisted active account, and reading that as staleness would silently spend the
+ * operator's one-shot. Invalidation is keyed to the OPERATOR path instead — another manual
+ * selection, the account leaving the pool, or a successful dispatch on it.
+ */
+const manualPreference = new Map<string, string>();
+
+/**
+ * Spend the one-shot for a pool scope once a dispatch on that account actually succeeded.
+ * This is the Codex analogue of `commitAnthropicSelectionRouting`, which Codex lacks.
+ *
+ * Wiring this BEFORE the guard below is not a style choice. Measured: with the guard in
+ * place and no consume site, the first manual selection freezes the automatic cursor
+ * permanently and 15 of 69 rotation tests fail.
+ */
+function consumeManualPreference(accountId: string, poolKey: string): void {
+  if (manualPreference.get(poolKey) === accountId) manualPreference.delete(poolKey);
+}
+
+/**
+ * Drop an account's preference in every scope. Pause and exclusion do not route through
+ * `resetCodexRoutingForManualSelection`, so without this a preference could outlive the
+ * account it names and keep suppressing the automatic cursor.
+ */
+function forgetManualPreference(accountId: string): void {
+  for (const [poolKey, preferred] of manualPreference) {
+    if (preferred === accountId) manualPreference.delete(poolKey);
+  }
+}
+
+/**
+ * True while an unspent operator selection for this scope names a DIFFERENT account than
+ * the automatic pick about to be recorded.
+ *
+ * Callers pass their own scope: an independent quota scope keeps its own entry and must
+ * never read the shared one. The failover promote does NOT consult this — see its call
+ * site for why.
+ */
+function manualPreferenceBlocks(poolKey: string, accountId: string): boolean {
+  const preferred = manualPreference.get(poolKey);
+  return preferred !== undefined && preferred !== accountId;
+}
+
 export function getEffectiveActiveCodexAccountId(config: OcxConfig): string | undefined {
   return runtimeActiveCodexAccountId ?? config.activeCodexAccountId;
 }
@@ -1690,6 +1885,10 @@ export function reconcileCodexActiveAfterExclusion(
   now = Date.now(),
 ): string | null {
   const wasEffective = (getEffectiveActiveCodexAccountId(config) ?? MAIN_CODEX_ACCOUNT_ID) === excludedAccountId;
+  // Exclusion does not route through resetCodexRoutingForManualSelection, so the one-shot is
+  // revoked here too. A preference naming an account that can no longer serve would keep
+  // suppressing the automatic cursor with no way to clear it.
+  forgetManualPreference(excludedAccountId);
   if (config.activeCodexAccountId === excludedAccountId) {
     config.activeCodexAccountId = undefined;
   }
@@ -1892,6 +2091,45 @@ export function resolveCodexAccountForThread(
   return resolution.status === "selected" ? resolution.accountId : null;
 }
 
+function carriesQuotaRefusal(health: CodexUpstreamHealth | undefined): boolean {
+  return health?.lastFailureStatus === 429 || health?.lastFailureStatus === 402;
+}
+
+/**
+ * Has this account refused a request on quota without serving one since?
+ *
+ * Thread affinity is a prompt-cache optimization and every rule around it is a preference:
+ * `autoSwitchThreshold` is a hint that an account is getting busy, and `pool.cacheAffinity`
+ * deliberately raises that bar further. A refusal is not a preference, and once the account has
+ * told THIS thread it cannot serve, the binding has nothing left to optimize.
+ *
+ * The distinction matters because the cooldown a 429 writes is deliberately short. A reset
+ * announcement is advisory — plan quota routinely frees up before the advertised instant — so
+ * {@link CODEX_MAX_RESET_DERIVED_COOLDOWN_MS} caps it at 15 minutes. The five-hour window that
+ * announcement describes is not capped, so an account whose burst window is spent looks
+ * selectable again long before it is. For an unbound request that is correct: going back to find
+ * out is how the pool learns the window moved. For a BOUND thread it is a loop with no exit —
+ * the cooldown lapses, the account still scores lowest on the only window this proxy has a
+ * reading for (its weekly bar, untouched by a burst limit), the thread rebinds, and earns the
+ * identical 429. Cleared affinity does not help: the next request re-derives the same choice.
+ * From the Codex side that reads exactly as reported — a new session rotates normally while an
+ * existing one is locked to an exhausted account until the proxy is restarted, because a restart
+ * is the only thing that drops the binding and the stale health together.
+ *
+ * `lastFailureStatus` is the right evidence because of when it ends: {@link preservedCooldownFields}
+ * strips it from every recovery write, so it survives exactly until the account actually serves a
+ * request again. Nothing here blocks that — selection is untouched, so unbound traffic still probes
+ * the account and the first success releases every thread this refused.
+ *
+ * Scope follows where the refusal was recorded. An account-wide throttle lands in
+ * `upstreamHealth` and releases every lane; a reset-derived refusal lands against one native
+ * quota group, so a spent Spark window still cannot displace the same thread's Terra binding.
+ */
+function hasUnrecoveredCodexQuotaRefusal(accountId: string, quotaScope?: CodexQuotaScope): boolean {
+  if (carriesQuotaRefusal(upstreamHealth.get(accountId))) return true;
+  return quotaScope !== undefined && carriesQuotaRefusal(scopedHealthFor(accountId, quotaScope));
+}
+
 function previewReusableAffinityAccount(
   entry: ThreadAffinityEntry | undefined,
   config: OcxConfig,
@@ -1904,6 +2142,7 @@ function previewReusableAffinityAccount(
     || isThreadAffinityExpired(entry, now)
     || !isThreadAffinityGenerationLive(entry)
     || !isCodexAccountSelectable(config, entry.accountId, now, quotaScope, selectionOptions)
+    || hasUnrecoveredCodexQuotaRefusal(entry.accountId, quotaScope)
     || shouldFailover(config, entry.accountId, now)
   ) {
     return null;
@@ -1918,7 +2157,9 @@ function previewReusableAffinityAccount(
         getPoolAccountPlanForSelection(config, entry.accountId, selectionOptions),
       now,
       );
-      if (!isUnknownUsage(usage) && usage >= threshold) {
+      // Preview must agree with resolve: this is the second copy of the same rule, and the
+      // suite asserts the two answer identically.
+      if (mayRebindAffinityForQuota(config, entry.accountId, usage, threshold, selectionOptions)) {
         const best = pickLowerUsageAccount(
           config,
           entry.accountId,
@@ -1935,6 +2176,32 @@ function previewReusableAffinityAccount(
   return entry.accountId;
 }
 
+/**
+ * May a LIVE binding be moved for quota reasons?
+ *
+ * Default: yes once usage crosses `autoSwitchThreshold`, which is the historical rule.
+ *
+ * With `pool.cacheAffinity` on, the bar becomes genuine exhaustion. Moving a bound
+ * conversation discards the prompt cache warmed on its account, so a threshold crossing -- a
+ * hint that the account is getting busy -- does not justify paying that cost; the account has
+ * to be unable to serve. Deliberately NOT `hasCodexQuotaHeadroom`, which reads
+ * `usage < autoSwitchThreshold` and would reproduce the old rule under a new name.
+ */
+function mayRebindAffinityForQuota(
+  config: OcxConfig,
+  accountId: string,
+  usage: number,
+  threshold: number,
+  selectionOptions?: CodexAccountUsabilityOptions,
+): boolean {
+  const overThreshold = threshold > 0 && !isUnknownUsage(usage) && usage >= threshold;
+  if (config.pool?.cacheAffinity !== true) return overThreshold;
+  // The usable half is already guaranteed by both callers, which gate on
+  // isCodexAccountSelectable; kept explicit so the predicate reads correctly on its own.
+  return !isCodexAccountUsable(config, accountId, selectionOptions)
+    || (!isUnknownUsage(usage) && usage >= 100);
+}
+
 /**
  * Re-evaluate an affined account under the quota strategy. Returns a strictly
  * cooler replacement, or null when the current binding should remain.
@@ -1955,15 +2222,18 @@ function reevaluateAffinityQuota(
       now,
       )
     : 0;
-  const overThreshold = threshold > 0 && !isUnknownUsage(usage) && usage >= threshold;
+  // One bar, used for BOTH the rebind decision and the re-score interval. Keying the short
+  // circuit off the old threshold while the rebind bar moved would re-score a bound thread on
+  // every request through the whole 80-99% band instead of once a minute.
+  const mayRebind = mayRebindAffinityForQuota(config, entry.accountId, usage, threshold, selectionOptions);
   if (
-    !overThreshold
+    !mayRebind
     && now - entry.lastReevalAt < CODEX_THREAD_AFFINITY_REEVAL_INTERVAL_MS
   ) {
     return null;
   }
   entry.lastReevalAt = now;
-  if (!overThreshold) return null;
+  if (!mayRebind) return null;
   const best = pickLowerUsageAccount(
     config,
     entry.accountId,
@@ -2106,6 +2376,7 @@ export function resolveCodexAccountForThreadDetailed(
       const detourReusable = !isThreadAffinityExpired(detourEntry, now)
         && isThreadAffinityGenerationLive(detourEntry)
         && isCodexAccountSelectable(config, detourEntry.accountId, now, quotaScope, selectionOptions)
+        && !hasUnrecoveredCodexQuotaRefusal(detourEntry.accountId, quotaScope)
         && !shouldFailover(config, detourEntry.accountId, now);
       if (detourReusable) {
         detourEntry.lastUsedAt = now;
@@ -2143,11 +2414,16 @@ export function resolveCodexAccountForThreadDetailed(
     const selectableForRequest = selectableForSharedState
       && isCodexAccountSelectable(config, entry.accountId, now, quotaScope, selectionOptions);
     const failoverReady = shouldFailover(config, entry.accountId, now);
+    // A quota refusal outranks every affinity preference, including `pool.cacheAffinity`:
+    // the account has already told this thread it cannot serve it.
+    const quotaRefused = hasUnrecoveredCodexQuotaRefusal(entry.accountId, quotaScope);
     const healthyForSharedAffinity = selectableForSharedState
       && hasCodexQuotaHeadroom(config, entry.accountId, sharedSelectionOptions, now)
+      && !quotaRefused
       && !failoverReady;
     if (
       selectableForRequest
+      && !quotaRefused
       // Affined threads must leave a failing account once the streak trips failover
       // (soft-avoid covers the first-hit case; this catches post-avoid residual streaks).
       && !failoverReady
@@ -2210,6 +2486,13 @@ export function resolveCodexAccountForThreadDetailed(
       && !preserveSharedSelectionForModelDetour
       && !isIndependentCodexQuotaScope(quotaScope)
     ) {
+      // NOT guarded by manualPreferenceBlocks, unlike preemption below. Measured: guarding
+      // it fails 8 cases in tests/codex-integration/codex-routing.test.ts, because a model
+      // detour is not the pool exercising discretion — the operator's account cannot serve
+      // this model at all. Under a rotating strategy this promote only moves the
+      // process-local cursor to whoever is actually serving and releases the pin; the
+      // operator's persisted activeCodexAccountId is left untouched either way, which is
+      // the thing the preference exists to protect.
       promoteActiveCodexAccount(config, strategyPick);
     }
     return { status: "selected", accountId: strategyPick };
@@ -2283,7 +2566,10 @@ export function resolveCodexAccountForThreadDetailed(
       !preserveSharedSelectionForModelDetour
       && !isIndependentCodexQuotaScope(quotaScope)
     ) {
-      rememberActiveCodexAccount(config, preempted);
+      // Preemption is an automatic pick competing with the operator, so it yields.
+      if (!manualPreferenceBlocks(POOL_KEY_CODEX, preempted)) {
+        rememberActiveCodexAccount(config, preempted);
+      }
     }
     active = preempted;
   }
@@ -2354,6 +2640,9 @@ export function recordCodexUpstreamOutcome(
    */
   dropSpentCredentialFailure(accountId);
   if (outcomeClass === "success") {
+    // The operator's one-shot is spent by a dispatch that actually worked, and only by that.
+    // A failed lookup leaves it unspent so the intent survives the failure.
+    consumeManualPreference(accountId, codexPoolKeyForScope(quotaScope));
     const scopedProbe = meta.probeQuotaScope
       ? scopedHealthFor(accountId, meta.probeQuotaScope)
       : undefined;
@@ -2364,6 +2653,20 @@ export function recordCodexUpstreamOutcome(
         setScopedHealth(accountId, meta.probeQuotaScope, withProbeLeaseReleased(scopedProbe, now));
       }
     }
+    // A served request is what ends the refusal marker the quota branch left on this lane.
+    // The probe contract above owns the scoped COOLDOWN; this owns only the field
+    // {@link hasUnrecoveredCodexQuotaRefusal} reads, which would otherwise keep threads away
+    // from an account that is demonstrably serving them again. The account-wide marker needs
+    // no equivalent: every recovery write below runs it through preservedCooldownFields.
+    const refusedScope = quotaScope ? scopedHealthFor(accountId, quotaScope) : undefined;
+    if (quotaScope && refusedScope && carriesQuotaRefusal(refusedScope)) {
+      const {
+        lastFailureStatus: _refusal, lastFailureAt: _refusedAt, quotaAvoidUntil: _avoid, ...retained
+      } = refusedScope;
+      // A live cooldown and its probe bookkeeping survive; an entry that held nothing else goes.
+      if (Object.keys(retained).length > 1) setScopedHealth(accountId, quotaScope, retained);
+      else deleteScopedHealth(accountId, quotaScope);
+    }
     const current = upstreamHealth.get(accountId);
     const cooldownUntil = getCodexAccountCooldownUntil(accountId, now);
     // A leased probe that is still on its own cooldown generation proves the
@@ -2507,6 +2810,7 @@ export function recordCodexUpstreamOutcome(
         lastFailureStatus,
         lastFailureAt: now,
         cooldownUntil: until,
+        quotaAvoidUntil: quotaAvoidUntilFor(meta, now, until),
         cooldownSince: now,
         cooldownSource: source,
         cooldownGeneration,
@@ -2555,6 +2859,7 @@ export function recordCodexUpstreamOutcome(
       lastFailureStatus,
       lastFailureAt: now,
       cooldownUntil: until,
+      quotaAvoidUntil: quotaAvoidUntilFor(meta, now, until),
       cooldownSince: now,
       cooldownSource: source,
       cooldownGeneration,
diff --git a/src/codex/warmup.ts b/src/codex/warmup.ts
index 2fbd87d582..7be16980c6 100644
--- a/src/codex/warmup.ts
+++ b/src/codex/warmup.ts
@@ -27,8 +27,8 @@ export interface CodexWarmupOptions {
 }
 
 const CODEX_RESPONSES_URL = "https://chatgpt.com/backend-api/codex/responses";
-const DEFAULT_MODEL = "gpt-5.4-mini";
-const FALLBACK_MODELS = ["gpt-5.5", "gpt-5.6-luna"];
+const DEFAULT_MODEL = "gpt-5.6-luna";
+const FALLBACK_MODELS = ["gpt-5.5"];
 const isRetryableWarmupStatus = (status?: number): boolean => status === 400 || status === 404;
 const DEFAULT_TIMEOUT_MS = 30_000;
 const MAX_TIMEOUT_MS = 0x7fff_ffff;
diff --git a/src/combos/failover.ts b/src/combos/failover.ts
index 3868bc4b0c..e592298d88 100644
--- a/src/combos/failover.ts
+++ b/src/combos/failover.ts
@@ -1,5 +1,6 @@
 import { parseResetCooldownMs } from "../codex/routing";
 import { classifyError, isCyberPolicyCode } from "../lib/errors";
+import { isNonReplayableUpstreamCode } from "../lib/upstream-retry";
 import type { OcxComboTarget } from "../types";
 import { targetKey } from "./types";
 import {
@@ -413,6 +414,10 @@ export function comboFailureDecision(
 ): ComboFailureDecision {
   if (status === 499) return "stop";
   if (message.toLowerCase().includes("origin_rejected")) return "stop";
+  // The origin may already be executing this turn (the Codex WebSocket relay sent the create
+  // frame and never saw a response event). Hopping would send the same request to a second
+  // target while the first may still be generating; the honest status goes to the client.
+  if (isNonReplayableUpstreamCode(options?.code)) return "stop";
   // Cyber policy is a hard non-retryable refusal — honor structured code even when
   // classificationText was truncated before the JSON code field.
   if (isCyberPolicyCode(options?.code)) return "stop";
diff --git a/src/combos/resolve.ts b/src/combos/resolve.ts
index 71ea750b6e..13fd4ccf6d 100644
--- a/src/combos/resolve.ts
+++ b/src/combos/resolve.ts
@@ -1,7 +1,6 @@
 import type { OcxComboTarget, OcxConfig } from "../types";
-import { getCachedProviderQuota } from "../providers/quota-routing-cache";
+import { getCachedProviderRoutingQuota } from "../providers/quota-routing-cache";
 import type { ProviderQuota } from "../providers/quota-types";
-import { isCanonicalOpenAiForwardProvider } from "../providers/openai-tiers";
 import { sleepWithAbort } from "../lib/upstream-retry";
 import {
   coolComboTarget,
@@ -65,9 +64,7 @@ function targetProviderIsUsable(config: OcxConfig, target: OcxComboTarget, now:
   if (!Object.hasOwn(config.providers, target.provider)) return false;
   const provider = config.providers[target.provider];
   if (!provider || provider.disabled === true) return false;
-  // Native account selection owns model-scoped quota; a provider summary cannot veto it.
-  return isCanonicalOpenAiForwardProvider(provider)
-    || !cachedProviderQuotaIsExhausted(getCachedProviderQuota(target.provider, now), now);
+  return !cachedProviderQuotaIsExhausted(getCachedProviderRoutingQuota(target.provider, provider, now), now);
 }
 
 function quotaWindowExhausted(percent: number | undefined, resetAt: number | undefined, now: number): boolean {
@@ -104,11 +101,8 @@ export type QuotaInactiveReason = "no_credit";
  * `"no_credit"` when every USABLE target of a catalog row has positive exhaustion evidence
  * (#1711), otherwise undefined.
  *
- * This deliberately reuses the runtime rules in `targetProviderIsUsable` above rather than the
- * Dashboard's `quotaStateFromReport`, which is harsher: it treats `remaining <= 0` as exhausted
- * without requiring `percent >= 100` and ignores an elapsed `resetAt`. A catalog row marked
- * inactive on the harsher rule would contradict the router, which would still happily send the
- * request.
+ * This reuses the credential-scoped evidence and exhaustion rules used by runtime selection.
+ * Display-only account, model-group and service windows cannot mark a whole provider inactive.
  *
  * Three rules carry the correctness, all inherited rather than restated:
  *
@@ -117,7 +111,7 @@ export type QuotaInactiveReason = "no_credit";
  *   reason rather than a quota one, so this returns undefined.
  * - The canonical ChatGPT forward provider is exempt. Native account selection owns model-scoped
  *   quota, and a provider-level summary cannot veto it.
- * - A stale cache is NOT exhaustion. `getCachedProviderQuota` returns null past its 30-minute
+ * - A stale cache is NOT exhaustion. `getCachedProviderRoutingQuota` returns null past its 30-minute
  *   window, and a null reading ends the vote rather than counting as evidence, so an unprobed
  *   provider is never marked inactive.
  *
@@ -137,8 +131,7 @@ export function quotaInactiveReason(
   if (usable.length === 0) return undefined;
   for (const target of usable) {
     const provider = config.providers[target.provider]!;
-    if (isCanonicalOpenAiForwardProvider(provider)) return undefined;
-    const quota = getCachedProviderQuota(target.provider, now);
+    const quota = getCachedProviderRoutingQuota(target.provider, provider, now);
     if (!quota || !cachedProviderQuotaIsExhausted(quota, now)) return undefined;
   }
   return "no_credit";
@@ -181,6 +174,7 @@ function smoothWeightedIndex(
  * unknown (Infinity).
  */
 function resetWindowIndex(
+  config: OcxConfig,
   targets: Required<OcxComboTarget>[],
   eligible: (target: Required<OcxComboTarget>) => boolean,
   now = Date.now(),
@@ -190,7 +184,9 @@ function resetWindowIndex(
   for (let index = 0; index < targets.length; index++) {
     const target = targets[index]!;
     if (!eligible(target)) continue;
-    const remaining = quotaResetRemainingMs(getCachedProviderQuota(target.provider, now), now);
+    const remaining = quotaResetRemainingMs(
+      getCachedProviderRoutingQuota(target.provider, config.providers[target.provider], now), now,
+    );
     // Strict comparison deliberately retains configured order for ties,
     // including the no-snapshot fallback where every value is Infinity.
     if (selected < 0 || remaining < smallestRemaining) {
@@ -276,7 +272,7 @@ export function pickComboTarget(
       }
     }
   } else if (combo.strategy === "reset-window") {
-    targetIndex = resetWindowIndex(combo.targets, eligible, now);
+    targetIndex = resetWindowIndex(config, combo.targets, eligible, now);
   } else {
     targetIndex = combo.targets.findIndex(eligible);
   }
diff --git a/src/config.ts b/src/config.ts
index 66162c6a6a..5e81a7e5f1 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -580,6 +580,10 @@ const modelPinnedEffortsSchema = z.unknown().superRefine((value, ctx) => {
 const providerConfigSchema = z.object({
   pinnedReasoningEffort: pinnedReasoningEffortSchema.optional(),
   modelPinnedReasoningEfforts: modelPinnedEffortsSchema.optional(),
+  // Validated rather than left to passthrough: an unrecognized strategy would otherwise
+  // load silently and then be ignored at selection time, which reads as a broken feature
+  // rather than a rejected setting.
+  apiKeyPoolStrategy: z.enum(["round-robin", "fill-first", "quota"]).optional(),
   adapter: z.string().min(1),
   baseUrl: z.string().min(1),
   alias: z.string().optional(),
@@ -598,6 +602,7 @@ const providerConfigSchema = z.object({
   mcpMaxResultBytes: z.number().int().positive().optional(),
   apiKeyTransport: z.enum(["x-api-key", "bearer"]).optional(),
   responsesPath: z.string().min(1).optional(),
+  chatCompletionsPath: z.string().min(1).optional(),
   statelessResponses: z.boolean().optional(),
   requiresAdjacentResponsesToolResults: z.boolean().optional(),
   annotateEmptyToolOutputs: z.boolean().optional(),
@@ -622,6 +627,9 @@ const providerConfigSchema = z.object({
   noStructuredOutputModels: z.array(z.string().min(1))
     .transform(normalizeNonBlankStringArray)
     .optional(),
+  noJsonSchemaModels: z.array(z.string().min(1))
+    .transform(normalizeNonBlankStringArray)
+    .optional(),
   retainModels: z.array(z.string().min(1))
     .transform(normalizeNonBlankStringArray)
     .optional(),
@@ -649,6 +657,7 @@ const providerConfigSchema = z.object({
   webSearchBridge: providerWebSearchBridgeSchema.optional().catch(undefined),
   xaiResponsesXSearch: z.boolean().optional(),
   xaiResponsesDefaultVersion: z.number().int().positive().optional().catch(undefined),
+  zaiResponsesDefaultVersion: z.number().int().positive().optional().catch(undefined),
 }).passthrough();
 
 export { isValidProviderName, hasOwnProvider } from "./config/provider-name";
@@ -667,14 +676,18 @@ export {
   upstreamHttpVersionConfigError,
 } from "./config/provider-validation";
 
-function providerResponsesPathConfigError(responsesPath: string | undefined): string | null {
-  if (responsesPath === undefined) return null;
-  if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(responsesPath) || responsesPath.includes("://")) {
-    return "responsesPath must be a relative path without a URL scheme";
+/**
+ * Shared shape check for the two relative send-path overrides. `field` names the
+ * offending key so the message stays specific to what the user actually wrote.
+ */
+function providerRelativeSendPathConfigError(field: string, value: string | undefined): string | null {
+  if (value === undefined) return null;
+  if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(value) || value.includes("://")) {
+    return `${field} must be a relative path without a URL scheme`;
   }
-  if (!responsesPath.startsWith("/")) return "responsesPath must start with /";
-  if (responsesPath.includes("?") || responsesPath.includes("#")) {
-    return "responsesPath must not include query strings or fragments";
+  if (!value.startsWith("/")) return `${field} must start with /`;
+  if (value.includes("?") || value.includes("#")) {
+    return `${field} must not include query strings or fragments`;
   }
   return null;
 }
@@ -1298,6 +1311,12 @@ const configSchema = z.object({
     enabled: z.boolean().optional(),
     leadTimeMinutes: z.number().int().min(1).max(60).optional(),
   }).optional().catch(undefined),
+  // Same degrade-to-off rule as the flags above: a hand-edited typo in an opt-in pool
+  // feature must never cost the operator their providers.
+  pool: z.object({
+    kernel: z.boolean().optional(),
+    cacheAffinity: z.boolean().optional(),
+  }).optional().catch(undefined),
   // Model ids excluded from the Grok Build managed block (dashboard switches).
   grokExcludedModels: z.array(z.string()).optional(),
   // Invalid values degrade to undefined ("auto") instead of failing the whole
@@ -1443,13 +1462,15 @@ const configSchema = z.object({
         });
       }
     }
-    const responsesPathError = providerResponsesPathConfigError(provider.responsesPath);
-    if (responsesPathError) {
-      ctx.addIssue({
-        code: "custom",
-        path: ["providers", redactSecretString(name), "responsesPath"],
-        message: responsesPathError,
-      });
+    for (const field of ["responsesPath", "chatCompletionsPath"] as const) {
+      const sendPathError = providerRelativeSendPathConfigError(field, provider[field]);
+      if (sendPathError) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["providers", redactSecretString(name), field],
+          message: sendPathError,
+        });
+      }
     }
     const headersError = providerHeadersConfigError((provider as { headers?: unknown }).headers);
     if (headersError) {
@@ -1612,6 +1633,17 @@ const configSchema = z.object({
         message: structuredOutputOptOutError,
       });
     }
+    const jsonSchemaOptOutError = nonBlankStringArrayConfigError(
+      (provider as { noJsonSchemaModels?: unknown }).noJsonSchemaModels,
+      "noJsonSchemaModels",
+    );
+    if (jsonSchemaOptOutError) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["providers", redactSecretString(name), "noJsonSchemaModels"],
+        message: jsonSchemaOptOutError,
+      });
+    }
     const retainModelsError = nonBlankStringArrayConfigError(
       (provider as { retainModels?: unknown }).retainModels,
       "retainModels",
diff --git a/src/grok/grpc-web.ts b/src/grok/grpc-web.ts
new file mode 100644
index 0000000000..f292236929
--- /dev/null
+++ b/src/grok/grpc-web.ts
@@ -0,0 +1,120 @@
+/**
+ * Minimal, zero-dependency gRPC-Web binary framing encoder and decoder.
+ * Supports 5-byte header prefix: 0x00 data frames, 0x80 trailer frames.
+ */
+
+export interface GrpcWebTrailer {
+  status: number;
+  statusMessage?: string;
+  metadata: Record<string, string>;
+}
+
+export interface DecodedGrpcWebResponse {
+  messages: Uint8Array[];
+  status: number;
+  statusMessage?: string;
+  trailers?: GrpcWebTrailer;
+}
+
+export class GrpcWebError extends Error {
+  readonly status: number;
+  readonly statusMessage: string;
+
+  constructor(status: number, statusMessage: string) {
+    super(`gRPC-Web call failed with status ${status}: ${statusMessage}`);
+    this.name = "GrpcWebError";
+    this.status = status;
+    this.statusMessage = statusMessage;
+  }
+}
+
+const FRAME_DATA = 0x00;
+const FRAME_TRAILER = 0x80;
+const HEADER_SIZE = 5;
+
+/**
+ * Encodes a protobuf payload into a single gRPC-Web binary data frame (flag 0x00).
+ */
+export function encodeGrpcWebEnvelope(message: Uint8Array): Uint8Array {
+  const envelope = new Uint8Array(HEADER_SIZE + message.length);
+  envelope[0] = FRAME_DATA;
+  const view = new DataView(envelope.buffer, envelope.byteOffset, envelope.byteLength);
+  view.setUint32(1, message.length, false); // Big-endian u32
+  envelope.set(message, HEADER_SIZE);
+  return envelope;
+}
+
+/**
+ * Parses ASCII key-value lines from a gRPC-Web trailer frame payload.
+ */
+export function parseGrpcWebTrailers(bytes: Uint8Array): GrpcWebTrailer {
+  const text = new TextDecoder("utf-8").decode(bytes);
+  const lines = text.split(/\r?\n/);
+  const metadata: Record<string, string> = {};
+  let status = 0;
+  let statusMessage: string | undefined;
+
+  for (const line of lines) {
+    const colonIdx = line.indexOf(":");
+    if (colonIdx === -1) continue;
+    const key = line.slice(0, colonIdx).trim().toLowerCase();
+    const value = line.slice(colonIdx + 1).trim();
+    if (!key) continue;
+    metadata[key] = value;
+    if (key === "grpc-status") {
+      const parsed = parseInt(value, 10);
+      if (!Number.isNaN(parsed)) {
+        status = parsed;
+      }
+    } else if (key === "grpc-message") {
+      try {
+        statusMessage = decodeURIComponent(value);
+      } catch {
+        statusMessage = value;
+      }
+    }
+  }
+
+  return { status, statusMessage, metadata };
+}
+
+/**
+ * Decodes a contiguous gRPC-Web binary stream into data messages and trailing metadata.
+ */
+export function decodeGrpcWebResponse(bytes: Uint8Array): DecodedGrpcWebResponse {
+  const messages: Uint8Array[] = [];
+  let offset = 0;
+  let trailer: GrpcWebTrailer | undefined;
+
+  while (offset + HEADER_SIZE <= bytes.length) {
+    const flag = bytes[offset];
+    const view = new DataView(bytes.buffer, bytes.byteOffset + offset, HEADER_SIZE);
+    const length = view.getUint32(1, false);
+    const frameStart = offset + HEADER_SIZE;
+    const frameEnd = frameStart + length;
+
+    if (frameEnd > bytes.length) {
+      throw new Error(`Incomplete gRPC-Web frame at offset ${offset}: expected ${length} bytes, got ${bytes.length - frameStart}`);
+    }
+
+    const payload = bytes.subarray(frameStart, frameEnd);
+
+    if (flag === FRAME_DATA) {
+      messages.push(payload);
+    } else if (flag === FRAME_TRAILER) {
+      trailer = parseGrpcWebTrailers(payload);
+    }
+
+    offset = frameEnd;
+  }
+
+  const finalStatus = trailer ? trailer.status : 0;
+  const finalMessage = trailer?.statusMessage;
+
+  return {
+    messages,
+    status: finalStatus,
+    statusMessage: finalMessage,
+    trailers: trailer,
+  };
+}
diff --git a/src/grok/reset-coupon-ledger.ts b/src/grok/reset-coupon-ledger.ts
new file mode 100644
index 0000000000..ac63f9fc44
--- /dev/null
+++ b/src/grok/reset-coupon-ledger.ts
@@ -0,0 +1,139 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteFile } from "../config/atomic-write";
+import { getConfigDir } from "../config/paths";
+
+export type GrokResetCouponOperationKind = "execute" | "replay" | "identity-mismatch" | "capacity";
+
+export interface GrokResetCouponOperationIdentity {
+  accountId: string;
+  tokenId?: string;
+  operationId: string;
+}
+
+export interface GrokResetCouponOperationRecord {
+  kind: GrokResetCouponOperationKind;
+  operationId: string;
+  accountId?: string;
+  tokenId?: string;
+  code?: string;
+  settledAt?: number;
+}
+
+interface GrokResetCouponOperationState {
+  accountId: string;
+  tokenId?: string;
+  status: "open" | "settled" | "failed";
+  code?: string;
+  createdAt: number;
+  updatedAt: number;
+}
+
+interface GrokResetCouponLedger {
+  version: 1;
+  operations: Record<string, GrokResetCouponOperationState>;
+}
+
+export function grokCouponJournalPath(customDir?: string): string {
+  const dir = customDir ?? getConfigDir();
+  return join(dir, "grok-reset-coupon-ledger.json");
+}
+
+function readGrokCouponLedger(filePath: string): GrokResetCouponLedger {
+  if (!existsSync(filePath)) {
+    return { version: 1, operations: {} };
+  }
+  try {
+    const raw = readFileSync(filePath, "utf-8");
+    const parsed = JSON.parse(raw) as GrokResetCouponLedger;
+    return parsed && parsed.version === 1 && parsed.operations && typeof parsed.operations === "object"
+      ? parsed
+      : { version: 1, operations: {} };
+  } catch {
+    return { version: 1, operations: {} };
+  }
+}
+
+function writeGrokCouponLedger(filePath: string, ledger: GrokResetCouponLedger, now = Date.now()): void {
+  // Prune settled/failed operations older than 30 days to avoid unbounded growth
+  const retentionCutoff = now - 30 * 24 * 60 * 60_000;
+  ledger.operations = Object.fromEntries(
+    Object.entries(ledger.operations).filter(
+      ([, op]) => op.status === "open" || op.updatedAt > retentionCutoff,
+    ),
+  );
+  atomicWriteFile(filePath, JSON.stringify(ledger, null, 2));
+}
+
+const MAX_GROK_RESET_COUPON_OPERATION_IDS = 256;
+
+export function openGrokResetCouponOperation(
+  identity: GrokResetCouponOperationIdentity,
+  now = Date.now(),
+  journalPath?: string,
+): GrokResetCouponOperationRecord {
+  const filePath = journalPath ?? grokCouponJournalPath();
+  const ledger = readGrokCouponLedger(filePath);
+
+  if (Object.keys(ledger.operations).length >= MAX_GROK_RESET_COUPON_OPERATION_IDS) {
+    return { kind: "capacity", operationId: identity.operationId };
+  }
+
+  const existing = ledger.operations[identity.operationId];
+  if (existing) {
+    if (existing.accountId !== identity.accountId) {
+      return { kind: "identity-mismatch", operationId: identity.operationId };
+    }
+    if (existing.status !== "open") {
+      // Durably settled already: replay the recorded outcome instead of
+      // trusting upstream idempotency for an irreversible spend.
+      return {
+        kind: "replay",
+        operationId: identity.operationId,
+        accountId: existing.accountId,
+        tokenId: existing.tokenId,
+        code: existing.code,
+        settledAt: existing.updatedAt,
+      };
+    }
+    return {
+      kind: "execute",
+      operationId: identity.operationId,
+      accountId: existing.accountId,
+      tokenId: existing.tokenId,
+    };
+  }
+
+  ledger.operations[identity.operationId] = {
+    accountId: identity.accountId,
+    ...(identity.tokenId === undefined ? {} : { tokenId: identity.tokenId }),
+    status: "open",
+    createdAt: now,
+    updatedAt: now,
+  };
+  writeGrokCouponLedger(filePath, ledger, now);
+  return {
+    kind: "execute",
+    operationId: identity.operationId,
+    accountId: identity.accountId,
+    tokenId: identity.tokenId,
+  };
+}
+
+export function recordGrokResetCouponSettlement(
+  settlement: { operationId: string; tokenId?: string; code: string; status: "success" | "failed" },
+  now = Date.now(),
+  journalPath?: string,
+): void {
+  const filePath = journalPath ?? grokCouponJournalPath();
+  const ledger = readGrokCouponLedger(filePath);
+  const existing = ledger.operations[settlement.operationId];
+  if (!existing) return;
+
+  existing.status = settlement.status === "success" ? "settled" : "failed";
+  existing.code = settlement.code;
+  if (settlement.tokenId !== undefined) existing.tokenId = settlement.tokenId;
+  existing.updatedAt = now;
+
+  writeGrokCouponLedger(filePath, ledger, now);
+}
diff --git a/src/grok/reset-coupons.ts b/src/grok/reset-coupons.ts
new file mode 100644
index 0000000000..b35afd286a
--- /dev/null
+++ b/src/grok/reset-coupons.ts
@@ -0,0 +1,278 @@
+import { XAI_GROK_COMPATIBILITY } from "../providers/xai-transport";
+import {
+  decodeGrpcWebResponse,
+  encodeGrpcWebEnvelope,
+  GrpcWebError,
+} from "./grpc-web";
+
+export const GROK_CONSUMER_UI_BASE_URL = "https://grok.com";
+export const GROK_GET_REMAINING_RESETS_ENDPOINT =
+  "https://grok.com/prod_mc_billing.ConsumerUiSvc/GetRemainingResets";
+export const GROK_REDEEM_RESET_ENDPOINT =
+  "https://grok.com/prod_mc_billing.ConsumerUiSvc/RedeemReset";
+
+export interface GrokResetCoupon {
+  tokenId: string;
+  validityStart: string;
+  validityEnd: string;
+}
+
+export interface GetRemainingResetsOptions {
+  accessToken: string;
+  fetchFn?: typeof globalThis.fetch;
+  signal?: AbortSignal;
+  endpoint?: string;
+}
+
+export interface RedeemResetOptions {
+  accessToken: string;
+  tokenId: string;
+  fetchFn?: typeof globalThis.fetch;
+  signal?: AbortSignal;
+  endpoint?: string;
+}
+
+export interface RedeemResetResult {
+  success: boolean;
+  status: number;
+  statusMessage?: string;
+}
+
+/**
+ * Encodes a 32/64-bit non-negative integer into protobuf varint wire bytes.
+ */
+export function encodeVarint(value: number | bigint): Uint8Array {
+  const bytes: number[] = [];
+  let val = BigInt(value);
+  while (val >= 0x80n) {
+    bytes.push(Number((val & 0x7fn) | 0x80n));
+    val >>= 7n;
+  }
+  bytes.push(Number(val & 0x7fn));
+  return new Uint8Array(bytes);
+}
+
+/**
+ * Decodes a protobuf varint from bytes at offset.
+ */
+export function decodeVarint(bytes: Uint8Array, offset: number): { value: number; bytesRead: number } {
+  let result = 0;
+  let shift = 0;
+  let count = 0;
+
+  while (offset + count < bytes.length) {
+    const b = bytes[offset + count];
+    count++;
+    result |= (b & 0x7f) << shift;
+    if ((b & 0x80) === 0) break;
+    shift += 7;
+    if (shift > 35) {
+      // For timestamps seconds, JS safe integers suffice.
+      break;
+    }
+  }
+
+  return { value: result, bytesRead: count };
+}
+
+/**
+ * Encodes RedeemResetRequest protobuf: field 1 (string token_id).
+ */
+export function encodeRedeemResetRequest(tokenId: string): Uint8Array {
+  const tokenBytes = new TextEncoder().encode(tokenId);
+  const tag = (1 << 3) | 2; // Field 1, Wire Type 2
+  const tagBytes = encodeVarint(tag);
+  const lenBytes = encodeVarint(tokenBytes.length);
+
+  const out = new Uint8Array(tagBytes.length + lenBytes.length + tokenBytes.length);
+  out.set(tagBytes, 0);
+  out.set(lenBytes, tagBytes.length);
+  out.set(tokenBytes, tagBytes.length + lenBytes.length);
+  return out;
+}
+
+/**
+ * Decodes a Timestamp submessage (field 1: int64 seconds).
+ */
+function decodeTimestamp(bytes: Uint8Array): number {
+  let offset = 0;
+  let seconds = 0;
+
+  while (offset < bytes.length) {
+    const { value: tag, bytesRead: tagLen } = decodeVarint(bytes, offset);
+    offset += tagLen;
+    const fieldNum = tag >> 3;
+    const wireType = tag & 0x7;
+
+    if (wireType === 0) {
+      const { value, bytesRead } = decodeVarint(bytes, offset);
+      offset += bytesRead;
+      if (fieldNum === 1) seconds = value;
+    } else if (wireType === 2) {
+      const { value: len, bytesRead } = decodeVarint(bytes, offset);
+      offset += bytesRead + len;
+    } else {
+      break;
+    }
+  }
+
+  return seconds;
+}
+
+/**
+ * Decodes a ConsumerResetToken submessage.
+ */
+function decodeConsumerResetToken(bytes: Uint8Array): GrokResetCoupon | null {
+  let offset = 0;
+  let tokenId = "";
+  let startSec = 0;
+  let endSec = 0;
+
+  while (offset < bytes.length) {
+    const { value: tag, bytesRead: tagLen } = decodeVarint(bytes, offset);
+    offset += tagLen;
+    const fieldNum = tag >> 3;
+    const wireType = tag & 0x7;
+
+    if (wireType === 2) {
+      const { value: len, bytesRead: lenRead } = decodeVarint(bytes, offset);
+      offset += lenRead;
+      const sub = bytes.subarray(offset, offset + len);
+      offset += len;
+
+      if (fieldNum === 10) {
+        tokenId = new TextDecoder("utf-8").decode(sub);
+      } else if (fieldNum === 20) {
+        startSec = decodeTimestamp(sub);
+      } else if (fieldNum === 30) {
+        endSec = decodeTimestamp(sub);
+      }
+    } else if (wireType === 0) {
+      const { bytesRead } = decodeVarint(bytes, offset);
+      offset += bytesRead;
+    } else {
+      break;
+    }
+  }
+
+  if (!tokenId) return null;
+
+  return {
+    tokenId,
+    validityStart: startSec > 0 ? new Date(startSec * 1000).toISOString() : "",
+    validityEnd: endSec > 0 ? new Date(endSec * 1000).toISOString() : "",
+  };
+}
+
+/**
+ * Decodes GetRemainingResetsResponse protobuf message: field 10 (repeated ConsumerResetToken).
+ */
+export function decodeGetRemainingResetsResponse(payload: Uint8Array): GrokResetCoupon[] {
+  const tokens: GrokResetCoupon[] = [];
+  let offset = 0;
+
+  while (offset < payload.length) {
+    const { value: tag, bytesRead: tagLen } = decodeVarint(payload, offset);
+    offset += tagLen;
+    const fieldNum = tag >> 3;
+    const wireType = tag & 0x7;
+
+    if (wireType === 2) {
+      const { value: len, bytesRead: lenRead } = decodeVarint(payload, offset);
+      offset += lenRead;
+      const sub = payload.subarray(offset, offset + len);
+      offset += len;
+
+      if (fieldNum === 10) {
+        const token = decodeConsumerResetToken(sub);
+        if (token) tokens.push(token);
+      }
+    } else if (wireType === 0) {
+      const { bytesRead } = decodeVarint(payload, offset);
+      offset += bytesRead;
+    } else {
+      break;
+    }
+  }
+
+  return tokens;
+}
+
+function buildGrokHeaders(accessToken: string): Record<string, string> {
+  return {
+    "Content-Type": "application/grpc-web+proto",
+    "X-Grpc-Web": "1",
+    "Accept": "application/grpc-web+proto",
+    "Authorization": `Bearer ${accessToken}`,
+    [XAI_GROK_COMPATIBILITY.headers.tokenAuth]: "xai-grok-cli",
+  };
+}
+
+/**
+ * Reads available Grok reset tokens for the authenticated xAI account.
+ */
+export async function getGrokRemainingResets(options: GetRemainingResetsOptions): Promise<{ tokens: GrokResetCoupon[] }> {
+  const fetchImpl = options.fetchFn ?? globalThis.fetch;
+  const endpoint = options.endpoint ?? GROK_GET_REMAINING_RESETS_ENDPOINT;
+  // BodyInit requires a plain ArrayBuffer backing store; the encoder's generic
+  // Uint8Array<ArrayBufferLike> is not assignable under TS 5.7 lib.dom types.
+  const emptyBody = encodeGrpcWebEnvelope(new Uint8Array(0)) as Uint8Array<ArrayBuffer>;
+
+  const res = await fetchImpl(endpoint, {
+    method: "POST",
+    headers: buildGrokHeaders(options.accessToken),
+    body: emptyBody,
+    signal: options.signal,
+  });
+
+  if (!res.ok) {
+    throw new Error(`GetRemainingResets HTTP error ${res.status}: ${res.statusText}`);
+  }
+
+  const rawBytes = new Uint8Array(await res.arrayBuffer());
+  const decoded = decodeGrpcWebResponse(rawBytes);
+
+  if (decoded.status !== 0) {
+    throw new GrpcWebError(decoded.status, decoded.statusMessage ?? "Unknown gRPC error");
+  }
+
+  if (decoded.messages.length === 0) {
+    return { tokens: [] };
+  }
+
+  return { tokens: decodeGetRemainingResetsResponse(decoded.messages[0]) };
+}
+
+/**
+ * Redeems a specific Grok reset token by tokenId.
+ */
+export async function redeemGrokResetCoupon(options: RedeemResetOptions): Promise<RedeemResetResult> {
+  const fetchImpl = options.fetchFn ?? globalThis.fetch;
+  const endpoint = options.endpoint ?? GROK_REDEEM_RESET_ENDPOINT;
+  const protoMessage = encodeRedeemResetRequest(options.tokenId);
+  const envelope = encodeGrpcWebEnvelope(protoMessage) as Uint8Array<ArrayBuffer>;
+
+  const res = await fetchImpl(endpoint, {
+    method: "POST",
+    headers: buildGrokHeaders(options.accessToken),
+    body: envelope,
+    signal: options.signal,
+  });
+
+  if (!res.ok) {
+    throw new Error(`RedeemReset HTTP error ${res.status}: ${res.statusText}`);
+  }
+
+  const rawBytes = new Uint8Array(await res.arrayBuffer());
+  const decoded = decodeGrpcWebResponse(rawBytes);
+
+  if (decoded.status !== 0) {
+    throw new GrpcWebError(decoded.status, decoded.statusMessage ?? "Unknown gRPC error");
+  }
+
+  return {
+    success: true,
+    status: decoded.status,
+    statusMessage: decoded.statusMessage,
+  };
+}
diff --git a/src/integrations/catalog-refresh.ts b/src/integrations/catalog-refresh.ts
index 8b89762f30..45e9b7a97b 100644
--- a/src/integrations/catalog-refresh.ts
+++ b/src/integrations/catalog-refresh.ts
@@ -10,7 +10,7 @@ import {
 /** Refresh only previously connected clients; a refused file never blocks its peers. */
 export async function refreshOwnedCatalogIntegrations(
   input: Omit<OwnedIntegrationRefreshInput, "clientId">,
-  clientIds: readonly IntegrationClientId[] = ["pi", "aside", "raycast"],
+  clientIds: readonly IntegrationClientId[] = ["pi", "aside", "raycast", "omo"],
 ): Promise<OwnedIntegrationRefreshOutcome[]> {
   let models: Promise<readonly ExportModel[]> | undefined;
   const loadModels = () => models ??= Promise.resolve().then(() =>
diff --git a/src/integrations/cline-document.ts b/src/integrations/cline-document.ts
new file mode 100644
index 0000000000..06ed337429
--- /dev/null
+++ b/src/integrations/cline-document.ts
@@ -0,0 +1,73 @@
+import { PARSE_FAILED, parseConfig } from "./config-io";
+import { serializeDocument, UnserializableValueError } from "./serialize";
+
+/** Private journal representation, never written into either Cline file. */
+export interface ClineRawPair { settings: string | null; catalog: string | null }
+
+export function isClineObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+export function encodeClinePair(pair: ClineRawPair): string | null {
+  return pair.settings === null && pair.catalog === null ? null : JSON.stringify(pair);
+}
+
+export function decodeClinePair(text: string | null): ClineRawPair {
+  if (text === null) return { settings: null, catalog: null };
+  let value: unknown;
+  try { value = JSON.parse(text); }
+  catch { throw new UnserializableValueError("invalid Cline snapshot bundle"); }
+  if (!isClineObject(value) || Object.keys(value).length !== 2
+    || !(value.settings === null || typeof value.settings === "string")
+    || !(value.catalog === null || typeof value.catalog === "string")) {
+    throw new UnserializableValueError("invalid Cline snapshot bundle");
+  }
+  return { settings: value.settings, catalog: value.catalog };
+}
+
+function nativeDocument(value: unknown): value is Record<string, unknown> {
+  return isClineObject(value) && (value.version === undefined || value.version === 1)
+    && (value.providers === undefined || isClineObject(value.providers));
+}
+
+export function parseClineDocument(text: string | null): unknown | typeof PARSE_FAILED {
+  try {
+    const pair = decodeClinePair(text);
+    const settings = parseConfig(pair.settings, "json");
+    const catalog = parseConfig(pair.catalog, "json");
+    if (!nativeDocument(settings) || !nativeDocument(catalog)
+      || (settings.modes !== undefined && !isClineObject(settings.modes))) return PARSE_FAILED;
+    return { settings, catalog };
+  } catch { return PARSE_FAILED; }
+}
+
+export function serializeClineDocument(value: unknown): string {
+  if (!isClineObject(value)) throw new UnserializableValueError("invalid Cline document");
+  const settings = value.settings ?? {};
+  const catalog = value.catalog ?? {};
+  if (!nativeDocument(settings) || !nativeDocument(catalog)) {
+    throw new UnserializableValueError("unsupported Cline document version or providers shape");
+  }
+  return JSON.stringify({
+    settings: serializeDocument({ version: 1, modes: {}, providers: {}, ...settings }, "json"),
+    catalog: serializeDocument({ version: 1, providers: {}, ...catalog }, "json"),
+  });
+}
+
+/** Cline saves these two fields during normal model selection. Keep only a still-routed choice. */
+export function preserveClineSelection(previous: unknown, next: unknown): void {
+  if (!isClineObject(previous) || !isClineObject(next)) return;
+  const entry = (document: Record<string, unknown>, part: string): Record<string, unknown> | undefined => {
+    const root = document[part];
+    const providers = isClineObject(root) ? root.providers : undefined;
+    return isClineObject(providers) && isClineObject(providers.opencodex) ? providers.opencodex : undefined;
+  };
+  const old = entry(previous, "settings");
+  const current = entry(next, "settings");
+  const models = entry(next, "catalog")?.models;
+  if (!current || !isClineObject(current.settings) || !old || !isClineObject(old.settings)) return;
+  if (typeof old.settings.model === "string" && isClineObject(models) && Object.hasOwn(models, old.settings.model)) {
+    current.settings.model = old.settings.model;
+  }
+  if (typeof old.updatedAt === "string") current.updatedAt = old.updatedAt;
+}
diff --git a/src/integrations/cline-io.ts b/src/integrations/cline-io.ts
new file mode 100644
index 0000000000..8107e70046
--- /dev/null
+++ b/src/integrations/cline-io.ts
@@ -0,0 +1,149 @@
+import { dirname, join, resolve } from "node:path";
+import { type IntegrationIO, type IntegrationTransaction, type ReadResult, type StatKind } from "./config-io";
+import type { IntegrationStateStore } from "./store";
+import { fingerprint, type OwnershipRecord } from "./ownership";
+import type { JournalEntry } from "./journal";
+import { parseClineTransaction } from "./cline-transaction";
+import { decodeClinePair, encodeClinePair, type ClineRawPair } from "./cline-document";
+
+/** Per-file atomic replacement with durable pair recovery, not simultaneous two-file visibility. */
+export class ClineTransactionError extends Error {
+  readonly residual = true;
+  constructor(readonly snapshotPath: string) {
+    super(`Cline has an unfinished two-file operation. Stop Cline and retry the mutation. If either file was edited, recover from ${snapshotPath} before retrying.`);
+  }
+}
+
+function sameRecord(a: unknown, b: unknown): boolean {
+  return JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+}
+
+export function clinePendingPath(store: IntegrationStateStore, configPath: string): string {
+  return join(store.root, `cline-pending-${fingerprint(resolve(configPath))}.json`);
+}
+
+/** Snapshot/ownership remain in the existing store. Only the filesystem projection changes. */
+export function createClineIO(
+  base: IntegrationIO,
+  configPath: string,
+  store: IntegrationStateStore,
+  recover = false,
+): IntegrationIO {
+  const catalogPath = join(dirname(configPath), "models.json");
+  const markerPath = clinePendingPath(store, configPath);
+  const targets = { settings: configPath, catalog: catalogPath };
+  const keys = ["settings", "catalog"] as const;
+  const kind = (path: string) => (base.lstatKind ?? base.statKind)(path);
+  const readPair = (): ClineRawPair => {
+    const pair: ClineRawPair = { settings: null, catalog: null };
+    for (const key of keys) {
+      const path = targets[key];
+      const state = kind(path);
+      if (state === "missing") continue;
+      if (state !== "file") throw new ClineTransactionError(markerPath);
+      const read = base.readText(path);
+      if (read.kind !== "text") throw new ClineTransactionError(markerPath);
+      pair[key] = read.text;
+    }
+    return pair;
+  };
+  const writeMember = (key: typeof keys[number], text: string | null): void => {
+    if (text === null) base.removeFile(targets[key]);
+    else { base.mkdirp(dirname(targets[key])); base.writeText(targets[key], text); }
+  };
+  const writePair = (pair: ClineRawPair): void => {
+    for (const key of keys) writeMember(key, pair[key]);
+  };
+  const readPending = (): IntegrationTransaction | null => {
+    if (kind(markerPath) === "missing") return null;
+    if (kind(markerPath) !== "file") throw new ClineTransactionError(markerPath);
+    const read = base.readText(markerPath);
+    if (read.kind !== "text") throw new ClineTransactionError(markerPath);
+    try {
+      return parseClineTransaction(read.text, configPath);
+    } catch { throw new ClineTransactionError(markerPath); }
+  };
+  const committed = (pending: IntegrationTransaction, current: ClineRawPair): boolean => {
+    let operation: JournalEntry | null;
+    let record: OwnershipRecord | undefined;
+    try { operation = store.findCommittedOperation(pending.entry.opId); record = store.readRecordsStrict().cline; }
+    catch { throw new ClineTransactionError(markerPath); }
+    return operation !== null && operation.clientId === "cline" && operation.configPath === configPath
+      && operation.resultFingerprint === pending.entry.resultFingerprint
+      && encodeClinePair(current) === pending.nextText
+      && sameRecord(record, pending.record);
+  };
+  const cleanup = (): void => {
+    // The append is the commit boundary. Cleanup failure never rolls back a committed pair.
+    try { base.removeFile(markerPath); } catch { /* The next mutation recognizes the committed record. */ }
+  };
+  const pendingSafe = (): boolean => {
+    const pending = readPending();
+    return pending === null || committed(pending, readPair());
+  };
+
+  if (resolve(configPath).toLowerCase() === resolve(catalogPath).toLowerCase()) throw new ClineTransactionError(markerPath);
+  if (recover) {
+    const pending = readPending();
+    if (pending) {
+      const current = readPair();
+      if (committed(pending, current)) cleanup();
+      else {
+        // A journaled but mixed/inconsistent result is not an interrupted uncommitted write.
+        try {
+          if (store.findCommittedOperation(pending.entry.opId)) throw new ClineTransactionError(markerPath);
+        } catch { throw new ClineTransactionError(markerPath); }
+        const before = decodeClinePair(pending.before);
+        const after = decodeClinePair(pending.nextText);
+        if (!keys.every(key => current[key] === before[key] || current[key] === after[key])) throw new ClineTransactionError(markerPath);
+        let record: OwnershipRecord | null;
+        try { record = store.readRecordsStrict().cline ?? null; }
+        catch { throw new ClineTransactionError(markerPath); }
+        if (!sameRecord(record, pending.priorRecord) && !sameRecord(record, pending.record)) throw new ClineTransactionError(markerPath);
+        try {
+          writePair(before);
+          if (pending.priorRecord) base.putRecord(pending.priorRecord);
+          else base.dropRecord("cline");
+          base.removeFile(markerPath);
+        } catch { throw new ClineTransactionError(markerPath); }
+      }
+    }
+  }
+
+  return {
+    ...base,
+    statKind: (path): StatKind => {
+      if (path !== configPath) return base.statKind(path);
+      try {
+        if (!pendingSafe()) return "failed";
+        const pair = readPair();
+        return pair.settings === null && pair.catalog === null ? "missing" : "file";
+      } catch { return "failed"; }
+    },
+    readText: (path): ReadResult => {
+      if (path !== configPath) return base.readText(path);
+      try {
+        if (!pendingSafe()) return { kind: "failed", code: "CLINE_PENDING" };
+        const text = encodeClinePair(readPair());
+        return text === null ? { kind: "missing" } : { kind: "text", text };
+      } catch { return { kind: "failed", code: "CLINE_UNSAFE" }; }
+    },
+    beginTransaction: transaction => {
+      if (transaction.entry.clientId !== "cline" || transaction.entry.configPath !== configPath) throw new ClineTransactionError(markerPath);
+      if (readPending() !== null) throw new ClineTransactionError(markerPath);
+      if (encodeClinePair(readPair()) !== transaction.before) throw new ClineTransactionError(markerPath);
+      base.mkdirp(store.root);
+      const { entry, before, nextText, record, priorRecord } = transaction;
+      base.writeText(markerPath, JSON.stringify({ entry, before, nextText, record, priorRecord }));
+    },
+    writeText: (path, text) => {
+      if (path !== configPath) return base.writeText(path, text);
+      writePair(decodeClinePair(text));
+    },
+    removeFile: path => {
+      if (path !== configPath) return base.removeFile(path);
+      writePair({ settings: null, catalog: null });
+    },
+    finishTransaction: cleanup,
+  };
+}
diff --git a/src/integrations/cline-transaction.ts b/src/integrations/cline-transaction.ts
new file mode 100644
index 0000000000..6c6e95dc1b
--- /dev/null
+++ b/src/integrations/cline-transaction.ts
@@ -0,0 +1,42 @@
+import type { IntegrationTransaction } from "./config-io";
+import { decodeClinePair, encodeClinePair, isClineObject } from "./cline-document";
+import { isJournalEntry } from "./journal";
+import { fingerprint, isOwnershipRecord, type OwnershipRecord } from "./ownership";
+import { validRefreshablePaths } from "./ownership-policy";
+
+const FRAGMENTS = [["catalog", "providers", "opencodex"], ["settings", "providers", "opencodex"]];
+const CONTAINERS = new Set(["catalog", "settings", "catalog\0providers", "settings\0providers"]);
+
+function clineRecord(value: unknown, configPath: string): value is OwnershipRecord | null {
+  if (value === null) return true;
+  if (!isOwnershipRecord(value) || value.clientId !== "cline" || value.configPath !== configPath) return false;
+  if (value.fragmentPaths.length !== FRAGMENTS.length
+    || !FRAGMENTS.every(expected => value.fragmentPaths.some(path =>
+      path.length === expected.length && path.every((segment, index) => segment === expected[index])))) return false;
+  if (value.createdContainers?.some(path => !CONTAINERS.has(path))) return false;
+  if (value.refreshablePaths !== undefined
+    && !validRefreshablePaths({ clientId: "cline", fragments: [] }, value.refreshablePaths)) return false;
+  return value.protectedBlockFingerprint === undefined || value.refreshablePaths !== undefined;
+}
+
+/** Validate all recovery authority before a file or ownership record can be replaced. */
+export function parseClineTransaction(text: string, configPath: string): IntegrationTransaction {
+  const value: unknown = JSON.parse(text);
+  if (!isClineObject(value) || !isJournalEntry(value.entry)
+    || value.entry.clientId !== "cline" || value.entry.configPath !== configPath
+    || !(typeof value.before === "string" || value.before === null)
+    || !(typeof value.nextText === "string" || value.nextText === null)
+    || !clineRecord(value.record, configPath) || !clineRecord(value.priorRecord, configPath)
+    || !clineRecord(value.entry.priorRecord, configPath)
+    || JSON.stringify(value.entry.priorRecord) !== JSON.stringify(value.priorRecord)
+    || (value.record !== null && (value.record.opId !== value.entry.opId || value.record.appliedAt !== value.entry.at))) {
+    throw new Error("invalid Cline transaction metadata");
+  }
+  if (encodeClinePair(decodeClinePair(value.before)) !== value.before
+    || encodeClinePair(decodeClinePair(value.nextText)) !== value.nextText
+    || value.entry.resultAbsent !== (value.nextText === null)
+    || value.entry.resultFingerprint !== (value.nextText === null ? "" : fingerprint(value.nextText))) {
+    throw new Error("inconsistent Cline transaction result");
+  }
+  return { entry: value.entry, before: value.before, nextText: value.nextText, record: value.record, priorRecord: value.priorRecord };
+}
diff --git a/src/integrations/config-io.ts b/src/integrations/config-io.ts
index dd61fcf351..8a1e1480ec 100644
--- a/src/integrations/config-io.ts
+++ b/src/integrations/config-io.ts
@@ -7,7 +7,7 @@
  *
  * Design of record: devlog/_fin/260802_client_toggle_api/021 §5-6.
  */
-import { mkdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { lstatSync, mkdirSync, readFileSync, rmSync, statSync } from "node:fs";
 import type { ConfigFormat } from "../clients/config-export";
 import { MAX_JSON_NESTING } from "./serialize";
 import { atomicWriteFile } from "../config";
@@ -200,6 +200,8 @@ export interface IntegrationIO {
   readText: (path: string) => ReadResult;
   /** `failed` is distinct from `missing` for the same reason. */
   statKind: (path: string) => StatKind;
+  /** Optional no-follow probe for paired-file clients. */
+  lstatKind?: (path: string) => StatKind;
   writeText: (path: string, text: string) => void;
   removeFile: (path: string) => void;
   mkdirp: (path: string) => void;
@@ -208,6 +210,16 @@ export interface IntegrationIO {
   appendJournal: (entry: JournalEntry) => void;
   putRecord: (record: OwnershipRecord) => void;
   dropRecord: (clientId: IntegrationClientId) => void;
+  beginTransaction?: (transaction: IntegrationTransaction) => void;
+  finishTransaction?: () => void;
+}
+
+export interface IntegrationTransaction {
+  entry: JournalEntry;
+  before: string | null;
+  nextText: string | null;
+  record: OwnershipRecord | null;
+  priorRecord: OwnershipRecord | null;
 }
 
 export type TargetState =
@@ -240,6 +252,14 @@ export function loadTarget(io: IntegrationIO, configPath: string): TargetState {
  */
 export function fileIO(): Omit<IntegrationIO, "appendJournal" | "putRecord" | "dropRecord"> {
   return {
+    lstatKind: path => {
+      try {
+        const stats = lstatSync(path);
+        return stats.isFile() ? "file" : stats.isDirectory() ? "dir" : "other";
+      } catch (error) {
+        return (error as NodeJS.ErrnoException).code === "ENOENT" ? "missing" : "failed";
+      }
+    },
     readText: path => {
       try {
         return { kind: "text", text: readFileSync(path, "utf8") };
@@ -334,4 +354,3 @@ export function assertIntegrationWriteOwnership(
     + "of sharing the mount.",
   );
 }
-
diff --git a/src/integrations/journal.ts b/src/integrations/journal.ts
index c23a293211..9c4444d5e8 100644
--- a/src/integrations/journal.ts
+++ b/src/integrations/journal.ts
@@ -16,7 +16,7 @@ import { randomUUID } from "node:crypto";
 import { appendFileSync, existsSync, readFileSync, readdirSync, rmSync } from "node:fs";
 import { join, resolve, sep } from "node:path";
 import { atomicWriteFile } from "../config";
-import { ensureDir, fingerprint, integrationsDir, type OwnershipRecord } from "./ownership";
+import { ensureDir, fingerprint, integrationsDir, isOwnershipRecord, type OwnershipRecord } from "./ownership";
 import { isIntegrationClientId, type IntegrationClientId } from "./registry";
 
 /**
@@ -231,6 +231,48 @@ export function findOperation(opId: string, dir: string = integrationsDir()): Jo
   return listOperations(undefined, Number.MAX_SAFE_INTEGER, dir).find(row => row.opId === opId) ?? null;
 }
 
+export function isJournalEntry(value: unknown): value is JournalEntry {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const entry = value as Record<string, unknown>;
+  const snapshot = entry.snapshot;
+  return typeof entry.opId === "string" && /^[a-zA-Z0-9-]+$/.test(entry.opId)
+    && typeof entry.clientId === "string" && isIntegrationClientId(entry.clientId)
+    && typeof entry.configPath === "string" && entry.configPath.length > 0
+    && typeof entry.at === "string" && Number.isFinite(Date.parse(entry.at))
+    && typeof entry.kind === "string" && ["apply", "refresh", "disable", "restore", "overwrite"].includes(entry.kind)
+    && typeof entry.resultAbsent === "boolean"
+    && (entry.resultAbsent ? entry.resultFingerprint === "" : typeof entry.resultFingerprint === "string" && /^[a-f0-9]{16}$/.test(entry.resultFingerprint))
+    && (entry.priorRecord === null || isOwnershipRecord(entry.priorRecord))
+    && snapshot !== null && typeof snapshot === "object" && !Array.isArray(snapshot)
+    && ("kind" in snapshot && (snapshot.kind === "none" || snapshot.kind === "expired"
+      || (snapshot.kind === "stored" && "relPath" in snapshot && typeof snapshot.relPath === "string" && snapshot.relPath.length > 0)));
+}
+
+/** Commit evidence includes retired rows. Read/parse failures must never become "not committed". */
+export function findCommittedOperation(opId: string, dir: string = integrationsDir()): JournalEntry | null {
+  let raw: string;
+  try { raw = readFileSync(journalPath(dir), "utf8"); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw new Error("integration journal cannot be read for recovery");
+  }
+  let found: JournalEntry | null = null;
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    let row: unknown;
+    try { row = JSON.parse(line); }
+    catch { throw new Error("integration journal is incomplete for recovery"); }
+    if (isTombstone(row)) {
+      if (!row.tombstone || typeof row.at !== "string" || !Number.isFinite(Date.parse(row.at))
+        || typeof row.by !== "string" || !row.by) throw new Error("integration journal contains invalid recovery metadata");
+      continue;
+    }
+    if (!isJournalEntry(row)) throw new Error("integration journal contains invalid recovery metadata");
+    if (row.opId === opId) found = row;
+  }
+  return found;
+}
+
 /** Resolves the tag against what is actually on disk now. */
 export function readSnapshot(
   entry: JournalEntry,
diff --git a/src/integrations/omp-yaml-source.ts b/src/integrations/omp-yaml-source.ts
index dc2c19275b..bfe6d05834 100644
--- a/src/integrations/omp-yaml-source.ts
+++ b/src/integrations/omp-yaml-source.ts
@@ -29,7 +29,20 @@ interface MissingEntry {
   insertAt: number;
 }
 
-type LocatedPath = { kind: "existing"; entry: LocatedEntry } | { kind: "missing"; entry: MissingEntry };
+interface ReplaceLineEntry {
+  lines: readonly SourceLine[];
+  index: number;
+  indent: number;
+  missingDepth: number;
+}
+
+type LocatedPath =
+  | { kind: "existing"; entry: LocatedEntry }
+  | { kind: "missing"; entry: MissingEntry }
+  // `key: {}` — an empty inline map the block-key scanner cannot see (#4260).
+  | { kind: "replace-line"; entry: ReplaceLineEntry }
+  // A populated flow container. Still refused, but nameable as its own cause.
+  | { kind: "unsupported-style" };
 
 export type YamlFragmentMutation =
   | { kind: "upsert"; value: unknown }
@@ -82,6 +95,61 @@ function isPlainBlockKey(line: string, indent: number, key: string): boolean {
   return new RegExp(`^${regexpEscape(key)}:[ ]*(?:#.*)?$`, "u").test(rest);
 }
 
+/** The inline value written after `key:` on this line, or null if the key is not here. */
+function inlineValueAfterKey(line: string, indent: number, key: string): string | null {
+  const spaces = leadingSpaces(line);
+  if (spaces !== indent) return null;
+  const rest = line.slice(indent);
+  const head = `${key}:`;
+  // Compared as text, not as a pattern: a path segment is arbitrary user data,
+  // and brace escaping inside a `u`-flag regex is its own hazard.
+  if (!rest.startsWith(head)) return null;
+  return rest.slice(head.length).trim();
+}
+
+/** Exactly `key: {}` (any inner spacing) — an empty inline map, no inline comment. */
+function isEmptyInlineMapKey(line: string, indent: number, key: string): boolean {
+  const value = inlineValueAfterKey(line, indent, key);
+  if (value === null) return false;
+  return value.startsWith("{") && value.endsWith("}") && value.slice(1, -1).trim().length === 0;
+}
+
+/** `key: { ... }` or `key: [ ... ]` on one line: content we would have to re-render. */
+function isPopulatedInlineFlowKey(line: string, indent: number, key: string): boolean {
+  const value = inlineValueAfterKey(line, indent, key);
+  if (value === null) return false;
+  if (!value.startsWith("{") && !value.startsWith("[")) return false;
+  return !isEmptyInlineMapKey(line, indent, key);
+}
+
+/**
+ * A plain block key whose first child opens a flow collection:
+ *
+ *     providers:
+ *       { native: { ... } }
+ *
+ * DSH writes this shape itself. The walk passes straight through it — the key
+ * line is a plain block key and `containerEnd` does not stop at `}` — so the
+ * refusal used to surface only as a failed re-parse at the very end and got
+ * reported as a comment or formatting problem that was not there (#4260).
+ */
+function firstChildOpensFlow(
+  lines: readonly SourceLine[],
+  start: number,
+  end: number,
+  parentIndent: number,
+): boolean {
+  for (let index = start + 1; index < end; index += 1) {
+    const body = lines[index]!.body;
+    if (isBlank(body) || isComment(body)) continue;
+    const spaces = leadingSpaces(body);
+    if (spaces === null || spaces <= parentIndent) continue;
+    const trimmed = body.trimStart();
+    return trimmed.startsWith("{") || trimmed.startsWith("[");
+  }
+  return false;
+}
+
 function containerEnd(lines: readonly SourceLine[], start: number, indent: number): number | null {
   for (let index = start + 1; index < lines.length; index += 1) {
     const body = lines[index]!.body;
@@ -193,9 +261,24 @@ function locatePath(text: string, parsed: unknown, path: readonly string[]): Loc
     if (matches.length > 1) return null;
     prefix.push(path[depth]!);
     if (matches.length === 0) {
+      const seen = readPath(parsed, prefix);
+      // An empty inline map is the one flow shape we can adopt: rewriting that
+      // single line into block form adds our subtree and re-renders nothing the
+      // user wrote, because there is nothing in it (#4260).
+      const inline: number[] = [];
+      const populatedFlow: number[] = [];
+      for (let index = rangeStart; index < rangeEnd; index += 1) {
+        const body = lines[index]!.body;
+        if (isEmptyInlineMapKey(body, indent, path[depth]!)) inline.push(index);
+        else if (isPopulatedInlineFlowKey(body, indent, path[depth]!)) populatedFlow.push(index);
+      }
+      if (inline.length === 1 && isPlainRecord(seen) && Object.keys(seen).length === 0) {
+        return { kind: "replace-line", entry: { lines, index: inline[0]!, indent, missingDepth: depth } };
+      }
+      if (populatedFlow.length === 1 && seen !== undefined) return { kind: "unsupported-style" };
       // The parser saw this key through syntax we do not patch (quoted/flow,
       // merge aliases, or an ambiguous indentation shape).
-      if (readPath(parsed, prefix) !== undefined) return null;
+      if (seen !== undefined) return null;
       const insertAt = rangeEnd < lines.length ? lines[rangeEnd]!.start : text.length;
       return { kind: "missing", entry: { lines, missingDepth: depth, indent, insertAt } };
     }
@@ -209,7 +292,20 @@ function locatePath(text: string, parsed: unknown, path: readonly string[]): Loc
       if (leafEnd === null) return null;
       return { kind: "existing", entry: { lines, index, indent, endIndex: leafEnd } };
     }
-    if (!isPlainRecord(readPath(parsed, prefix))) return null;
+    const container = readPath(parsed, prefix);
+    // `key:` with no children parses as null. The key line matched, so the
+    // missing-key branch above never runs, and `isPlainRecord(null)` is false —
+    // so an empty container used to refuse the whole document (#4260). Insert
+    // our subtree as its first child instead.
+    if (container === null) {
+      const insertAt = end < lines.length ? lines[end]!.start : text.length;
+      return {
+        kind: "missing",
+        entry: { lines, missingDepth: depth + 1, indent: indent + 2, insertAt },
+      };
+    }
+    if (!isPlainRecord(container)) return null;
+    if (firstChildOpensFlow(lines, index, end, indent)) return { kind: "unsupported-style" };
     rangeStart = index + 1;
     rangeEnd = end;
     parentIndent = indent;
@@ -241,7 +337,7 @@ function upsertSource(
   value: unknown,
 ): string | null {
   const located = locatePath(text, parsed, path);
-  if (located === null) return null;
+  if (located === null || located.kind === "unsupported-style") return null;
   const eol = lineEnding(text);
   if (located.kind === "existing") {
     const { lines, index, indent, endIndex } = located.entry;
@@ -250,6 +346,13 @@ function upsertSource(
     const candidate = `${text.slice(0, startOffset)}${rendered({ [path[path.length - 1]!]: value }, indent, eol)}${text.slice(endOffset)}`;
     return preserveFinalNewline(candidate, text, eol);
   }
+  if (located.kind === "replace-line") {
+    const { lines, index, indent, missingDepth } = located.entry;
+    const startOffset = lines[index]!.start;
+    const endOffset = index + 1 < lines.length ? lines[index + 1]!.start : text.length;
+    const insertion = rendered(nestedValue(path.slice(missingDepth), value), indent, eol);
+    return preserveFinalNewline(`${text.slice(0, startOffset)}${insertion}${text.slice(endOffset)}`, text, eol);
+  }
 
   const { missingDepth, indent, insertAt } = located.entry;
   const prefix = insertAt > 0 && !text.slice(0, insertAt).endsWith("\n") ? eol : "";
@@ -338,6 +441,22 @@ export function patchYamlFragmentSource(
   return patched !== null && semanticallyMatches(patched, expected) ? patched : null;
 }
 
+/**
+ * True when a refusal on this path is caused by a flow-style container rather
+ * than by comments or formatting we would have to re-render. DSH writes that
+ * shape itself, so naming it is the difference between an actionable message
+ * and one that sends the user hunting for a comment that is not there (#4260).
+ */
+export function yamlFragmentUnsupportedStyle(text: string, path: readonly string[]): boolean {
+  let parsed: unknown;
+  try {
+    parsed = text.trim().length === 0 ? {} : Bun.YAML.parse(text);
+  } catch {
+    return false;
+  }
+  return locatePath(text, parsed, path)?.kind === "unsupported-style";
+}
+
 /** Backward-compatible OMP wrapper around the generic path patcher. */
 export function patchOmpYamlSource(
   text: string,
diff --git a/src/integrations/ownership-policy.ts b/src/integrations/ownership-policy.ts
index 508910955f..a0cf52bf61 100644
--- a/src/integrations/ownership-policy.ts
+++ b/src/integrations/ownership-policy.ts
@@ -63,6 +63,10 @@ function cloneFragment(fragment: ManagedFragment): ManagedFragment {
 export function refreshablePathsOf(
   contribution: ManagedContribution,
 ): readonly (readonly string[])[] {
+  if (contribution.clientId === "cline") return [
+    ["settings", "providers", OPENCODE_PROVIDER_ID, "updatedAt"],
+    ["settings", "providers", OPENCODE_PROVIDER_ID, "settings", "model"],
+  ];
   if (contribution.clientId !== "zcode") return [];
   const fragment = contribution.fragments.find(candidate => (
     candidate.path.length === 2
@@ -90,6 +94,9 @@ export function validRefreshablePaths(
   contribution: ManagedContribution,
   value: unknown,
 ): value is readonly (readonly string[])[] {
+  if (contribution.clientId === "cline") {
+    return JSON.stringify(value) === JSON.stringify(refreshablePathsOf(contribution));
+  }
   if (contribution.clientId !== "zcode" || !Array.isArray(value) || value.length === 0) {
     return false;
   }
diff --git a/src/integrations/ownership.ts b/src/integrations/ownership.ts
index 537e53fd64..61d0bda74b 100644
--- a/src/integrations/ownership.ts
+++ b/src/integrations/ownership.ts
@@ -101,6 +101,42 @@ export interface OwnershipRecord {
   opId: string;
 }
 
+/** Recovery needs proven metadata, unlike the tolerant status-reader fallback. */
+export function isOwnershipRecord(value: unknown): value is OwnershipRecord {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const record = value as Record<string, unknown>;
+  const hash = (item: unknown) => typeof item === "string" && /^[a-f0-9]{16}$/.test(item);
+  const paths = (item: unknown) => Array.isArray(item) && item.every(path =>
+    Array.isArray(path) && path.length > 0 && path.every(key => typeof key === "string" && key.length > 0));
+  return typeof record.clientId === "string" && record.clientId.length > 0
+    && typeof record.configPath === "string" && record.configPath.length > 0
+    && typeof record.opId === "string" && record.opId.length > 0
+    && typeof record.appliedAt === "string" && Number.isFinite(Date.parse(record.appliedAt))
+    && hash(record.fileFingerprint) && hash(record.blockFingerprint)
+    && paths(record.fragmentPaths) && (record.fragmentPaths as unknown[]).length > 0
+    && ["semanticBlockFingerprint", "protectedBlockFingerprint", "semanticProtectedBlockFingerprint"]
+      .every(key => record[key] === undefined || hash(record[key]))
+    && (record.refreshablePaths === undefined || paths(record.refreshablePaths))
+    && (record.createdContainers === undefined || (Array.isArray(record.createdContainers)
+      && record.createdContainers.every(path => typeof path === "string")));
+}
+
+/** Missing is empty; corrupt/unreadable ownership is uncertainty and must abort recovery. */
+export function readRecordsStrict(dir: string = integrationsDir()): Partial<Record<IntegrationClientId, OwnershipRecord>> {
+  let text: string;
+  try { text = readFileSync(recordsPath(dir), "utf8"); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
+    throw new Error("integration ownership cannot be read for recovery");
+  }
+  try {
+    const parsed: unknown = JSON.parse(text);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)
+      || !Object.entries(parsed).every(([key, value]) => isOwnershipRecord(value) && value.clientId === key)) throw new Error();
+    return parsed as Partial<Record<IntegrationClientId, OwnershipRecord>>;
+  } catch { throw new Error("integration ownership is invalid for recovery"); }
+}
+
 /**
  * The integrations directory itself. Every primitive takes THIS path, never a
  * config root, so a caller cannot accidentally produce
diff --git a/src/integrations/registry.ts b/src/integrations/registry.ts
index 8d67ac83a1..4181316207 100644
--- a/src/integrations/registry.ts
+++ b/src/integrations/registry.ts
@@ -12,6 +12,8 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import {
   ClientPathError,
+  clineConfigPath,
+  clineSettingsDir,
   EXPORT_CLIENTS,
   asideAccountDir,
   asideConfigPath,
@@ -26,6 +28,8 @@ import {
   kimiHomeDir,
   mcodeConfigPath,
   mcodeHomeDir,
+  omoAgentDir,
+  omoConfigPath,
   ompAgentDir,
   ompModelsConfigPath,
   opencodeGlobalConfigPath,
@@ -280,6 +284,29 @@ export const INTEGRATION_CLIENTS: Record<IntegrationClientId, IntegrationClientS
      */
     detectDir: (env = process.env, home = homedir()) => raycastAiDir(env, home),
   },
+  omo: {
+    id: "omo",
+    configPath: (env = process.env, home = homedir()) => omoConfigPath(env, home),
+    /*
+     * The AGENT directory, not `~/.omo`. The v4 launcher wrapper creates
+     * `~/.omo` to hold `binary-runtime` without ever creating `agent/`, so
+     * detecting on the parent reports an omo v5 install that is not there --
+     * and `installed` is what stops apply from writing a catalog for an engine
+     * that will never read it. Prime's agent directory and Aside's account
+     * directory are the same shape; Pi's parent-directory check is the odd one.
+     *
+     * No `sourcePreservingYaml` (JSON), no `writerLock` (single writer), and no
+     * `resolvePaths` -- unlike Aside, both omo paths are a pure function of env
+     * and home, so reading them in sequence cannot straddle a state change.
+     */
+    detectDir: (env = process.env, home = homedir()) => omoAgentDir(env, home),
+  },
+  cline: {
+    id: "cline",
+    configPath: (env = process.env, home = homedir()) => clineConfigPath(env, home),
+    detectDir: (env = process.env, home = homedir()) => clineSettingsDir(env, home),
+    writerLock: { suffix: ".lock" },
+  },
 };
 
 export const INTEGRATION_CLIENT_IDS: readonly IntegrationClientId[] =
diff --git a/src/integrations/state.ts b/src/integrations/state.ts
index 0249987027..c1c9096140 100644
--- a/src/integrations/state.ts
+++ b/src/integrations/state.ts
@@ -8,6 +8,8 @@
  *
  * Design of record: devlog/_fin/260802_client_toggle_api/021 §3.
  */
+import { createClineIO } from "./cline-io";
+import { parseClineDocument } from "./cline-document";
 import { ClientPathError, EXPORT_CLIENTS, opencodeProxyBaseUrl, type ExportModel, type ManagedContribution } from "../clients/config-export";
 import type { OcxConfig } from "../types";
 import { PARSE_FAILED, loadTarget, parseConfig, type IntegrationIO } from "./config-io";
@@ -487,7 +489,7 @@ function retentionOf(
 export function readIntegrationState(input: IntegrationStateInput): IntegrationStatus {
   const store = input.store ?? createIntegrationStateStore();
   retryPendingPrunesOnce(store);
-  const io = input.io ?? store.io();
+  let io = input.io ?? store.io();
   const spec = INTEGRATION_CLIENTS[input.clientId];
   const exportSpec = EXPORT_CLIENTS[input.clientId];
   const retention = retentionOf(input.clientId, store);
@@ -529,6 +531,7 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
     };
   }
 
+  if (input.clientId === "cline") io = createClineIO(io, configPath, store);
   const target = loadTarget(io, configPath);
   if (!target.ok) {
     return {
@@ -541,7 +544,7 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
     };
   }
 
-  const parsed = parseConfig(target.before, exportSpec.format);
+  const parsed = input.clientId === "cline" ? parseClineDocument(target.before) : parseConfig(target.before, exportSpec.format);
   const contribution = exportSpec.buildContribution(exportContextOf(input));
   const record = store.readRecords()[input.clientId] ?? null;
   const { state, reason } = classifyIntegration({
diff --git a/src/integrations/store.ts b/src/integrations/store.ts
index a8c9310531..4e04fd3021 100644
--- a/src/integrations/store.ts
+++ b/src/integrations/store.ts
@@ -17,6 +17,7 @@ import {
   clearPruneFailure,
   countSnapshots,
   findOperation,
+  findCommittedOperation,
   listOperations,
   markPruneFailure,
   pruneSnapshots,
@@ -32,6 +33,7 @@ import {
   deleteRecord,
   integrationsDir,
   readRecords,
+  readRecordsStrict,
   writeRecord,
   type OwnershipRecord,
 } from "./ownership";
@@ -41,6 +43,7 @@ export interface IntegrationStateStore {
   /** The integrations directory itself — never a config root to resolve again. */
   readonly root: string;
   readRecords(): Partial<Record<IntegrationClientId, OwnershipRecord>>;
+  readRecordsStrict(): Partial<Record<IntegrationClientId, OwnershipRecord>>;
   putRecord(record: OwnershipRecord): void;
   dropRecord(clientId: IntegrationClientId): void;
   appendJournal(entry: JournalEntry): void;
@@ -48,6 +51,7 @@ export interface IntegrationStateStore {
   retireOperation(record: JournalTombstone): void;
   listOperations(clientId?: IntegrationClientId, limit?: number): JournalEntry[];
   findOperation(opId: string): JournalEntry | null;
+  findCommittedOperation(opId: string): JournalEntry | null;
   captureSnapshot(clientId: IntegrationClientId, opId: string, text: string | null): SnapshotRef;
   readSnapshot(entry: JournalEntry):
     | { kind: "none" }
@@ -79,12 +83,14 @@ export function createIntegrationStateStore(root: string = integrationsDir()): I
   const store: IntegrationStateStore = {
     root: dir,
     readRecords: () => readRecords(dir),
+    readRecordsStrict: () => readRecordsStrict(dir),
     putRecord: record => writeRecord(record, dir),
     dropRecord: clientId => deleteRecord(clientId, dir),
     appendJournal: entry => appendOperation(entry, dir),
     retireOperation: record => appendTombstone(record, dir),
     listOperations: (clientId, limit) => listOperations(clientId, limit, dir),
     findOperation: opId => findOperation(opId, dir),
+    findCommittedOperation: opId => findCommittedOperation(opId, dir),
     captureSnapshot: (clientId, opId, text) => captureSnapshot(clientId, opId, text, dir),
     readSnapshot: entry => readSnapshot(entry, dir),
     countSnapshots: clientId => countSnapshots(clientId, dir),
diff --git a/src/integrations/writer.ts b/src/integrations/writer.ts
index 514fbc3220..0bac4da13a 100644
--- a/src/integrations/writer.ts
+++ b/src/integrations/writer.ts
@@ -10,6 +10,8 @@
  * Design of record: devlog/_fin/260802_client_toggle_api/030 and 031.
  */
 import { homedir } from "node:os";
+import { createClineIO, ClineTransactionError } from "./cline-io";
+import { parseClineDocument, serializeClineDocument, preserveClineSelection } from "./cline-document";
 import { dirname } from "node:path";
 import { EXPORT_CLIENTS, type ExportModel, type ManagedContribution } from "../clients/config-export";
 import { shouldInjectApiAuthHeader } from "../codex/inject";
@@ -35,7 +37,29 @@ import { serializeDocument, UnserializableValueError } from "./serialize";
 import { ClientPathError } from "../clients/config-export";
 import { matchesOperationResult, newOpId, type JournalEntry } from "./journal";
 import { createIntegrationStateStore, type IntegrationStateStore } from "./store";
-import { patchYamlFragmentSource, sourcePrunableYamlContainers } from "./omp-yaml-source";
+import {
+  patchYamlFragmentSource,
+  sourcePrunableYamlContainers,
+  yamlFragmentUnsupportedStyle,
+} from "./omp-yaml-source";
+
+/**
+ * "comments or formatting" used to be the only refusal this path could report.
+ * For a flow-style container that names a cause which is not in the file, and
+ * DSH writes that shape itself, so the misdirection was routine rather than
+ * exotic: users went looking for a comment that was never there (#4260).
+ */
+function yamlRefusalReason(
+  source: string,
+  path: readonly string[],
+  configPath: string,
+  outcome: string,
+): string {
+  if (yamlFragmentUnsupportedStyle(source, path)) {
+    return `${configPath} writes ${path.join(".")} as a flow mapping or sequence, a YAML style opencodex will not re-render, so ${outcome}`;
+  }
+  return `${configPath} uses YAML source opencodex cannot patch without risking unrelated comments or formatting, so ${outcome}`;
+}
 import { withIntegrationWriterLock, type IntegrationWriterLockSeams } from "./writer-lock";
 
 export type RefusalReason =
@@ -126,13 +150,19 @@ interface CommitArgs {
  */
 function commit(args: CommitArgs): WriteOutcome {
   const { io, clientId, configPath } = args;
+  let transactionStarted = false;
   try {
+    if (io.beginTransaction) {
+      io.beginTransaction(args);
+      transactionStarted = true;
+    }
     if (args.nextText === null) io.removeFile(configPath);
     else {
       io.mkdirp(dirname(configPath));
       io.writeText(configPath, args.nextText);
     }
   } catch (error) {
+    if (transactionStarted) return compensate(args, error, "could not write both Cline files");
     return refuse(clientId, "write_failed", args.state, messageOf(error), args.snapshotPath);
   }
   try {
@@ -146,6 +176,7 @@ function commit(args: CommitArgs): WriteOutcome {
   } catch (error) {
     return compensate(args, error, "could not append the journal row");
   }
+  io.finishTransaction?.();
   return {
     ok: true,
     changed: true,
@@ -176,6 +207,7 @@ function compensate(args: CommitArgs, cause: unknown, what: string): WriteRefuse
       message: `${what}, and the change could not be rolled back. The file or its ownership record is in an intermediate state; the backup is at ${args.snapshotPath ?? "(none)"}.`,
     };
   }
+  io.finishTransaction?.();
   return refuse(clientId, "write_failed", args.state, `${what}; the change was rolled back. Cause: ${messageOf(cause)}`, args.snapshotPath);
 }
 
@@ -198,7 +230,7 @@ function sourcePreservingFragmentValue(
 /** Shared preflight: detect, gate, read, parse and classify. */
 function preflight(input: IntegrationWriteInput) {
   const store = input.store ?? createIntegrationStateStore();
-  const io = input.io ?? defaultIntegrationIO(store);
+  let io = input.io ?? defaultIntegrationIO(store);
   const clientId = input.clientId;
   const spec = INTEGRATION_CLIENTS[clientId];
   const exportSpec = EXPORT_CLIENTS[clientId];
@@ -224,7 +256,11 @@ function preflight(input: IntegrationWriteInput) {
     const resolved = input.resolvedPaths ?? resolveIntegrationPaths(clientId, input.env, input.home);
     configPath = resolved.configPath;
     detectDir = resolved.detectDir;
+    if (clientId === "cline") io = createClineIO(io, configPath, store, true);
   } catch (error) {
+    if (error instanceof ClineTransactionError) {
+      return { failed: { ...refuse(clientId, "unsafe", "unsafe", error.message, error.snapshotPath), residual: true } } as const;
+    }
     if (!(error instanceof ClientPathError)) throw error;
     return { failed: refuse(clientId, "unsafe", "unsafe", error.message) } as const;
   }
@@ -240,7 +276,7 @@ function preflight(input: IntegrationWriteInput) {
     } as const;
   }
   const before = target.before;
-  const parsed = parseConfig(before, exportSpec.format);
+  const parsed = clientId === "cline" ? parseClineDocument(before) : parseConfig(before, exportSpec.format);
   if (parsed === PARSE_FAILED) {
     return { failed: refuse(clientId, "unsafe", "unsafe",
       `${configPath} could not be parsed, or holds something opencodex cannot rewrite without changing it (a non-finite number, a large integer or a tiny one a rewrite would round, -0, a duplicate member, or nesting deeper than 1000 levels)`) } as const;
@@ -387,6 +423,7 @@ function applyOrRefreshIntegration(
     // every container exists and "did we create this?" is unanswerable.
     created = createdContainerPaths(base, contribution);
     const nextDocument = mergeContribution(base, contribution);
+    if (clientId === "cline") preserveClineSelection(parsed, nextDocument);
     if (spec.sourcePreservingYaml && before !== null) {
       const value = sourcePreservingFragmentValue(contribution, spec.sourcePreservingYaml.path);
       const patched = value === undefined
@@ -399,11 +436,11 @@ function applyOrRefreshIntegration(
           );
       if (patched === null) {
         return refuse(clientId, "unsafe", "unsafe",
-          `${configPath} uses YAML source opencodex cannot patch without risking unrelated comments or formatting, so it was left alone`);
+          yamlRefusalReason(before, spec.sourcePreservingYaml.path, configPath, "it was left alone"));
       }
       text = patched;
     } else {
-      text = serializeDocument(nextDocument, exportSpec.format);
+      text = clientId === "cline" ? serializeClineDocument(nextDocument) : serializeDocument(nextDocument, exportSpec.format);
     }
   } catch (error) {
     if (error instanceof AmbiguousSelectorError) {
@@ -536,7 +573,7 @@ export function disableIntegration(input: IntegrationWriteInput): WriteOutcome {
     : recordedCreated;
   if (prunableCreated === null) {
     return refuse(clientId, "unsafe", "unsafe",
-      `${configPath} uses YAML source opencodex cannot patch without risking unrelated comments or formatting, so nothing was removed`);
+      yamlRefusalReason(before ?? "", spec.sourcePreservingYaml!.path, configPath, "nothing was removed"));
   }
   let doc: unknown;
   let removed: boolean;
@@ -559,11 +596,11 @@ export function disableIntegration(input: IntegrationWriteInput): WriteOutcome {
       }, doc);
       if (patched === null) {
         return refuse(clientId, "unsafe", "unsafe",
-          `${configPath} uses YAML source opencodex cannot patch without risking unrelated comments or formatting, so nothing was removed`);
+          yamlRefusalReason(before, spec.sourcePreservingYaml.path, configPath, "nothing was removed"));
       }
       text = patched;
     } else {
-      text = serializeDocument(doc, exportSpec.format);
+      text = clientId === "cline" ? serializeClineDocument(doc) : serializeDocument(doc, exportSpec.format);
     }
   } catch (error) {
     if (!(error instanceof UnserializableValueError)) throw error;
@@ -593,7 +630,7 @@ export function disableIntegration(input: IntegrationWriteInput): WriteOutcome {
 
 export function restoreIntegration(input: IntegrationRestoreInput): WriteOutcome {
   const store = input.store ?? createIntegrationStateStore();
-  const io = input.io ?? defaultIntegrationIO(store);
+  let io = input.io ?? defaultIntegrationIO(store);
   const entry = store.findOperation(input.opId);
   if (!entry) throw new Error(`unknown operation ${input.opId}`);
   if (entry.clientId !== input.clientId) throw new Error("restore input names a different client than the operation");
@@ -609,6 +646,13 @@ export function restoreIntegration(input: IntegrationRestoreInput): WriteOutcome
     return refuse(clientId, "conflict", "conflict",
       `that operation was recorded for ${configPath}, but this client now resolves to ${resolvedPath}`);
   }
+  if (clientId === "cline") {
+    try { io = createClineIO(io, configPath, store, true); }
+    catch (error) {
+      if (!(error instanceof ClineTransactionError)) throw error;
+      return { ...refuse(clientId, "unsafe", "unsafe", error.message, error.snapshotPath), residual: true };
+    }
+  }
   const snapshot = store.readSnapshot(entry);
   if (snapshot.kind === "expired") {
     return refuse(clientId, "snapshot_expired", "absent", "that backup has expired");
diff --git a/src/lab/subject/behavior-fingerprint.ts b/src/lab/subject/behavior-fingerprint.ts
index 51dd9d9efb..831577c8dc 100644
--- a/src/lab/subject/behavior-fingerprint.ts
+++ b/src/lab/subject/behavior-fingerprint.ts
@@ -3,7 +3,7 @@ import { jcsStringify } from "../digest";
 import type { LabBehaviorSource, LabBehaviorValues } from "../live/types";
 
 const CLOSED_KEYS = new Set([
-  "wire.adapter", "wire.upstreamProtocol", "wire.responsesPath", "wire.commandCodeVersion", "wire.modelSuffixMode",
+  "wire.adapter", "wire.upstreamProtocol", "wire.responsesPath", "wire.chatCompletionsPath", "wire.commandCodeVersion", "wire.modelSuffixMode",
   "auth.mode", "auth.transport",
   "responses.stateful", "responses.upstreamStreaming", "responses.serviceTier", "responses.fastWireKind", "responses.fastWireValue", "responses.snapshotRepair", "responses.itemIdRepair",
   "limits.contextWindow", "limits.maxInputTokens", "limits.maxOutputTokens",
diff --git a/src/lib/abort.ts b/src/lib/abort.ts
index e42a4b89b6..79f638e811 100644
--- a/src/lib/abort.ts
+++ b/src/lib/abort.ts
@@ -144,3 +144,39 @@ export function cancelBodyOnAbort(body: ReadableStream<Uint8Array> | null, signa
   signal.addEventListener("abort", onAbort, { once: true });
   return () => signal.removeEventListener("abort", onAbort);
 }
+
+/**
+ * Compose multiple AbortSignals into a single signal that aborts when ANY input
+ * aborts. Uses `AbortSignal.any` when available (Node >=20.3 / Bun >=1.0);
+ * falls back to a manual implementation for older runtimes.
+ *
+ * The caller gets a `cleanup` alongside the signal and must call it once the
+ * work it guards has settled. `{ once: true }` only removes a listener that
+ * actually fired, so on the polyfill path a long-lived parent signal - a proxy
+ * session's, say - accumulates one listener per request until it aborts or the
+ * process exits. `signalWithTimeout` in this file has always had that
+ * discipline; this function did not.
+ */
+export function anySignal(signals: AbortSignal[]): { signal: AbortSignal; cleanup: () => void } {
+  const builtin = (AbortSignal as unknown as { any?: (s: AbortSignal[]) => AbortSignal }).any;
+  if (typeof builtin === "function") return { signal: builtin(signals), cleanup: () => {} };
+  const controller = new AbortController();
+  const listeners: Array<[AbortSignal, () => void]> = [];
+  const cleanup = (): void => {
+    for (const [source, handler] of listeners.splice(0)) source.removeEventListener("abort", handler);
+  };
+  const onAbort = (reason: unknown): void => {
+    if (!controller.signal.aborted) controller.abort(reason);
+    cleanup();
+  };
+  for (const s of signals) {
+    if (s.aborted) {
+      onAbort(s.reason);
+      break;
+    }
+    const handler = () => onAbort(s.reason);
+    listeners.push([s, handler]);
+    s.addEventListener("abort", handler);
+  }
+  return { signal: controller.signal, cleanup };
+}
diff --git a/src/lib/local-destinations.ts b/src/lib/local-destinations.ts
index 56e9b3c056..d4699754d1 100644
--- a/src/lib/local-destinations.ts
+++ b/src/lib/local-destinations.ts
@@ -7,7 +7,7 @@
  * 1. `localManagementOrigin` — authenticated management discovery/state (`/api/*`). It is
  *    served by the public listener and, on a hub, additionally by the loopback-only
  *    `hub.managementIngress`. Callers must still send a management credential: management
- *    authentication has no loopback bypass (structure/05), and the unauthenticated loopback
+ *    authentication has no loopback bypass (structure/gui-and-management-api.md), and the unauthenticated loopback
  *    listener deliberately does not serve `/api/*` at all.
  * 2. `localInferenceDestination` — the data plane a client wire actually speaks.
  *
diff --git a/src/lib/upstream-retry.ts b/src/lib/upstream-retry.ts
index 74302af51f..afdbbcf3ae 100644
--- a/src/lib/upstream-retry.ts
+++ b/src/lib/upstream-retry.ts
@@ -16,6 +16,39 @@
  */
 import { clearableDeadline } from "./abort";
 
+/**
+ * Responses the origin may already be executing. RFC 9110 §9.2.2 forbids an intermediary
+ * from automatically repeating a non-idempotent request; when a post-send transport (the
+ * Codex WebSocket relay) settles a gateway status because the origin never acknowledged the
+ * turn, the request body must not be sent again by this process — not by the transient-5xx
+ * layer below, not by a pool account rotation, not by a combo hop. The status is returned
+ * to the caller so the user agent can apply its own retry policy, exactly as it does on the
+ * direct path. The WeakSet is the in-process marker; the structured error codes are the
+ * marker that survives body re-wrapping (combo failure consumption re-parses the JSON).
+ */
+const nonReplayableResponses = new WeakSet<Response>();
+
+export function markResponseNonReplayable(response: Response): void {
+  nonReplayableResponses.add(response);
+}
+
+export function isNonReplayableResponse(response: Response): boolean {
+  return nonReplayableResponses.has(response);
+}
+
+/** Origin never produced a response event; the turn may still be executing. */
+export const UPSTREAM_NO_RESPONSE_CODE = "upstream_no_response";
+/** Transport closed after the send, before any response event. */
+export const UPSTREAM_CLOSED_BEFORE_RESPONSE_CODE = "upstream_closed_before_response";
+const NON_REPLAYABLE_UPSTREAM_CODES: ReadonlySet<string> = new Set([
+  UPSTREAM_NO_RESPONSE_CODE,
+  UPSTREAM_CLOSED_BEFORE_RESPONSE_CODE,
+]);
+
+export function isNonReplayableUpstreamCode(code: unknown): boolean {
+  return typeof code === "string" && NON_REPLAYABLE_UPSTREAM_CODES.has(code);
+}
+
 // 1 initial + 2 retries: the pool may hold more than one stale socket.
 const RESET_RETRY_MAX_ATTEMPTS = 3;
 const RESET_RETRY_BASE_DELAY_MS = 150;
@@ -395,7 +428,9 @@ export async function fetchWithTransientRetry(
   let attemptStart = Date.now();
   let res = await fetchWithResetRetry(countedFetch, { ...opts, attempts: remaining() });
   for (let attempt = 0; sent < budget; attempt++) {
-    if (res.ok || !isTransientUpstreamStatus(res.status)) return res;
+    // A non-replayable gateway status was settled after the request body had already left
+    // for the origin; retrying it here is the automatic resend the marker exists to forbid.
+    if (res.ok || !isTransientUpstreamStatus(res.status) || isNonReplayableResponse(res)) return res;
     // Checked before cancelResponseBodyBestEffort so an already-aborted caller never receives
     // a response whose body we just cancelled.
     if (opts.abortSignal?.aborted) return res;
diff --git a/src/oauth/account-quota-rank.ts b/src/oauth/account-quota-rank.ts
index 978f73de9d..0cae484fa5 100644
--- a/src/oauth/account-quota-rank.ts
+++ b/src/oauth/account-quota-rank.ts
@@ -67,6 +67,17 @@ function headroomOf(provider: string, accountId: string): number | null {
   return 100 - Math.max(...percents);
 }
 
+/**
+ * Remaining headroom percent for one account, or null when nothing has measured it.
+ *
+ * Exported for the generic fill-first threshold, which needs the measurement itself rather
+ * than an ordering. Null stays null all the way out: a caller must decide what "unmeasured"
+ * means for its own rule instead of being handed a fabricated 0 or 100.
+ */
+export function accountHeadroomPercent(provider: string, accountId: string): number | null {
+  return headroomOf(provider, accountId);
+}
+
 /** Unknown usage is not exhaustion; Kiro's explicit overage verdict is authoritative. */
 export function isAccountQuotaExhausted(provider: string, accountId: string): boolean {
   const exhaustion = provider === "kiro" ? getKiroAccountExhaustion(`${provider}\u0000${accountId}`) : null;
diff --git a/src/oauth/callback-server.ts b/src/oauth/callback-server.ts
index dc49d5fcd2..a9d4b7f003 100644
--- a/src/oauth/callback-server.ts
+++ b/src/oauth/callback-server.ts
@@ -37,6 +37,14 @@ function errorHtml(message: string): string {
 
 export type CallbackResult = { code: string; state: string };
 
+/** Close every response so pooled sockets cannot send the next login to a retired flow. */
+function closingResponse(body: string, status: number, contentType = "text/html"): Response {
+  return new Response(body, {
+    status,
+    headers: { "Content-Type": contentType, "Connection": "close" },
+  });
+}
+
 /**
  * The redirect URI advertised to providers must stay `localhost` (it is what the OAuth
  * apps have registered), but Windows commonly resolves `localhost` to `::1` first while
@@ -177,7 +185,7 @@ export abstract class OAuthCallbackFlow {
   #handleCallback(req: Request, expectedState: string): Response {
     const url = new URL(req.url);
     if (url.pathname !== this.callbackPath) {
-      return new Response("Not Found", { status: 404 });
+      return closingResponse("Not Found", 404, "text/plain");
     }
 
     const code = url.searchParams.get("code");
@@ -214,10 +222,7 @@ export abstract class OAuthCallbackFlow {
       });
     }
 
-    return new Response(ok ? SUCCESS_HTML : errorHtml(errMessage), {
-      status: ok ? 200 : consumeFlow ? 500 : 400,
-      headers: { "Content-Type": "text/html" },
-    });
+    return closingResponse(ok ? SUCCESS_HTML : errorHtml(errMessage), ok ? 200 : consumeFlow ? 500 : 400);
   }
 
   #waitForCallback(expectedState: string): Promise<CallbackResult> {
diff --git a/src/oauth/devin-cli.ts b/src/oauth/devin-cli.ts
new file mode 100644
index 0000000000..14a5466b53
--- /dev/null
+++ b/src/oauth/devin-cli.ts
@@ -0,0 +1,149 @@
+/**
+ * Devin CLI credential import.
+ *
+ * The installed CLI writes `credentials.toml` after `devin auth login`, and the
+ * `windsurf_api_key` in it is an ordinary `devin-session-token$<JWT>` — the same
+ * shape RegisterUser returns for `ocx login devin`, and the same one the
+ * cloud-direct client already speaks. Measured against a signed-in CLI: it mints
+ * a user_jwt, opens the full model catalog, and streams chat.
+ *
+ * So this is kiro's import-first login with the same substance: adopt a signed-in
+ * local CLI's own session rather than starting a browser flow the CLI already
+ * completed. No browser is ever opened, because there is nothing left for
+ * opencodex to authorize.
+ *
+ * The file also carries `devin_webapp_host` and `devin_api_url`, which belong to
+ * the Devin *session* product (`cog_` keys, agent VMs) rather than to model
+ * inference. Neither is read here.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { posix, win32 } from "node:path";
+import { DEVIN_CLI_INSTALL_HINT } from "../adapters/devin-cli/binary";
+import { identityFromApiKey } from "./devin";
+import { resolveDevinApiBaseUrl } from "./devin/api-base";
+import type { OAuthController, OAuthCredentials } from "./types";
+
+/**
+ * Structurally the `LoginOpts` from `./index`, restated here rather than imported.
+ * `index.ts` imports this module to register the provider, so importing the type
+ * back would close a cycle for one optional field this flow does not branch on:
+ * an import has nothing to force, so `forceLogin` is a no-op for it.
+ */
+type DevinCliLoginOpts = { forceLogin?: boolean };
+
+/** Absolute-path override, for a CLI installed somewhere this resolver does not model. */
+export const DEVIN_CLI_CREDENTIALS_ENV = "OPENCODEX_DEVIN_CLI_CREDENTIALS";
+
+export interface DevinCliLoginDeps {
+  env?: NodeJS.ProcessEnv;
+  platform?: NodeJS.Platform;
+  exists?: (path: string) => boolean;
+  read?: (path: string) => string;
+}
+
+/**
+ * Where the CLI keeps its own credential.
+ *
+ * Measured on a live install: `$XDG_DATA_HOME/devin/credentials.toml`, i.e.
+ * `~/.local/share/devin/...`, which `devin auth status` prints. Note this is the
+ * DATA dir, not the config dir — an earlier draft guessed `~/.config` and was
+ * wrong. The Windows branch mirrors the CLI's own installer.
+ */
+export function devinCliCredentialsPath(
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
+): string {
+  const override = env[DEVIN_CLI_CREDENTIALS_ENV]?.trim();
+  // Absolute only. A relative override would resolve against whatever directory
+  // the proxy happens to be running in, which is not a location a user can mean.
+  if (override && (override.startsWith("/") || /^[A-Za-z]:[\\/]/.test(override))) return override;
+  const paths = platform === "win32" ? win32 : posix;
+  if (platform === "win32") {
+    const appData = env.APPDATA ?? paths.join(homedir(), "AppData", "Roaming");
+    return paths.join(appData, "devin", "credentials.toml");
+  }
+  const dataHome = env.XDG_DATA_HOME ?? paths.join(homedir(), ".local", "share");
+  return paths.join(dataHome, "devin", "credentials.toml");
+}
+
+export interface DevinCliCredentialFile {
+  apiKey: string;
+  apiServerUrl: string;
+}
+
+/**
+ * Read the two keys that matter, and nothing else.
+ *
+ * The measured file is four flat `key = "value"` lines: no tables, no comments,
+ * no single quotes. A line matcher is therefore enough and a TOML dependency is
+ * not, and the quoted form is required rather than optional — an unquoted
+ * matcher would pass its own fixtures and miss the real file.
+ *
+ * Returns undefined rather than throwing so the caller owns the one error
+ * message. Nothing here ever puts the file's contents into a thrown value.
+ */
+export function readDevinCliCredentialFile(deps: DevinCliLoginDeps = {}): DevinCliCredentialFile | undefined {
+  const path = devinCliCredentialsPath(deps.env, deps.platform);
+  const exists = deps.exists ?? existsSync;
+  if (!exists(path)) return undefined;
+  let raw: string;
+  try {
+    raw = (deps.read ?? ((p: string) => readFileSync(p, "utf8")))(path);
+  } catch {
+    return undefined;
+  }
+  const apiKey = raw.match(/^\s*windsurf_api_key\s*=\s*"([^"]+)"/m)?.[1]?.trim();
+  const apiServerUrl = raw.match(/^\s*api_server_url\s*=\s*"([^"]+)"/m)?.[1]?.trim();
+  if (!apiKey || !apiServerUrl) return undefined;
+  return { apiKey, apiServerUrl };
+}
+
+/** True when a signed-in CLI credential is readable. Used for status, never for auth. */
+export function devinCliSignedIn(deps: DevinCliLoginDeps = {}): boolean {
+  return readDevinCliCredentialFile(deps) !== undefined;
+}
+
+export async function loginDevinCli(
+  ctrl: OAuthController,
+  _opts?: DevinCliLoginOpts,
+  deps: DevinCliLoginDeps = {},
+): Promise<OAuthCredentials> {
+  const file = readDevinCliCredentialFile(deps);
+  if (!file) {
+    // Deliberately names no path contents and no parsed value. A Connect error
+    // can echo a request, and redactSecretString does not recognise a bare JWT
+    // or a devin-session-token, which is why register-user.ts refuses to repeat
+    // error bodies; the same caution applies to anything thrown from here.
+    throw new Error(
+      `No signed-in Devin CLI session found. ${DEVIN_CLI_INSTALL_HINT} Then run \`devin auth login\` and try again.`,
+    );
+  }
+  // The host comes off disk and then receives the key, so it passes the same
+  // allowlist as the RegisterUser host. An unallowlisted value falls back to the
+  // default rather than becoming an exfiltration target.
+  const apiBaseUrl = resolveDevinApiBaseUrl(file.apiServerUrl);
+  ctrl.onProgress?.("Imported the signed-in Devin CLI session.");
+  return {
+    access: file.apiKey,
+    // Cognition issues a durable key and exposes no refresh endpoint. Carrying
+    // the key here rather than "" is the house pattern: an empty refresh makes
+    // detectOAuthWarning report stale_credentials from the moment of login.
+    refresh: file.apiKey,
+    expires: Number.MAX_SAFE_INTEGER,
+    source: "local-cli",
+    apiBaseUrl,
+    ...identityFromApiKey(file.apiKey),
+  };
+}
+
+export async function refreshDevinCliToken(
+  _refreshToken: string,
+  _signal?: AbortSignal,
+  _credential?: OAuthCredentials,
+): Promise<OAuthCredentials> {
+  // The CLI owns this session and Cognition has no refresh endpoint. Extending
+  // the stored expiry would make a revoked key look valid forever; throwing lets
+  // the request path mark the account needsReauth instead.
+  throw new Error("invalid_grant: the Devin CLI owns this session. Run devin auth login again.");
+}
diff --git a/src/oauth/devin.ts b/src/oauth/devin.ts
new file mode 100644
index 0000000000..57da4d460c
--- /dev/null
+++ b/src/oauth/devin.ts
@@ -0,0 +1,170 @@
+/**
+ * Devin / Cognition OAuth.
+ *
+ * Login opens the Auth0 browser sign-in flow (windsurf.com/windsurf/signin
+ * with redirect_uri=show-auth-token), then exchanges the pasted Firebase ID
+ * token via Cognition's RegisterUser for a long-lived API key.
+ */
+import { randomUUID } from "node:crypto";
+import type { OAuthController, OAuthCredentials } from "./types";
+import { DEFAULT_REGION, type WindsurfRegion } from "./devin/types";
+import { registerUser } from "./devin/register-user";
+import { DEVIN_DEFAULT_API_SERVER, resolveDevinApiBaseUrl, validateDevinApiBaseUrl } from "./devin/api-base";
+import { getCredential } from "./store";
+
+export { DEVIN_DEFAULT_API_SERVER } from "./devin/api-base";
+
+/**
+ * The api-server host this account must talk to.
+ *
+ * RegisterUser hands EU and FedStart tenants a host of their own and it is kept
+ * on the credential, so the signed-in account decides the destination. The
+ * configured provider baseUrl is the fallback, and the US default is the last
+ * resort; both are re-validated because neither is trusted more than the
+ * network value.
+ */
+export function resolveDevinApiServer(configuredBaseUrl?: string, providerId = "devin"): string {
+  return (
+    // Provider-scoped. `devin` and `devin-cli` share this transport and this token
+    // format but sign in to different accounts, and an EU or FedStart tenant is
+    // recorded on the credential rather than in the registry. Reading a fixed
+    // "devin" slot sent one provider's key to the other's host.
+    validateDevinApiBaseUrl(getCredential(providerId)?.apiBaseUrl) ??
+    validateDevinApiBaseUrl(configuredBaseUrl) ??
+    DEVIN_DEFAULT_API_SERVER
+  );
+}
+
+function decodeJwtPayload(token: string): Record<string, unknown> | undefined {
+  const parts = token.split(".");
+  const payload = parts[1];
+  if (parts.length < 2 || !payload) return undefined;
+  try {
+    return JSON.parse(Buffer.from(payload, "base64url").toString("utf8")) as Record<string, unknown>;
+  } catch {
+    return undefined;
+  }
+}
+
+export function identityFromApiKey(apiKey: string): { accountId?: string; email?: string } {
+  const jwtPart = apiKey.includes("$") ? apiKey.slice(apiKey.indexOf("$") + 1) : apiKey;
+  const payload = decodeJwtPayload(jwtPart);
+  const email = typeof payload?.email === "string" && payload.email.length > 0 ? payload.email : undefined;
+  const sub = typeof payload?.sub === "string" && payload.sub.length > 0 ? payload.sub : undefined;
+  const authUid = typeof payload?.auth_uid === "string" && payload.auth_uid.length > 0 ? payload.auth_uid : undefined;
+  return { ...(email ? { email } : {}), ...(sub || authUid ? { accountId: sub ?? authUid } : {}) };
+}
+
+function credentialsFromApiKey(
+  apiKey: string,
+  apiBaseUrl: string,
+  source: OAuthCredentials["source"] = "oauth",
+): OAuthCredentials {
+  const identity = identityFromApiKey(apiKey);
+  return {
+    access: apiKey,
+    // Cognition issues a durable key and exposes no refresh endpoint. Carrying
+    // the key here rather than "" is the house pattern for durable-key
+    // providers: an empty refresh makes detectOAuthWarning report
+    // stale_credentials for every Devin account from the moment it logs in.
+    refresh: apiKey,
+    // No expiry to model. A synthetic one-year deadline only produces a
+    // refresh attempt against an endpoint that does not exist.
+    expires: Number.MAX_SAFE_INTEGER,
+    source,
+    apiBaseUrl,
+    ...identity,
+  };
+}
+
+function buildSignInUrl(region: WindsurfRegion): string {
+  const params = new URLSearchParams({
+    response_type: "token",
+    client_id: region.oauthClientId,
+    redirect_uri: "show-auth-token",
+    state: randomUUID(),
+    prompt: "login",
+  });
+  return region.website + "/windsurf/signin?" + params.toString();
+}
+
+/**
+ * Shape of the value the sign-in page hands back.
+ *
+ * It is not always a JWT. A live free-tier sign-in against
+ * windsurf.com/windsurf/signin returns a 47-character one-time token of the
+ * form `ott$<base64url>`, and RegisterUser accepts it; an earlier JWT-only
+ * check here would have rejected every real login. So this is deliberately a
+ * shape check for "one opaque credential-looking word" rather than a format
+ * check: the point is to tell a token from a pasted URL or a sentence, not to
+ * second-guess what the vendor mints.
+ */
+const TOKEN_SHAPE = /^[A-Za-z0-9._$~+/=-]{20,4096}$/;
+
+const TOKEN_PARAM_NAMES = ["firebase_id_token", "access_token", "id_token", "token"] as const;
+
+/**
+ * Turn whatever the user pasted into the Firebase ID token RegisterUser expects.
+ *
+ * The sign-in page shows a bare token, but a user who copies the address bar
+ * instead hands us a callback URL whose fragment carries it. Posting that URL
+ * as `firebase_id_token` produces an opaque server-side rejection, so pull the
+ * token out and refuse a paste that has none rather than sending something that
+ * cannot work.
+ */
+export function parseDevinAuthPaste(raw: string): string {
+  const trimmed = raw.trim();
+  if (!trimmed) throw new Error("No auth token pasted; cannot complete Devin sign-in.");
+  if (/^https?:\/\//i.test(trimmed)) {
+    let url: URL;
+    try {
+      url = new URL(trimmed);
+    } catch {
+      throw new Error("That paste is not a usable Devin auth token or sign-in URL.");
+    }
+    const hash = url.hash.startsWith("#") ? url.hash.slice(1) : url.hash;
+    for (const params of [new URLSearchParams(hash), url.searchParams]) {
+      for (const name of TOKEN_PARAM_NAMES) {
+        const value = params.get(name)?.trim();
+        if (value && TOKEN_SHAPE.test(value)) return value;
+      }
+    }
+    throw new Error("That sign-in URL carries no auth token. Paste the token shown on the Windsurf page instead.");
+  }
+  if (TOKEN_SHAPE.test(trimmed)) return trimmed;
+  throw new Error("That paste is not a Devin auth token. Copy the token shown on the Windsurf sign-in page.");
+}
+
+async function loginDevinBrowser(ctrl: OAuthController, region: WindsurfRegion): Promise<OAuthCredentials> {
+  const url = buildSignInUrl(region);
+  ctrl.onAuth?.({
+    url,
+    instructions: "Sign in with your Cognition/Devin account, then paste the on-screen auth token here.",
+  });
+  ctrl.onProgress?.("Waiting for the pasted auth token...");
+  const pasted = (await ctrl.onManualCodeInput?.())?.trim();
+  if (!pasted) throw new Error("No auth token pasted; cannot complete Devin sign-in.");
+  const firebaseIdToken = parseDevinAuthPaste(pasted);
+  const result = await registerUser(firebaseIdToken, region, ctrl.signal);
+  const credentials = credentialsFromApiKey(result.apiKey, resolveDevinApiBaseUrl(result.apiServerUrl), "oauth");
+  // The display name is not an identity. Use it only when the key carried no
+  // email, otherwise reauth compares a label against an address and mismatches.
+  if (!credentials.email && result.name) credentials.email = result.name;
+  return credentials;
+}
+
+export async function loginDevin(ctrl: OAuthController): Promise<OAuthCredentials> {
+  return loginDevinBrowser(ctrl, DEFAULT_REGION);
+}
+
+export async function refreshDevinToken(
+  _refreshToken: string,
+  _signal?: AbortSignal,
+  _credential?: OAuthCredentials,
+): Promise<OAuthCredentials> {
+  // Cognition has no refresh endpoint. Extending the stored expiry here is what
+  // the carried implementation did, and it makes a revoked key look valid
+  // forever. Throwing lets the request path mark the account needsReauth the
+  // first time a forced refresh happens.
+  throw new Error("invalid_grant: Devin API keys do not refresh. Run ocx login devin again.");
+}
diff --git a/src/oauth/devin/api-base.ts b/src/oauth/devin/api-base.ts
new file mode 100644
index 0000000000..684ed632ce
--- /dev/null
+++ b/src/oauth/devin/api-base.ts
@@ -0,0 +1,63 @@
+/**
+ * Allowlist for the Cognition/Devin api-server origin.
+ *
+ * RegisterUser returns the tenant's api-server host, and that host then receives
+ * GetUserJwt, GetCascadeModelConfigs and GetChatMessage - the first of which
+ * carries the long-lived api_key. A host taken from the network without
+ * validation turns a spoofed or compromised RegisterUser response into
+ * credential exfiltration, so every value that reaches a request URL or the
+ * credential store passes through here first.
+ *
+ * This lives in its own module rather than in `../devin.ts` because the
+ * credential store imports the validator and `../devin.ts` imports the store's
+ * sibling types; a shared leaf keeps that from becoming a cycle.
+ */
+
+export const DEVIN_DEFAULT_API_SERVER = "https://server.codeium.com";
+
+/**
+ * Return the normalized api-server base URL, or undefined when the input is not
+ * an allowlisted Cognition host.
+ *
+ * Unlike the Copilot equivalent this keeps the path. EU and FedStart tenants are
+ * reached at `https://eu.windsurf.com/_route/api_server`, so the path prefix is
+ * part of the address rather than decoration, and normalizing to the origin
+ * would silently point those accounts at the wrong service.
+ */
+export function validateDevinApiBaseUrl(raw: string | undefined | null): string | undefined {
+  if (raw === undefined || raw === null) return undefined;
+  const trimmed = String(raw).trim();
+  if (!trimmed) return undefined;
+  let parsed: URL;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    return undefined;
+  }
+  if (parsed.protocol !== "https:") return undefined;
+  if (parsed.username || parsed.password) return undefined;
+  if (parsed.port && parsed.port !== "443") return undefined;
+  if (parsed.search || parsed.hash) return undefined;
+  const host = parsed.hostname.toLowerCase();
+  if (host === "localhost" || host.endsWith(".localhost")) return undefined;
+  if (/^\d{1,3}(\.\d{1,3}){3}$/.test(host) || host.includes(":")) return undefined;
+  const allowed =
+    host === "server.codeium.com" ||
+    // The shipped client (Devin Desktop 3.9.19,
+    // Contents/Resources/app/extensions/windsurf/dist/extension.js) also names
+    // these two, and a beta account's RegisterUser can return one.
+    host === "server-staging.codeium.com" ||
+    host === "server-beta.codeium.com" ||
+    host === "windsurf.com" ||
+    host.endsWith(".windsurf.com") ||
+    host === "windsurf.fedstart.com";
+  if (!allowed) return undefined;
+  const path = parsed.pathname.replace(/\/+$/, "");
+  if (path && !/^(\/[A-Za-z0-9._-]+)+$/.test(path)) return undefined;
+  return `https://${host}${path}`;
+}
+
+/** Same check, falling back to the default US host when the input is unusable. */
+export function resolveDevinApiBaseUrl(raw: string | undefined | null): string {
+  return validateDevinApiBaseUrl(raw) ?? DEVIN_DEFAULT_API_SERVER;
+}
diff --git a/src/oauth/devin/login.ts b/src/oauth/devin/login.ts
new file mode 100644
index 0000000000..67d4672ea3
--- /dev/null
+++ b/src/oauth/devin/login.ts
@@ -0,0 +1 @@
+export { loginDevin } from "../devin";
diff --git a/src/oauth/devin/register-user.ts b/src/oauth/devin/register-user.ts
new file mode 100644
index 0000000000..248e822789
--- /dev/null
+++ b/src/oauth/devin/register-user.ts
@@ -0,0 +1,186 @@
+/**
+ * Exchange a Firebase ID token for a long-lived Cognition/Devin API key.
+ *
+ * This calls the same Connect-RPC endpoint the Devin desktop client uses
+ * after browser sign-in completes:
+ *
+ *   POST https://register.windsurf.com/exa.seat_management_pb.SeatManagementService/RegisterUser
+ *   Content-Type: application/json
+ *   Body: { "firebase_id_token": "<jwt>" }
+ *
+ * Connect-RPC happily accepts plain JSON over HTTPS (no gRPC framing required),
+ * so we skip @connectrpc/connect entirely and use `fetch`. The response shape
+ * matches `exa.seat_management_pb.RegisterUserResponse`:
+ *
+ *   { api_key, name, api_server_url, redirect_url, team_options[] }
+ */
+
+import type { OAuthLoginResult, WindsurfRegion } from './types.js';
+import { anySignal } from '../../lib/abort.js';
+import { validateDevinApiBaseUrl } from './api-base.js';
+
+interface RegisterUserResponseJson {
+  api_key?: string;
+  name?: string;
+  api_server_url?: string;
+  redirect_url?: string;
+  team_options?: unknown[];
+}
+
+interface ConnectErrorJson {
+  code?: string;
+  message?: string;
+}
+
+export class WindsurfRegistrationError extends Error {
+  readonly status: number;
+  readonly connectCode?: string;
+  readonly traceId?: string;
+
+  constructor(message: string, status: number, connectCode?: string, traceId?: string) {
+    super(message);
+    this.name = 'WindsurfRegistrationError';
+    this.status = status;
+    this.connectCode = connectCode;
+    this.traceId = traceId;
+  }
+}
+
+const TRACE_ID_RE = /\(trace ID: ([0-9a-f]+)\)/i;
+
+/**
+ * Connect error codes that are safe to repeat to the user.
+ *
+ * The message body is not: a Connect error can echo the request, and the
+ * request here is the Firebase ID token. That message reaches CLI output and
+ * /api/logs, and redactSecretString does not recognise a bare JWT, so the code
+ * is the only part of an error body that leaves this function.
+ */
+const SAFE_CONNECT_CODES = new Set([
+  'canceled', 'unknown', 'invalid_argument', 'deadline_exceeded', 'not_found', 'already_exists',
+  'permission_denied', 'resource_exhausted', 'failed_precondition', 'aborted', 'out_of_range',
+  'unimplemented', 'internal', 'unavailable', 'data_loss', 'unauthenticated',
+]);
+
+function safeConnectCode(value: unknown): string | undefined {
+  return typeof value === 'string' && SAFE_CONNECT_CODES.has(value) ? value : undefined;
+}
+
+/**
+ * Exchange the Firebase ID token for a Windsurf API key.
+ *
+ * `firebaseIdToken` is the `access_token` (or `firebase_id_token`) value the
+ * Windsurf sign-in page returns in the OAuth callback URL — we treat it as
+ * opaque.
+ */
+export async function registerUser(
+  firebaseIdToken: string,
+  region: WindsurfRegion,
+  abortSignal?: AbortSignal,
+): Promise<OAuthLoginResult> {
+  if (!firebaseIdToken) {
+    throw new WindsurfRegistrationError('Empty firebase_id_token', 0, 'invalid_argument');
+  }
+
+  // The register host reaches the network holding the Firebase ID token, so it
+  // passes the same allowlist as the api-server host rather than being trusted
+  // because it came from a config object.
+  const registerBase = validateDevinApiBaseUrl(region.registerApiServerUrl);
+  if (!registerBase) {
+    throw new WindsurfRegistrationError(
+      'Refusing to send the sign-in token to a non-Cognition register host.',
+      0,
+      'permission_denied',
+    );
+  }
+  const url = `${registerBase}/exa.seat_management_pb.SeatManagementService/RegisterUser`;
+
+  // 30s internal timeout — RegisterUser responds in ~200ms in steady state.
+  // CLI users on flaky networks need bounded waits or the sign-in command
+  // hangs forever. Compose with the caller's signal via a small polyfill
+  // (`anySignal`) because Node 18 / older Bun lack AbortSignal.any; the
+  // previous fallback `combinedSignal = abortSignal` would drop the
+  // timeout entirely on those runtimes.
+  const timeoutSignal = AbortSignal.timeout(30_000);
+  const composed = abortSignal ? anySignal([abortSignal, timeoutSignal]) : undefined;
+  const combinedSignal: AbortSignal = composed?.signal ?? timeoutSignal;
+
+  let response: Response;
+  try {
+    response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      // Connect protocol version header — not strictly required for JSON, but
+      // matches what the official Connect clients send and avoids accidental
+      // routing into a non-Connect HTTP handler.
+      'Connect-Protocol-Version': '1',
+    },
+    body: JSON.stringify({ firebase_id_token: firebaseIdToken }),
+    // A 307/308 would replay this POST, and its body is the sign-in token, at
+    // whatever host Location names. Fail instead of following.
+    redirect: 'error',
+    signal: combinedSignal,
+    });
+  } finally {
+    // Detach from the caller's signal; it can outlive this one exchange.
+    composed?.cleanup();
+  }
+
+  const text = await response.text();
+
+  if (!response.ok) {
+    let connectCode: string | undefined;
+    let traceId: string | undefined;
+    try {
+      const errJson = JSON.parse(text) as ConnectErrorJson;
+      connectCode = safeConnectCode(errJson.code);
+      // The trace id is an opaque server identifier and is the one part of the
+      // message worth keeping for a support conversation.
+      traceId = typeof errJson.message === 'string' ? errJson.message.match(TRACE_ID_RE)?.[1] : undefined;
+    } catch {
+      // Non-JSON error body. It stays unread; only the status is reported.
+    }
+    const message = `RegisterUser failed (HTTP ${response.status}${connectCode ? `, ${connectCode}` : ''}${traceId ? `, trace ${traceId}` : ''})`;
+    throw new WindsurfRegistrationError(message, response.status, connectCode, traceId);
+  }
+
+  let parsed: RegisterUserResponseJson;
+  try {
+    parsed = JSON.parse(text) as RegisterUserResponseJson;
+  } catch {
+    throw new WindsurfRegistrationError(
+      // The body is not echoed: a 200 that fails to parse can still contain the
+      // key or the token that produced it.
+      `RegisterUser returned 200 with a body that is not JSON (${text.length} bytes)`,
+      response.status,
+      'internal',
+    );
+  }
+
+  const apiKey = parsed.api_key;
+  // Empty `api_server_url` is normal for single-tenant accounts — the desktop
+  // extension's `getApiServerUrl` helper falls back to the configured default
+  // when this is empty/missing. We mirror that behavior here.
+  const apiServerUrl = parsed.api_server_url && parsed.api_server_url.length > 0
+    ? parsed.api_server_url
+    : 'https://server.codeium.com';
+
+  if (!apiKey) {
+    throw new WindsurfRegistrationError(
+      'RegisterUser returned 200 but api_key was empty',
+      response.status,
+      'malformed_response',
+    );
+  }
+  // `name` is optional in the response — default it instead of failing login.
+  // src/oauth/devin.ts uses it only as a display label for the account email.
+  const name = parsed.name && parsed.name.length > 0 ? parsed.name : 'Devin account';
+
+  return {
+    apiKey,
+    name,
+    apiServerUrl,
+    redirectUrl: parsed.redirect_url,
+  };
+}
diff --git a/src/oauth/devin/types.ts b/src/oauth/devin/types.ts
new file mode 100644
index 0000000000..07b317eb0d
--- /dev/null
+++ b/src/oauth/devin/types.ts
@@ -0,0 +1,71 @@
+/**
+ * Shared types for the OAuth login flow + persisted credentials.
+ *
+ * Two distinct token shapes appear in this codebase:
+ *
+ *  - `firebaseIdToken` — the short-lived JWT minted by Auth0 / Firebase Auth
+ *    during browser sign-in. Lives in the OAuth callback URL fragment/query.
+ *    Treated as opaque and discarded once exchanged.
+ *
+ *  - `apiKey` — the long-lived credential returned by
+ *    `SeatManagementService.RegisterUser`. Used inside every Cascade RPC's
+ *    `Metadata.api_key` field. Format is provider-defined:
+ *      * Cognition era:  `devin-session-token$<JWT>`
+ *      * Codeium classic: bare UUID v4
+ *      * Older Windsurf:  `sk-ws-01-<...>` / `cog_<...>`
+ *    The plugin treats it as an opaque string — only the cloud cares about format.
+ */
+
+export interface OAuthLoginResult {
+  /** The opaque API key used as `Metadata.api_key` in every Cascade RPC. */
+  apiKey: string;
+  /** Human-readable account name (`Satvik Kapoor`). */
+  name: string;
+  /**
+   * Cloud API server (`https://server.codeium.com`, `https://eu.windsurf.com/_route/api_server`,
+   * `https://windsurf.fedstart.com/_route/api_server`). Driven by the user's
+   * tenant — language_server needs this as `--api_server_url`.
+   */
+  apiServerUrl: string;
+  /** Optional cleanup redirect URL returned by RegisterUser. Informational. */
+  redirectUrl?: string;
+}
+
+export interface PersistedCredentials extends OAuthLoginResult {
+  /** ISO timestamp the credentials were minted at — purely informational. */
+  issuedAt: string;
+  /** Optional tag tracking the OAuth client id used (so a future client rotation can invalidate). */
+  oauthClientId: string;
+  /**
+   * True when these credentials were written as part of the
+   * `opencode auth login` → authorize() flow (so opencode's auth.json is the
+   * authoritative copy and `opencode auth logout windsurf` should mirror-clear
+   * this file). False / absent for credentials written by our standalone
+   * `opencode-windsurf-auth login` CLI; those survive opencode auth state
+   * changes.
+   */
+  syncedViaOpencodeAuth?: boolean;
+}
+
+export interface WindsurfRegion {
+  /** Where to send users for browser sign-in. */
+  website: string;
+  /** Where to POST RegisterUser. */
+  registerApiServerUrl: string;
+  /** Auth0 client id passed in the OAuth URL. */
+  oauthClientId: string;
+}
+
+/**
+ * The single tenant (free / personal) configuration. EU, FedStart, and arbitrary
+ * portal URLs override `website` + `registerApiServerUrl` at runtime when the
+ * user passes `--portal-url` to the login command.
+ */
+export const DEFAULT_REGION: WindsurfRegion = {
+  website: 'https://windsurf.com',
+  registerApiServerUrl: 'https://register.windsurf.com',
+  // From /Applications/Windsurf.app/.../extension.js — the public Windsurf
+  // Auth0 client. If Windsurf rotates this, sign-in will start failing until
+  // we re-extract it.
+  oauthClientId: '3GUryQ7ldAeKEuD2obYnppsnmj58eP5u',
+};
diff --git a/src/oauth/generic-account-failover.ts b/src/oauth/generic-account-failover.ts
index 1ccfaf71df..6b444ea435 100644
--- a/src/oauth/generic-account-failover.ts
+++ b/src/oauth/generic-account-failover.ts
@@ -16,7 +16,21 @@
  */
 import { getAccountSet } from "./store";
 import { getValidAccessSnapshotForAccount, type OAuthAccessSnapshot } from "./index";
-import { exhaustedCooldownMs, hasHeadroomEvidence, isAccountQuotaExhausted, rankAccountsByHeadroom } from "./account-quota-rank";
+import {
+  accountHeadroomPercent,
+  exhaustedCooldownMs,
+  hasHeadroomEvidence,
+  isAccountQuotaExhausted,
+  rankAccountsByHeadroom,
+} from "./account-quota-rank";
+import {
+  genericPoolKey,
+  normalizeAccountPoolStickyLimit,
+  notePoolRotationSuccess,
+  peekRoundRobinAccount,
+  pickRoundRobinAccount,
+  seedPoolRotationAccount,
+} from "./pool-kernel";
 import { parseRetryAfterMs } from "../combos/failover";
 import { sweepExpiredOnWrite } from "../lib/state-store-sweeper";
 import type { OcxConfig, OcxProviderConfig } from "../types";
@@ -169,6 +183,113 @@ export function eligibleFailoverAccounts(providerName: string, now = Date.now())
     .map(account => account.id);
 }
 
+/** Generic pool strategies the kernel can actually run. `quota` IS the pre-kernel path. */
+type ActiveGenericStrategy = "round-robin" | "fill-first";
+
+/** Matches the Codex and Anthropic pools; the DTO still reports `null` for "not stored". */
+const DEFAULT_GENERIC_AUTO_SWITCH_THRESHOLD = 80;
+
+/**
+ * The strategy this provider's pool actually runs, or null for today's behaviour.
+ *
+ * Three different inputs answer null and they all mean the same thing to a caller: the flag is
+ * off, no strategy is stored, or the stored strategy is `quota` — which is precisely what the
+ * unflagged code already does. Collapsing them here is what keeps every call site a two-way
+ * branch instead of a four-way one.
+ */
+function activeGenericStrategy(config: OcxConfig, providerName: string): ActiveGenericStrategy | null {
+  if (config.pool?.kernel !== true) return null;
+  const raw = config.providers?.[providerName]?.oauthAccountFailover?.strategy;
+  return raw === "round-robin" || raw === "fill-first" ? raw : null;
+}
+
+function genericStickyLimit(config: OcxConfig, providerName: string): number {
+  return normalizeAccountPoolStickyLimit(config.providers?.[providerName]?.oauthAccountFailover?.stickyLimit);
+}
+
+/**
+ * The FULL roster in a stable order, not the eligible subset.
+ *
+ * Two load-bearing reasons. The store holds accounts in LOGIN order, so two operators who added
+ * the same accounts in a different sequence would otherwise rotate differently; sorting makes
+ * the ring a property of the accounts rather than of the history. And walking the eligible
+ * subset instead of the full roster changes the wrap order whenever an ineligible id sits
+ * between two eligible ones — the bug the Codex and Anthropic copies carry a `stableAll`
+ * argument to avoid.
+ */
+function stableGenericRoster(providerName: string): string[] {
+  const set = getAccountSet(providerName);
+  if (!set) return [];
+  return set.accounts.map(account => account.id).sort((left, right) => left.localeCompare(right));
+}
+
+/**
+ * Has this account spent enough of its allowance for fill-first to move on?
+ *
+ * An unmeasured account reads as UNDER the threshold, matching the Codex pool: a threshold is a
+ * statement about observed usage, and treating "no observation" as "spent" would evacuate every
+ * quota-less provider off its active account on the very first request.
+ */
+function isOverAutoSwitchThreshold(providerName: string, accountId: string, threshold: number): boolean {
+  const headroom = accountHeadroomPercent(providerName, accountId);
+  if (headroom === null) return false;
+  return 100 - headroom >= threshold;
+}
+
+/**
+ * Fill-first: stay on the active account until it crosses its threshold, then take the next
+ * eligible account in the stable ring. Null means "keep the active account".
+ */
+function pickFillFirstGenericAccount(
+  config: OcxConfig,
+  providerName: string,
+  activeId: string | undefined,
+  now: number,
+): string | null {
+  const stableAll = stableGenericRoster(providerName);
+  if (stableAll.length < 2) return null;
+  const eligible = new Set(eligibleFailoverAccounts(providerName, now));
+  const stored = config.providers?.[providerName]?.oauthAccountFailover?.autoSwitchThreshold;
+  const threshold = typeof stored === "number" && Number.isInteger(stored) && stored >= 0 && stored <= 100
+    ? stored
+    : DEFAULT_GENERIC_AUTO_SWITCH_THRESHOLD;
+  if (activeId && eligible.has(activeId) && !isOverAutoSwitchThreshold(providerName, activeId, threshold)) {
+    return null;
+  }
+  const start = activeId ? stableAll.indexOf(activeId) : -1;
+  const ring = start >= 0 ? [...stableAll.slice(start + 1), ...stableAll.slice(0, start)] : stableAll;
+  for (const id of ring) {
+    if (id !== activeId && eligible.has(id)) return id;
+  }
+  return null;
+}
+
+/**
+ * Advance the round-robin cursor once a dispatch has actually been admitted on this account.
+ *
+ * The early return is the whole safety story for the core path: this is reached on EVERY
+ * generic first dispatch, including quota pools and the fallback after a preferred account was
+ * dropped, so anything but round-robin must leave the cursor untouched.
+ *
+ * The live pick belongs here rather than in the proposal, and that is not stylistic.
+ * `peekRoundRobinAccount` never creates the pool state and `notePoolRotationSuccess` returns
+ * immediately when there is none, so a peek-only path would leave the ring with nothing to
+ * advance and round-robin would propose the same account forever. This is the same shape
+ * `commitAnthropicSelectionRouting` already commits with.
+ */
+export function noteGenericPoolSelection(config: OcxConfig, providerName: string, accountId: string): void {
+  if (activeGenericStrategy(config, providerName) !== "round-robin") return;
+  const poolKey = genericPoolKey(providerName);
+  const limit = genericStickyLimit(config, providerName);
+  const picked = pickRoundRobinAccount(poolKey, eligibleFailoverAccounts(providerName), limit);
+  // The resolver may have admitted a different account than the ring proposed: a removal, a
+  // reauth verdict or a manual selection can land during credential resolution. Realign the
+  // cursor onto what actually served rather than leaving it on a road not taken.
+  if (picked !== accountId) seedPoolRotationAccount(poolKey, accountId);
+  notePoolRotationSuccess(poolKey, accountId, limit);
+}
+
+
 /**
  * Cool the account that actually 429'd and name the next eligible one, or null.
  *
@@ -212,6 +333,30 @@ export function rotateGenericOAuthAccountOn429(
   const ring = start >= 0 ? [...order.slice(start + 1), ...order.slice(0, start)] : order;
   const candidates = ring.filter(id => id !== failedAccountId && eligible.includes(id));
   if (candidates.length === 0) return null;
+  // The 429 path branches too. Leaving it on the quota ranking would make a configured
+  // strategy inert in practice the moment anything actually failed, which is the case the
+  // operator chose the strategy for.
+  const strategy = activeGenericStrategy(config, providerName);
+  if (strategy === "round-robin") {
+    // PICK here, not peek: the failure already happened and this answer is the one being used,
+    // so the ring genuinely advances.
+    return pickRoundRobinAccount(
+      genericPoolKey(providerName),
+      candidates,
+      genericStickyLimit(config, providerName),
+    );
+  }
+  if (strategy === "fill-first") {
+    // Not "keep the active account": the one that just 429'd is cooled, so fill-first takes
+    // the next eligible account in the stable ring rather than its usual hold.
+    const stableAll = stableGenericRoster(providerName);
+    const from = stableAll.indexOf(failedAccountId);
+    const walk = from >= 0 ? [...stableAll.slice(from + 1), ...stableAll.slice(0, from)] : stableAll;
+    for (const id of walk) {
+      if (id !== failedAccountId && candidates.includes(id)) return id;
+    }
+    return null;
+  }
   // With no quota evidence this returns the ring untouched, so providers without
   // per-account quota keep exactly the traversal they have today.
   return rankAccountsByHeadroom(providerName, candidates)[0] ?? null;
@@ -259,6 +404,29 @@ export function preferredInitialAccount(
   const order = selected.accounts.filter(account => account.needsReauth !== true).map(account => account.id);
   if (order.length < 2) return null;
 
+  // A configured strategy answers this question itself. Both guards below exist to protect the
+  // QUOTA answer, and both are fatal to the other two: hasHeadroomEvidence refuses every
+  // provider with no quota data, which is exactly where round-robin is the point, and the
+  // healthy-active return fires before autoSwitchThreshold can ever be read, so fill-first
+  // would never reach its own test. Cooldowns and reauth are still honoured inside each pick.
+  const strategy = activeGenericStrategy(config, providerName);
+  if (strategy === "round-robin") {
+    const eligibleNow = eligibleFailoverAccounts(providerName, now);
+    if (eligibleNow.length === 0) return null;
+    // PEEK, not pick: this proposal is discardable, and advancing the ring for an account the
+    // resolver then rejects would skip a turn for nothing. noteGenericPoolSelection commits.
+    const picked = peekRoundRobinAccount(
+      genericPoolKey(providerName),
+      eligibleNow,
+      genericStickyLimit(config, providerName),
+    );
+    return picked && picked !== active ? picked : null;
+  }
+  if (strategy === "fill-first") {
+    const picked = pickFillFirstGenericAccount(config, providerName, active, now);
+    return picked && picked !== active ? picked : null;
+  }
+
   const activeRow = selected.accounts.find(account => account.id === active);
   if (activeRow && activeRow.needsReauth !== true
     && !isCooled(providerName, activeRow.id, now)
diff --git a/src/oauth/index.ts b/src/oauth/index.ts
index ed8af01af9..d0b1a1e010 100644
--- a/src/oauth/index.ts
+++ b/src/oauth/index.ts
@@ -38,6 +38,8 @@ import { loginNous, NousTokenError, refreshNousToken, clearNousRefreshIntent, Re
 import { loginChatGPT, refreshChatGPTToken, type ChatGPTLoginFlow } from "./chatgpt";
 import { loginAntigravity, refreshAntigravityToken } from "./google-antigravity";
 import { loginCursor, refreshCursorToken } from "./cursor";
+import { loginDevin, refreshDevinToken } from "./devin";
+import { loginDevinCli, refreshDevinCliToken } from "./devin-cli";
 import { loginGithubCopilot, refreshGithubCopilotToken, validateCopilotApiBaseUrl } from "./github-copilot";
 import { loginCommandCode, refreshCommandCodeToken } from "./command-code";
 import { loginMetaMuse, refreshMetaMuseToken } from "./meta-muse";
@@ -308,6 +310,23 @@ export const OAUTH_PROVIDERS: Record<string, OAuthProviderDef> = {
     providerConfig: oauthConfig("cursor"),
     defaultModel: oauthDefaultModel("cursor"),
   },
+  devin: {
+    login: (ctrl) => loginDevin(ctrl),
+    refresh: refreshDevinToken,
+    providerConfig: oauthConfig("devin"),
+    defaultModel: oauthDefaultModel("devin"),
+    defaultRefreshPolicy: "disabled",
+  },
+  "devin-cli": {
+    // Import-first, the kiro shape: adopt the credential the installed CLI
+    // already holds instead of starting a browser flow it has already completed.
+    login: (ctrl, opts) => loginDevinCli(ctrl, opts),
+    refresh: refreshDevinCliToken,
+    providerConfig: oauthConfig("devin-cli"),
+    defaultModel: oauthDefaultModel("devin-cli"),
+    // The CLI owns the session and Cognition exposes no refresh endpoint.
+    defaultRefreshPolicy: "disabled",
+  },
   "github-copilot": {
     login: (ctrl) => loginGithubCopilot(ctrl),
     refresh: (rt, signal) => refreshGithubCopilotToken(rt, signal),
@@ -320,7 +339,7 @@ export const OAUTH_PROVIDERS: Record<string, OAuthProviderDef> = {
     login: (ctrl, opts) => loginChatGPT(ctrl, { forceLogin: opts?.forceLogin, flow: opts?.flow }),
     refresh: (rt) => refreshChatGPTToken(rt),
     providerConfig: { adapter: "openai-responses", baseUrl: "https://chatgpt.com/backend-api/codex", authMode: "forward" as const },
-    defaultModel: "gpt-5.4",
+    defaultModel: "gpt-5.6-luna",
   },
 };
 
diff --git a/src/oauth/login-cli.ts b/src/oauth/login-cli.ts
index 79a3aa6eca..6d1de3abe6 100644
--- a/src/oauth/login-cli.ts
+++ b/src/oauth/login-cli.ts
@@ -65,15 +65,29 @@ export function warnIfLiveReloadSkipped(result: LocalProviderReloadResult | null
   );
 }
 
+/**
+ * The provider wall is the first thing an unfamiliar user sees, so it names the Codex
+ * route before the ~90 provider ids. 'codex' is not in either list on purpose: it is
+ * routed to the account-pool login in dispatch.ts, and 'chatgpt' stays off the public
+ * OAuth surface (isPublicOAuthProvider) because the pool owns that credential.
+ *
+ * It names 'openai-apikey' for the same reason it exists at all: 'openai' now routes to
+ * the pool, so someone who typed it looking for a platform key no longer sees the list
+ * that used to be their only pointer to it.
+ */
+export function loginUsageMessage(): string {
+  return `Usage: ocx login <provider>\n`
+    + `  Codex / ChatGPT: ocx login codex   (account pool, needs a running proxy; 'chatgpt' and\n`
+    + `                   'openai' are the same route. An OpenAI platform key is 'openai-apikey'.)\n`
+    + `  OAuth login:   ${listOAuthProviders().join(", ")}\n`
+    + `  API-key login: ${Object.keys(KEY_LOGIN_PROVIDERS).join(", ")}`;
+}
+
 export async function handleLogin(provider?: string): Promise<void> {
   const name = (provider ?? "").trim().toLowerCase();
   if (isPublicOAuthProvider(name)) return handleOAuthLogin(name);
   if (isKeyLoginProvider(name)) return handleKeyLogin(name);
-  console.error(
-    `Usage: ocx login <provider>\n` +
-      `  OAuth login:   ${listOAuthProviders().join(", ")}\n` +
-      `  API-key login: ${Object.keys(KEY_LOGIN_PROVIDERS).join(", ")}`,
-  );
+  console.error(loginUsageMessage());
   process.exit(1);
 }
 
diff --git a/src/oauth/pool-kernel.ts b/src/oauth/pool-kernel.ts
new file mode 100644
index 0000000000..b36ac88e03
--- /dev/null
+++ b/src/oauth/pool-kernel.ts
@@ -0,0 +1,321 @@
+import type { OcxAccountPoolRotationStrategy } from "../types";
+import type { GenerationContext } from "../lib/state-store-sweeper";
+
+export const POOL_KEY_CODEX = "codex";
+export const POOL_KEY_ANTHROPIC = "anthropic";
+
+/**
+ * Pool key for a generic OAuth provider. Namespaced so a provider can never collide
+ * with the two dedicated kinds, and so `reconcilePoolRotationState` can recognise
+ * the entry as sweepable rather than skipping it as unknown.
+ */
+export function genericPoolKey(providerName: string): string {
+  return `generic:${providerName}`;
+}
+
+interface SelectionState {
+  activeKey?: string;
+  successes: number;
+  currentWeights: Map<string, number>;
+}
+
+const selectionState = new Map<string, SelectionState>();
+let lastReconciledGeneration = 0;
+
+const DEFAULT_STICKY_LIMIT = 1;
+const MIN_STICKY_LIMIT = 1;
+const MAX_STICKY_LIMIT = 100;
+const DEFAULT_STRATEGY: OcxAccountPoolRotationStrategy = "quota";
+const VALID_STRATEGIES = new Set<OcxAccountPoolRotationStrategy>(["quota", "round-robin", "fill-first"]);
+
+/** Selection order for an account with no stored preference: one flat tier. */
+export const DEFAULT_ACCOUNT_PRIORITY = 0;
+export const MIN_ACCOUNT_PRIORITY = -100;
+export const MAX_ACCOUNT_PRIORITY = 100;
+
+/** Strict parse for management APIs — returns null instead of defaulting. */
+export function parseAccountPoolStrategy(raw: unknown): OcxAccountPoolRotationStrategy | null {
+  if (typeof raw === "string" && VALID_STRATEGIES.has(raw as OcxAccountPoolRotationStrategy)) {
+    return raw as OcxAccountPoolRotationStrategy;
+  }
+  return null;
+}
+
+/** Strict parse for management APIs — returns null instead of defaulting. */
+export function parseAccountPoolStickyLimit(raw: unknown): number | null {
+  if (typeof raw === "number" && Number.isInteger(raw) && raw >= MIN_STICKY_LIMIT && raw <= MAX_STICKY_LIMIT) {
+    return raw;
+  }
+  return null;
+}
+
+export function normalizeAccountPoolStrategy(raw: unknown): OcxAccountPoolRotationStrategy {
+  return parseAccountPoolStrategy(raw) ?? DEFAULT_STRATEGY;
+}
+
+export function normalizeAccountPoolStickyLimit(raw: unknown): number {
+  return parseAccountPoolStickyLimit(raw) ?? DEFAULT_STICKY_LIMIT;
+}
+
+/** Strict parse for management APIs — returns null instead of defaulting. */
+export function parseAccountPriority(raw: unknown): number | null {
+  if (
+    typeof raw === "number"
+    && Number.isInteger(raw)
+    && raw >= MIN_ACCOUNT_PRIORITY
+    && raw <= MAX_ACCOUNT_PRIORITY
+  ) {
+    return raw;
+  }
+  return null;
+}
+
+export function normalizeAccountPriority(raw: unknown): number {
+  return parseAccountPriority(raw) ?? DEFAULT_ACCOUNT_PRIORITY;
+}
+
+/**
+ * Narrow an already-eligible account list to the highest selection-order tier that
+ * still has usable quota. Priority is an *ordering* boundary layered on top of
+ * eligibility: it never admits an account the caller already filtered out, and it
+ * never keeps the pool on a tier whose every member is drained.
+ *
+ * Contract (each clause is load-bearing for "no behavior change when unconfigured"):
+ * - one distinct priority across `ids` (the unconfigured case) returns `ids` unchanged,
+ *   so today's pick sequence is preserved byte for byte;
+ * - input order is preserved inside the returned tier, which keeps the `__main__`
+ *   head-of-list bias and the first-index tie-break used by SWRR/lowest-usage;
+ * - every tier drained returns `ids` unchanged, reproducing today's
+ *   stay-put-until-429 behavior rather than inventing a pick;
+ * - a `pinnedId` that is present *and* has headroom lowers the ceiling to its own
+ *   tier, which is what makes a manual "use this now" survive round-robin and
+ *   fill-first without any mutable selection state. A drained or absent pin is
+ *   ignored, so the pin expires on its own once the account crosses the threshold.
+ */
+export function selectPriorityTier(
+  ids: readonly string[],
+  priorityOf: (id: string) => number,
+  hasHeadroom: (id: string) => boolean,
+  pinnedId?: string,
+): readonly string[] {
+  // Readonly out as well as in: the no-change cases return the caller's own array, so a
+  // mutating caller would corrupt its input in exactly the cases that must not change.
+  const list = ids;
+  if (list.length <= 1) return list;
+
+  const priorities = list.map(priorityOf);
+  const firstPriority = priorities[0]!;
+  if (priorities.every(priority => priority === firstPriority)) return list;
+
+  let ceiling = Number.POSITIVE_INFINITY;
+  if (pinnedId !== undefined) {
+    const pinnedIndex = list.indexOf(pinnedId);
+    if (pinnedIndex >= 0 && hasHeadroom(pinnedId)) ceiling = priorities[pinnedIndex]!;
+  }
+
+  const tiers = [...new Set(priorities)].sort((a, b) => b - a);
+  for (const tier of tiers) {
+    if (tier > ceiling) continue;
+    const members = list.filter((_, index) => priorities[index] === tier);
+    if (members.some(hasHeadroom)) return members;
+  }
+  return list;
+}
+
+function getOrCreateState(poolKey: string): SelectionState {
+  let state = selectionState.get(poolKey);
+  if (!state) {
+    state = { successes: 0, currentWeights: new Map() };
+    selectionState.set(poolKey, state);
+  }
+  return state;
+}
+
+function cloneSelectionState(state: SelectionState): SelectionState {
+  return {
+    activeKey: state.activeKey,
+    successes: state.successes,
+    currentWeights: new Map(state.currentWeights),
+  };
+}
+
+function smoothWeightedIndex(ids: readonly string[], state: SelectionState): number {
+  let best = -1;
+  let bestScore = Number.NEGATIVE_INFINITY;
+  let total = 0;
+  const weight = 1;
+  for (let i = 0; i < ids.length; i++) {
+    const id = ids[i]!;
+    const score = (state.currentWeights.get(id) ?? 0) + weight;
+    state.currentWeights.set(id, score);
+    total += weight;
+    if (score > bestScore) {
+      best = i;
+      bestScore = score;
+    }
+  }
+  if (best >= 0) {
+    const key = ids[best]!;
+    state.currentWeights.set(key, (state.currentWeights.get(key) ?? 0) - total);
+  }
+  return best;
+}
+
+/**
+ * Shared pick core. Mutates `state` the same way live resolve does; callers pass
+ * either the live map entry or a scratch/clone for dry-run peek.
+ */
+function pickRoundRobinFromState(
+  eligibleIds: readonly string[],
+  stickyLimit: number,
+  state: SelectionState,
+  commitSticky: boolean,
+): string | null {
+  if (eligibleIds.length === 0) return null;
+
+  const limit = normalizeAccountPoolStickyLimit(stickyLimit);
+
+  if (state.activeKey && eligibleIds.includes(state.activeKey)) {
+    return state.activeKey;
+  }
+
+  if (state.activeKey) {
+    delete state.activeKey;
+    state.successes = 0;
+  }
+
+  const index = smoothWeightedIndex(eligibleIds, state);
+  if (index < 0) return null;
+
+  const picked = eligibleIds[index]!;
+  if (commitSticky && limit > 1) {
+    state.activeKey = picked;
+    state.successes = 0;
+  }
+  return picked;
+}
+
+export function pickRoundRobinAccount(
+  poolKey: string,
+  eligibleIds: readonly string[],
+  stickyLimit: number,
+): string | null {
+  return pickRoundRobinFromState(eligibleIds, stickyLimit, getOrCreateState(poolKey), true);
+}
+
+/**
+ * Dry-run of {@link pickRoundRobinAccount}: returns the same account resolve would
+ * pick without advancing ring weights, activeKey, or successes.
+ */
+export function peekRoundRobinAccount(
+  poolKey: string,
+  eligibleIds: readonly string[],
+  stickyLimit: number,
+): string | null {
+  const live = selectionState.get(poolKey);
+  const scratch = live
+    ? cloneSelectionState(live)
+    : { successes: 0, currentWeights: new Map<string, number>() };
+  return pickRoundRobinFromState(eligibleIds, stickyLimit, scratch, false);
+}
+
+export function notePoolRotationSuccess(
+  poolKey: string,
+  accountId: string,
+  stickyLimit: number,
+): void {
+  const limit = normalizeAccountPoolStickyLimit(stickyLimit);
+  const state = selectionState.get(poolKey);
+  if (!state) return;
+  if (state.activeKey !== accountId) {
+    state.activeKey = accountId;
+    state.successes = 0;
+  }
+  state.successes += 1;
+  if (state.successes >= limit) {
+    delete state.activeKey;
+    state.successes = 0;
+  }
+}
+
+export function notePoolRotationFailure(poolKey: string, accountId: string): void {
+  const state = selectionState.get(poolKey);
+  if (state?.activeKey === accountId) {
+    delete state.activeKey;
+    state.successes = 0;
+  }
+}
+
+/**
+ * Force the next sticky/RR pick onto `accountId` (manual dashboard selection).
+ * Clears sticky success counters and ring weights so the seeded account is held
+ * for the next new-session pick before ordinary rotation resumes.
+ */
+export function seedPoolRotationAccount(poolKey: string, accountId: string): void {
+  const state = getOrCreateState(poolKey);
+  state.activeKey = accountId;
+  state.successes = 0;
+  state.currentWeights.clear();
+}
+
+export function clearPoolRotationState(poolKey?: string): void {
+  if (poolKey === undefined) {
+    selectionState.clear();
+    return;
+  }
+  selectionState.delete(poolKey);
+}
+
+export function reconcilePoolRotationState(context: GenerationContext): number {
+  if (context.generation <= lastReconciledGeneration) return 0;
+  const anthropicIds = new Set<string>();
+  // Live account ids per generic OAuth provider, built from the same
+  // `provider\0id` roster the Anthropic pass already walks. Without this the
+  // `generic:*` entries fall through as unknown and are never swept, so a removed
+  // account would keep its rotation weight forever.
+  const genericIds = new Map<string, Set<string>>();
+  for (const key of context.oauthAccountKeys) {
+    const separator = key.indexOf("\0");
+    if (separator <= 0) continue;
+    const provider = key.slice(0, separator);
+    const accountId = key.slice(separator + 1);
+    if (provider === "anthropic") {
+      anthropicIds.add(accountId);
+      continue;
+    }
+    let bucket = genericIds.get(provider);
+    if (!bucket) {
+      bucket = new Set<string>();
+      genericIds.set(provider, bucket);
+    }
+    bucket.add(accountId);
+  }
+  let removed = 0;
+  for (const [poolKey, state] of selectionState) {
+    const valid = poolKey === POOL_KEY_ANTHROPIC
+      ? anthropicIds
+      : poolKey === POOL_KEY_CODEX || poolKey.startsWith(`${POOL_KEY_CODEX}:`)
+        ? context.codexAccountIds
+        : poolKey.startsWith("generic:")
+          ? genericIds.get(poolKey.slice("generic:".length)) ?? new Set<string>()
+          : null;
+    if (!valid) continue;
+    if (valid.size === 0) {
+      selectionState.delete(poolKey);
+      removed += 1;
+      continue;
+    }
+    if (state.activeKey && !valid.has(state.activeKey)) {
+      delete state.activeKey;
+      state.successes = 0;
+      removed += 1;
+    }
+    for (const accountId of state.currentWeights.keys()) {
+      if (valid.has(accountId)) continue;
+      state.currentWeights.delete(accountId);
+      removed += 1;
+    }
+  }
+  lastReconciledGeneration = context.generation;
+  return removed;
+}
diff --git a/src/oauth/pool-settings-capability.ts b/src/oauth/pool-settings-capability.ts
index 210870b718..946a92d357 100644
--- a/src/oauth/pool-settings-capability.ts
+++ b/src/oauth/pool-settings-capability.ts
@@ -1,5 +1,6 @@
 import { isGenericFailoverProvider } from "./generic-account-failover";
-import type { OcxProviderConfig } from "../types";
+import { parseAccountPoolStickyLimit, parseAccountPoolStrategy } from "./pool-kernel";
+import type { OcxConfig, OcxProviderConfig } from "../types";
 
 /**
  * Which pool-settings contract a provider speaks (#695, slice 1).
@@ -28,33 +29,85 @@ export function poolSettingsCapability(name: string, provider: OcxProviderConfig
 }
 
 export function parseGenericPoolStrategy(value: unknown): GenericPoolStrategy | null {
-  return typeof value === "string" && (GENERIC_POOL_STRATEGIES as readonly string[]).includes(value)
-    ? value as GenericPoolStrategy
-    : null;
+  // Delegated, not re-implemented. Three pools accepting the same three names from three
+  // private copies of the same check is how they drift apart: the Codex and Anthropic kinds
+  // already shared this parser while the generic kind carried its own. The names and the
+  // 1..100 bound live in pool-kernel.ts, once.
+  return parseAccountPoolStrategy(value) as GenericPoolStrategy | null;
 }
 
 export function parseGenericAutoSwitchThreshold(value: unknown): number | null {
   return typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 100 ? value : null;
 }
 
+export function parseGenericStickyLimit(value: unknown): number | null {
+  return parseAccountPoolStickyLimit(value);
+}
+
+/** Fields the unified pool-settings contract can carry, per kind. */
+export const POOL_SETTINGS_FIELDS = [
+  "enabled", "strategy", "stickyLimit", "autoSwitchThreshold", "quotaWindow",
+] as const;
+export type PoolSettingsField = typeof POOL_SETTINGS_FIELDS[number];
+
+/**
+ * One shape for all three pool kinds.
+ *
+ * `supported` is the reason this is a consolidation rather than a fourth contract: a field a
+ * kind does not honour is DECLARED unsupported instead of being omitted, so a dashboard can
+ * tell "this pool has no quotaWindow" from "this response forgot to send one". Every kind
+ * answers with the same keys.
+ */
+export interface PoolSettingsDto {
+  provider: string;
+  kind: PoolSettingsKind;
+  supported: PoolSettingsField[];
+  /** The STORED override. null means nothing is stored here, not "off". */
+  enabled: boolean | null;
+  /**
+   * What the runtime actually resolves for `enabled`, after the global default.
+   *
+   * The generic kind inherits `config.oauthAccountFailover.enabled` when it stores no override
+   * of its own, so `enabled: null` alone cannot distinguish a disabled pool from an inherited
+   * one. This resolves exactly that config question and nothing else -- deliberately NOT the
+   * roster quorum the dispatch predicate also applies, because a settings field that folded in
+   * "how many accounts are logged in" would be answering a different question than it asks.
+   */
+  enabledEffective: boolean;
+  strategy: string | null;
+  stickyLimit: number | null;
+  autoSwitchThreshold: number | null;
+  quotaWindow: string | null;
+}
+
+
 export interface GenericPoolSettingsDto {
   provider: string;
   kind: "generic";
   enabled: boolean | null;
   strategy: GenericPoolStrategy | null;
   autoSwitchThreshold: number | null;
+  stickyLimit: number | null;
   /**
-   * Slice-1 marker for `strategy` and `autoSwitchThreshold` only: persisted, not yet consumed
-   * by the selector.
+   * Marker for `strategy`, `autoSwitchThreshold` and `stickyLimit` only: true while they are
+   * persisted but not consumed by the selector, false once `pool.kernel` is on and they
+   * actually choose an account.
    *
    * It deliberately does NOT describe `enabled`, which governs the pre-dispatch preference.
    * Widening it to the whole DTO would tell a dashboard that `enabled` changes nothing, which
    * has been false since reactive and proactive activation were split.
+   *
+   * Computed, never a literal: the flag is reversible, so a DTO that hard-codes either answer
+   * would be lying in one of the two states.
    */
-  inert: true;
+  inert: boolean;
 }
 
-export function genericPoolSettingsDto(name: string, provider: OcxProviderConfig): GenericPoolSettingsDto {
+export function genericPoolSettingsDto(
+  name: string,
+  provider: OcxProviderConfig,
+  kernelEnabled = false,
+): GenericPoolSettingsDto {
   const failover = provider.oauthAccountFailover ?? {};
   return {
     provider: name,
@@ -62,6 +115,71 @@ export function genericPoolSettingsDto(name: string, provider: OcxProviderConfig
     enabled: typeof failover.enabled === "boolean" ? failover.enabled : null,
     strategy: parseGenericPoolStrategy(failover.strategy),
     autoSwitchThreshold: parseGenericAutoSwitchThreshold(failover.autoSwitchThreshold),
-    inert: true,
+    stickyLimit: parseGenericStickyLimit(failover.stickyLimit),
+    inert: kernelEnabled !== true,
   };
 }
+
+/** Which fields each kind actually honours. Declared, never silently omitted. */
+const SUPPORTED_BY_KIND: Record<PoolSettingsKind, PoolSettingsField[]> = {
+  codex: ["strategy", "stickyLimit", "autoSwitchThreshold"],
+  anthropic: ["enabled", "strategy", "stickyLimit", "autoSwitchThreshold", "quotaWindow"],
+  generic: ["enabled", "strategy", "stickyLimit", "autoSwitchThreshold"],
+};
+
+/**
+ * The one projection behind `/api/pool/settings`.
+ *
+ * Reads each kind's own storage -- this consolidates the CONTRACT, not the persistence -- and
+ * answers with identical keys plus a `supported` list, so an unsupported field is a declared
+ * `null` rather than an absence a caller has to guess about.
+ */
+export function unifiedPoolSettingsDto(
+  config: OcxConfig,
+  provider: string,
+  kind: PoolSettingsKind,
+): PoolSettingsDto {
+  const base = { provider, kind, supported: SUPPORTED_BY_KIND[kind] };
+  if (kind === "codex") {
+    return {
+      ...base,
+      // The Codex pool has no enablement switch: it is on whenever accounts exist, so the
+      // honest answer is "not a field here" rather than a fabricated true.
+      enabled: null,
+      enabledEffective: true,
+      strategy: parseGenericPoolStrategy(config.accountPoolStrategy) ?? "quota",
+      stickyLimit: parseGenericStickyLimit(config.accountPoolStickyLimit) ?? 1,
+      autoSwitchThreshold: parseGenericAutoSwitchThreshold(config.autoSwitchThreshold) ?? 80,
+      quotaWindow: null,
+    };
+  }
+  if (kind === "anthropic") {
+    const pool = config.anthropicAccountPool ?? {};
+    const enabled = typeof pool.enabled === "boolean" ? pool.enabled : null;
+    return {
+      ...base,
+      enabled,
+      enabledEffective: enabled === true,
+      strategy: parseGenericPoolStrategy(pool.strategy) ?? "quota",
+      stickyLimit: parseGenericStickyLimit(pool.stickyLimit) ?? 1,
+      autoSwitchThreshold: parseGenericAutoSwitchThreshold(pool.autoSwitchThreshold) ?? 80,
+      quotaWindow: typeof pool.quotaWindow === "string" ? pool.quotaWindow : "five-hour",
+    };
+  }
+  const failover = config.providers?.[provider]?.oauthAccountFailover ?? {};
+  const stored = typeof failover.enabled === "boolean" ? failover.enabled : null;
+  return {
+    ...base,
+    enabled: stored,
+    // The defect this field exists to close: a generic provider with no stored override
+    // inherits the global, so `enabled: null` alone cannot tell a disabled pool from an
+    // inherited one. Config only -- the roster quorum the dispatch predicate also applies is a
+    // different question and stays out of a settings field.
+    enabledEffective: stored ?? (config.oauthAccountFailover?.enabled === true),
+    strategy: parseGenericPoolStrategy(failover.strategy),
+    stickyLimit: parseGenericStickyLimit(failover.stickyLimit),
+    autoSwitchThreshold: parseGenericAutoSwitchThreshold(failover.autoSwitchThreshold),
+    quotaWindow: null,
+  };
+}
+
diff --git a/src/oauth/store.ts b/src/oauth/store.ts
index e641b81be7..011247dde3 100644
--- a/src/oauth/store.ts
+++ b/src/oauth/store.ts
@@ -29,6 +29,7 @@ import {
   type GenerationContext,
 } from "../lib/state-store-sweeper";
 import { validateCopilotApiBaseUrl } from "./github-copilot";
+import { validateDevinApiBaseUrl } from "./devin/api-base";
 import type { OAuthAccountSelection, OAuthCredentialSource, OAuthCredentials, ProviderAccount, ProviderAccountSet } from "./types";
 
 export type AuthStore = Record<string, ProviderAccountSet>;
@@ -459,9 +460,12 @@ function normalizeCredential(cred: unknown): OAuthCredentials | null {
   if (isCredentialSource(candidate.source)) normalized.source = candidate.source;
   if (typeof candidate.projectId === "string" && candidate.projectId.length > 0) normalized.projectId = candidate.projectId;
   if (typeof candidate.apiBaseUrl === "string" && candidate.apiBaseUrl.length > 0) {
-    // Persist only allowlisted Copilot origins; drop anything else so auth.json cannot
-    // become an SSRF springboard across reloads.
-    const validated = validateCopilotApiBaseUrl(candidate.apiBaseUrl);
+    // Persist only allowlisted origins; drop anything else so auth.json cannot
+    // become an SSRF springboard across reloads. Copilot and Devin are the two
+    // providers whose host comes back from the network, and each owns its own
+    // allowlist.
+    const validated =
+      validateCopilotApiBaseUrl(candidate.apiBaseUrl) ?? validateDevinApiBaseUrl(candidate.apiBaseUrl);
     if (validated) normalized.apiBaseUrl = validated;
   }
   if (candidate.kiro && typeof candidate.kiro === "object") {
diff --git a/src/oauth/token-guardian.ts b/src/oauth/token-guardian.ts
index ff87c1f532..6815e83a3b 100644
--- a/src/oauth/token-guardian.ts
+++ b/src/oauth/token-guardian.ts
@@ -52,7 +52,7 @@ const DEFAULTS = {
   failureBackoffBaseSeconds: 300,
   failureBackoffMaxSeconds: 3600,
   codexWarmupMaxAgeSeconds: 691_200, // 8d — matches Codex managed-auth last_refresh cadence.
-  codexWarmupModel: "gpt-5.4-mini",
+  codexWarmupModel: "gpt-5.6-luna",
 };
 
 interface BackoffEntry {
diff --git a/src/providers/codebuddy-models.ts b/src/providers/codebuddy-models.ts
index edd6a30415..ceb7463ce8 100644
--- a/src/providers/codebuddy-models.ts
+++ b/src/providers/codebuddy-models.ts
@@ -35,7 +35,6 @@ export const CODEBUDDY_GLOBAL_MODELS = [
 /** China (`internal`) session models from the official internal manifest (text/chat models only). */
 export const CODEBUDDY_CN_MODELS = [
   "default",
-  "deepseek-v4-pro",
   "deepseek-v4-flash",
   "minimax-m3",
   "minimax-m2.7",
@@ -121,7 +120,6 @@ export const CODEBUDDY_GLOBAL_MODEL_DEFAULT_REASONING_EFFORTS: Record<string, st
 
 export const CODEBUDDY_CN_MODEL_CONTEXT_WINDOWS: Record<string, number> = {
   "default": 200_000,
-  "deepseek-v4-pro": 1_000_000,
   "deepseek-v4-flash": 1_000_000,
   "minimax-m3": 512_000,
   "minimax-m2.7": 200_000,
@@ -142,7 +140,6 @@ export const CODEBUDDY_CN_MODEL_CONTEXT_WINDOWS: Record<string, number> = {
 
 export const CODEBUDDY_CN_MODEL_MAX_OUTPUT_TOKENS: Record<string, number> = {
   "default": 24_000,
-  "deepseek-v4-pro": 50_000,
   "deepseek-v4-flash": 50_000,
   "minimax-m3": 128_000,
   "minimax-m2.7": 48_000,
diff --git a/src/providers/command-code-efforts.ts b/src/providers/command-code-efforts.ts
index 621eb330bc..31a11e3af5 100644
--- a/src/providers/command-code-efforts.ts
+++ b/src/providers/command-code-efforts.ts
@@ -1,10 +1,6 @@
 import { readBoundedResponseBody } from "../lib/bounded-body";
 
 const COMMAND_CODE_MODEL_EFFORTS = {
-  "deepseek/deepseek-v4-pro": {
-    efforts: ["high", "max"],
-    profileUrl: "https://commandcode.ai/models/deepseek-v4-pro",
-  },
   "deepseek/deepseek-v4-flash": {
     efforts: ["high", "max"],
     profileUrl: "https://commandcode.ai/models/deepseek-v4-flash",
@@ -130,6 +126,29 @@ const COMMAND_CODE_MODEL_EFFORTS = {
     efforts: ["low", "medium", "high", "xhigh", "max"],
     profileUrl: "https://commandcode.ai/models/meta-muse-spark-1.1",
   },
+  /*
+   * Two live routes that never gained a row here, so the adapter dropped every
+   * requested effort (a client's `max` left the wire as no reasoning parameter
+   * at all) and the preset advertised no effort control for them.
+   *
+   * PROVENANCE, stated plainly: both ladders are inferred from the same-family
+   * rows above — deepseek v4: high..max; the Qwen 3.8 family: low..max — NOT
+   * read from the profile pages. commandcode.ai renders those client-side and
+   * ships an empty reasoning payload, so the self-refresh below is as dead for
+   * these rows as the #2647 block above already documents. Measured live
+   * 2026-09-11: /alpha/generate accepts `reasoning_effort: "max"` on both
+   * routes (HTTP 200). `ultra` is deliberately not offered: the adapter would
+   * strip it, and no profile evidence backs an ultra→max alias the way it does
+   * for v4-pro/v4-flash above.
+   */
+  "deepseek/deepseek-v4.1-flash": {
+    efforts: ["high", "max"],
+    profileUrl: "https://commandcode.ai/models/deepseek-v4-1-flash",
+  },
+  "Qwen/Qwen3.8-Flash": {
+    efforts: ["low", "medium", "high", "max"],
+    profileUrl: "https://commandcode.ai/models/qwen3-8-flash",
+  },
 } as const;
 
 /**
diff --git a/src/providers/default-aliases.ts b/src/providers/default-aliases.ts
index dffbd9eb3c..30128db749 100644
--- a/src/providers/default-aliases.ts
+++ b/src/providers/default-aliases.ts
@@ -51,7 +51,11 @@ export const DEFAULT_MODEL_ALIASES: ReadonlyArray<{ match: RegExp; alias: string
   { match: /^claude-haiku/, alias: "haiku" },
   { match: /^gemini-3(?:\.\d+)?-pro/, alias: "g3p" },
   { match: /^gemini-3(?:\.\d+)?-flash/, alias: "g3f" },
+  // Ordered before the V4 rule on purpose: `builtinRule` takes the first match, and
+  // `/^deepseek-v4/` also matches `deepseek-v4.1-flash`.
+  { match: /^deepseek-v4\.1/, alias: "ds41" },
   { match: /^deepseek-v4/, alias: "ds4" },
+  { match: /^deepseek-flash/, alias: "dsf" },
   { match: /^grok-4/, alias: "grok" },
 ];
 
diff --git a/src/providers/derive.ts b/src/providers/derive.ts
index 67e6c0522e..72a662aee4 100644
--- a/src/providers/derive.ts
+++ b/src/providers/derive.ts
@@ -16,6 +16,7 @@ export interface DerivedKeyLoginProvider {
   label: string;
   baseUrl: string;
   responsesPath?: string;
+  chatCompletionsPath?: string;
   adapter: string;
   apiKeyValidation?: "unknown";
   apiKeyTransport?: OcxProviderConfig["apiKeyTransport"];
@@ -71,6 +72,7 @@ export interface DerivedProviderPreset {
   adapter: string;
   baseUrl: string;
   responsesPath?: string;
+  chatCompletionsPath?: string;
   defaultModel?: string;
   auth: "oauth" | "forward" | "key" | "local";
   codexAccountMode?: CodexAccountMode;
@@ -222,6 +224,7 @@ export function providerConfigSeed(entry: ProviderRegistryEntry): OcxProviderCon
     baseUrl: entry.baseUrl,
     ...(entry.apiKeyTransport !== undefined ? { apiKeyTransport: entry.apiKeyTransport } : {}),
     ...(entry.responsesPath ? { responsesPath: entry.responsesPath } : {}),
+    ...(entry.chatCompletionsPath ? { chatCompletionsPath: entry.chatCompletionsPath } : {}),
     ...(entry.alias ? { alias: entry.alias } : {}),
     // Preserve the registry auth kind verbatim (including "local") so fail-closed gates that
     // distinguish local runtimes from API-key providers keep working after the seed round-trip.
@@ -257,6 +260,7 @@ export function providerConfigSeed(entry: ProviderRegistryEntry): OcxProviderCon
     ...(entry.chatServiceTier !== undefined ? { chatServiceTier: entry.chatServiceTier } : {}),
     ...(entry.openaiChatEofTolerance !== undefined ? { openaiChatEofTolerance: entry.openaiChatEofTolerance } : {}),
     ...(entry.responsesPath !== undefined ? { responsesPath: entry.responsesPath } : {}),
+    ...(entry.chatCompletionsPath !== undefined ? { chatCompletionsPath: entry.chatCompletionsPath } : {}),
     ...(entry.statelessResponses !== undefined ? { statelessResponses: entry.statelessResponses } : {}),
     ...(entry.requiresAdjacentResponsesToolResults !== undefined
       ? { requiresAdjacentResponsesToolResults: entry.requiresAdjacentResponsesToolResults }
@@ -288,6 +292,7 @@ export function deriveKeyLoginMap(): Record<string, DerivedKeyLoginProvider> {
       label: entry.label,
       baseUrl: entry.baseUrl,
       ...(entry.responsesPath ? { responsesPath: entry.responsesPath } : {}),
+      ...(entry.chatCompletionsPath ? { chatCompletionsPath: entry.chatCompletionsPath } : {}),
       adapter: entry.adapter,
       ...(entry.apiKeyValidation !== undefined ? { apiKeyValidation: entry.apiKeyValidation } : {}),
       ...(entry.apiKeyTransport !== undefined ? { apiKeyTransport: entry.apiKeyTransport } : {}),
@@ -478,6 +483,7 @@ export function enrichProviderFromRegistry(name: string, prov: OcxProviderConfig
   if (prov.apiKeyTransport === undefined && seed.apiKeyTransport !== undefined) prov.apiKeyTransport = seed.apiKeyTransport;
   if (!prov.defaultModel && seed.defaultModel) prov.defaultModel = seed.defaultModel;
   if (prov.responsesPath === undefined && seed.responsesPath !== undefined) prov.responsesPath = seed.responsesPath;
+  if (prov.chatCompletionsPath === undefined && seed.chatCompletionsPath !== undefined) prov.chatCompletionsPath = seed.chatCompletionsPath;
   // Fill mode only when absent: an explicit persisted `direct` must never be overwritten.
   if (prov.codexAccountMode === undefined && seed.codexAccountMode !== undefined) prov.codexAccountMode = seed.codexAccountMode;
   if (!prov.models && seed.models) prov.models = [...seed.models];
@@ -521,6 +527,7 @@ export function enrichProviderFromRegistry(name: string, prov: OcxProviderConfig
   // Fill-only: a hand-edited path must survive, and a config saved before the registry
   // learned this route still gets backfilled.
   if (prov.responsesPath === undefined && seed.responsesPath !== undefined) prov.responsesPath = seed.responsesPath;
+  if (prov.chatCompletionsPath === undefined && seed.chatCompletionsPath !== undefined) prov.chatCompletionsPath = seed.chatCompletionsPath;
   if (prov.statelessResponses === undefined && seed.statelessResponses !== undefined) prov.statelessResponses = seed.statelessResponses;
   if (prov.requiresAdjacentResponsesToolResults === undefined && seed.requiresAdjacentResponsesToolResults !== undefined) {
     prov.requiresAdjacentResponsesToolResults = seed.requiresAdjacentResponsesToolResults;
@@ -602,6 +609,7 @@ function entryToPreset(entry: ProviderRegistryEntry): DerivedProviderPreset {
     adapter: entry.adapter,
     baseUrl: entry.baseUrl,
     ...(entry.responsesPath ? { responsesPath: entry.responsesPath } : {}),
+    ...(entry.chatCompletionsPath ? { chatCompletionsPath: entry.chatCompletionsPath } : {}),
     auth: entry.authKind === "forward" ? "forward" : entry.authKind === "oauth" ? "oauth" : entry.authKind === "local" ? "local" : "key",
     ...(entry.codexAccountMode ? { codexAccountMode: entry.codexAccountMode } : {}),
     ...(entry.codexAccountMode ? { provider: providerConfigSeed(entry) } : {}),
diff --git a/src/providers/devin-cli-authmode-migration.ts b/src/providers/devin-cli-authmode-migration.ts
new file mode 100644
index 0000000000..1dba274e37
--- /dev/null
+++ b/src/providers/devin-cli-authmode-migration.ts
@@ -0,0 +1,57 @@
+/**
+ * Repair a saved `devin-cli` row that still claims `authMode: "local"`.
+ *
+ * `derive.ts` seeds `authMode` from the registry's `authKind`, so every config
+ * written while `devin-cli` was a local provider carries `"local"`. The registry
+ * now classifies it as an account provider, and the management write boundary
+ * fails closed on that mismatch: `auth-cors.ts` rejects `authMode: "local"` when
+ * the registry entry is not local. Without this, an existing install can no
+ * longer save provider changes from the dashboard.
+ *
+ * It rewrites exactly that one field, on exactly that mismatch. A row the user
+ * retargeted at another adapter is left alone, and so is any other value.
+ *
+ * It also WARNS, without changing anything, when the saved row still names the
+ * ACP adapter. That field no longer selects the transport — `routedProviderConfig`
+ * pins the adapter from the registry for any row whose name is a registry id — so
+ * an operator who deliberately chose ACP would otherwise switch transports
+ * silently. The warning names the custom-id row that still gets them ACP.
+ */
+import { PROVIDER_REGISTRY } from "./registry";
+import type { OcxConfig } from "../types";
+
+export interface DevinCliAuthModeProjection {
+  config: OcxConfig;
+  changed: boolean;
+  warnings: string[];
+}
+
+const ACP_ESCAPE_HATCH =
+  'a custom-named row still reaches it, e.g. "devin-acp": { "adapter": "devin-cli", "baseUrl": "https://cli.devin.ai" }';
+
+export function projectDevinCliAuthMode(config: OcxConfig): DevinCliAuthModeProjection {
+  const warnings: string[] = [];
+  const prov = config.providers?.["devin-cli"];
+  if (!prov) return { config, changed: false, warnings };
+
+  const entry = PROVIDER_REGISTRY.find(row => row.id === "devin-cli");
+  if (!entry || entry.authKind !== "oauth") return { config, changed: false, warnings };
+
+  // Non-mutating: the saved adapter no longer decides the transport, so leaving
+  // it in place preserves nothing except a signal worth reporting once.
+  if (prov.adapter === "devin-cli") {
+    warnings.push(
+      'the saved "devin-cli" row names the ACP adapter, but that provider id now streams over '
+      + `Cognition's api-server and the adapter is pinned from the registry; for the CLI's own agent loop, ${ACP_ESCAPE_HATCH}.`,
+    );
+  }
+
+  if (prov.authMode !== "local") return { config, changed: warnings.length > 0 ? false : false, warnings };
+  prov.authMode = "oauth";
+  warnings.push(
+    'rewrote "devin-cli" authMode local -> oauth: the registry no longer classifies it as local, '
+    + "and the management write boundary fails closed on the mismatch.",
+  );
+  return { config, changed: true, warnings };
+}
+
diff --git a/src/providers/key-failover.ts b/src/providers/key-failover.ts
index ad4d61ba8d..d5ccd759e3 100644
--- a/src/providers/key-failover.ts
+++ b/src/providers/key-failover.ts
@@ -15,6 +15,10 @@ import type { OcxConfig, OcxProviderConfig, RateLimitRetryPolicy, TransientRetry
 import { OPENCODE_GO_SESSION_HEADER } from "./opencode-go-transport";
 import { resolveProviderTransport, type OcxProviderTransport } from "./xai-transport";
 import { sweepExpiredOnWrite } from "../lib/state-store-sweeper";
+// quota-key-accounts imports only node:crypto, the key store and the quota types -- NOT
+// providers/quota.ts -- so the cached reader reaches the dispatch path without dragging the
+// probe machinery onto it.
+import { cachedApiKeyQuota } from "./quota-key-accounts";
 
 // ---- cooldown state (in-memory, same as codex/routing.ts) ----
 
@@ -100,6 +104,177 @@ export function hasKeyPoolFailover(provider: OcxProviderConfig): boolean {
   return (provider.apiKeyPool?.length ?? 0) >= 2;
 }
 
+/**
+ * Process-local round-robin cursor per provider, deliberately parallel to `keyCooldowns`
+ * rather than borrowing the Codex pool-rotation state: an API key is not an OAuth account
+ * and must not share a quota scope key. Multi-process desync is the same accepted limit
+ * the cooldown map already carries.
+ */
+const keyRotationCursor = new Map<string, string>();
+
+/**
+ * Forget a provider's cursor so an operator's manual key selection is not second-guessed.
+ *
+ * Optional name, mirroring `clearKeyCooldowns`, because the batch provider PUT rewrites the
+ * entire roster: a cursor that survives a reorder still names a real id, so round-robin
+ * resumes after the pre-edit position and can skip the first eligible key in the new pool.
+ */
+export function forgetApiKeyRotationCursor(providerName?: string): void {
+  if (!providerName) {
+    keyRotationCursor.clear();
+    return;
+  }
+  keyRotationCursor.delete(providerName);
+}
+
+/** The pool entry shape is inline on OcxProviderConfig; name it once rather than re-spelling it. */
+type ApiKeyPoolEntry = NonNullable<OcxProviderConfig["apiKeyPool"]>[number];
+
+/**
+ * Remaining headroom for one key, or null when nothing current measures it.
+ *
+ * Same definition as `headroomOf` on the OAuth side, so the two pools cannot disagree about
+ * what "more room" means. `creditsUsd` is deliberately excluded: it is a currency amount, not
+ * a percentage, and ranking one against the other produces an order that means nothing.
+ */
+function keyHeadroom(providerName: string, provider: OcxProviderConfig, entry: ApiKeyPoolEntry): number | null {
+  const quota = cachedApiKeyQuota(providerName, provider, entry.id, entry.key);
+  if (!quota) return null;
+  const percents = [
+    quota.fiveHourPercent,
+    quota.weeklyPercent,
+    quota.monthlyPercent,
+    ...(quota.customWindows ?? []).map((window: { percent?: number }) => window.percent),
+  ].filter((value): value is number => typeof value === "number");
+  if (percents.length === 0) return null;
+  return 100 - Math.max(...percents);
+}
+
+/**
+ * Order eligible keys best-first, in the same three buckets `rankAccountsByHeadroom` uses:
+ * measured-with-headroom, then unmeasured, then measured-and-spent. Ties keep the roster order.
+ *
+ * An unmeasured key is NOT assumed spent, and not assumed fresh either -- it sits between the
+ * two, which is the only honest position for a key nothing has looked at. A provider that
+ * publishes no per-key differentiation (DeepSeek reports every key at the same percent) ties
+ * across the board and falls through to the roster order, which is exactly today's behaviour.
+ */
+function rankKeysByHeadroom(
+  providerName: string,
+  provider: OcxProviderConfig,
+  eligible: readonly ApiKeyPoolEntry[],
+): ApiKeyPoolEntry[] {
+  return eligible
+    .map((entry, index) => {
+      const headroom = keyHeadroom(providerName, provider, entry);
+      const bucket = headroom === null ? 1 : headroom <= 0 ? 2 : 0;
+      return { entry, bucket, headroom: headroom ?? 0, index };
+    })
+    .sort((left, right) => (left.bucket - right.bucket)
+      || (right.headroom - left.headroom)
+      || (left.index - right.index))
+    .map(row => row.entry);
+}
+
+
+/**
+ * Pick a better key BEFORE the first attempt when the committed one is already cooling.
+ *
+ * This is intentionally narrow. It never overrides a healthy key: if the committed
+ * `apiKey` is not in cooldown it returns null, so an operator's manual selection stands
+ * and no config write happens. It only acts when the committed key is known-cooled (or
+ * missing from the pool), which is exactly the case where the first request would
+ * otherwise be spent earning a 429 the runtime could already predict.
+ *
+ * Returning null is the common path, so the persisted-selection transaction is not on
+ * the per-request hot path.
+ *
+ * Like `rotateKeyAfterFailure`, the returned object is a snapshot of the PERSISTED config
+ * and carries none of the registry backfills `routedProviderConfig` merges in at request
+ * time. A request path must not assign it to an active route wholesale -- for a built-in
+ * provider stored in its valid minimal form that would drop the adapter id, the base URL and
+ * the static headers, so `resolveAdapter()` throws `Unknown adapter: undefined` and a
+ * hand-built URL dereferences a missing `baseUrl`. Use
+ * `selectProactiveApiKeyTransport`, the pre-dispatch twin of `rotateProviderTransportOn429`.
+ */
+export function selectProactiveApiKey(
+  config: OcxConfig,
+  providerName: string,
+  now = Date.now(),
+): OcxProviderConfig | null {
+  const provider = config.providers?.[providerName];
+  if (!provider) return null;
+  const strategy = provider.apiKeyPoolStrategy;
+  if (!strategy) return null;
+  if (!hasKeyPoolFailover(provider)) return null;
+  const pool = provider.apiKeyPool ?? [];
+
+  const activeEntry = pool.find(entry => entry.key === provider.apiKey);
+  // A healthy committed key wins, whether the operator chose it or a previous rotation did.
+  if (activeEntry && !isKeyInCooldown(providerName, activeEntry.id, now)) return null;
+
+  const eligible = pool.filter(entry => !isKeyInCooldown(providerName, entry.id, now));
+  if (eligible.length === 0) return null;
+
+  let chosen = eligible[0]!;
+  if (strategy === "round-robin") {
+    const lastId = keyRotationCursor.get(providerName);
+    const lastIndex = lastId ? pool.findIndex(entry => entry.id === lastId) : -1;
+    for (let offset = 1; offset <= pool.length; offset += 1) {
+      const candidate = pool[(lastIndex + offset) % pool.length]!;
+      if (isKeyInCooldown(providerName, candidate.id, now)) continue;
+      chosen = candidate;
+      break;
+    }
+  } else if (strategy === "quota") {
+    // else-if, deliberately. `fill-first` is not a named branch here -- it is the eligible[0]
+    // default above, so replacing that default would silently retarget it.
+    chosen = rankKeysByHeadroom(providerName, provider, eligible)[0] ?? chosen;
+  }
+  if (chosen.key === provider.apiKey) return null;
+
+  const outcome = commitProviderApiKeySelection<string | null>(config, providerName, freshProvider => {
+    const freshPool = freshProvider.apiKeyPool ?? [];
+    const target = freshPool.find(entry => entry.id === chosen.id);
+    if (!target) return { changed: false, value: null };
+    if (freshProvider.apiKey === target.key) return { changed: false, value: null };
+    const freshActive = freshPool.find(entry => entry.key === freshProvider.apiKey);
+    // Re-check under the lock: a concurrent manual selection may have landed a healthy key.
+    if (freshActive && !isKeyInCooldown(providerName, freshActive.id, now)) {
+      return { changed: false, value: null };
+    }
+    freshProvider.apiKey = target.key;
+    return { changed: true, value: target.id };
+  });
+  if (outcome.status !== "committed" || outcome.value === null) return null;
+
+  keyRotationCursor.set(providerName, outcome.value);
+  const committed = structuredClone(outcome.provider);
+  config.providers[providerName] = committed;
+  return structuredClone(committed);
+}
+
+/**
+ * Pre-dispatch twin of `rotateProviderTransportOn429`: pick a warm key, then rebuild the
+ * active route from the committed row through the same seam the 429 path uses, so the
+ * registry backfills survive and only explicit runtime transport state (`fetch` and a
+ * generated OpenCode session header) is carried over from the route being replaced.
+ *
+ * Every request path that assigns the result to a live route must call THIS, not
+ * `selectProactiveApiKey`, which answers with a persisted snapshot.
+ */
+export function selectProactiveApiKeyTransport(
+  config: OcxConfig,
+  providerName: string,
+  routedProvider: OcxProviderTransport,
+  promptCacheKey?: string,
+  now = Date.now(),
+): OcxProviderTransport | null {
+  const committed = selectProactiveApiKey(config, providerName, now);
+  if (!committed) return null;
+  return applyRotatedTransport(providerName, routedProvider, committed, promptCacheKey);
+}
+
 /**
  * Normalize a provider's `retryOn429` policy, or return null when the knob is absent,
  * explicitly disabled, or the provider is not key-auth (OAuth/forward credentials must not be
diff --git a/src/providers/model-rename-startup.ts b/src/providers/model-rename-startup.ts
index 7112e7cdd8..51f1b35da8 100644
--- a/src/providers/model-rename-startup.ts
+++ b/src/providers/model-rename-startup.ts
@@ -1,7 +1,27 @@
 import { mutatePersistedConfig } from "../config";
 import { projectModelRenames } from "./model-rename-migration";
+import { projectStaleContextWindows } from "./stale-context-window-migration";
+import { projectDevinCliAuthMode } from "./devin-cli-authmode-migration";
 import type { OcxConfig } from "../types";
 
+/**
+ * The startup projection: registry model renames, then the context-window
+ * repair. Both fix a saved row the registry can no longer reach on its own —
+ * `enrichProviderFromRegistry` backfills a missing field and never rewrites a
+ * present one — so they share this pass rather than adding a second boot step
+ * with its own persistence, adopt, and failure handling.
+ */
+export function projectStartupConfigRepairs(config: OcxConfig): ReturnType<typeof projectModelRenames> {
+  const renames = projectModelRenames(config);
+  const windows = projectStaleContextWindows(renames.config);
+  const devinCli = projectDevinCliAuthMode(windows.config);
+  return {
+    config: devinCli.config,
+    changed: renames.changed || windows.changed || devinCli.changed,
+    warnings: [...renames.warnings, ...windows.warnings, ...devinCli.warnings],
+  };
+}
+
 export interface ModelRenameStartupDeps {
   project: typeof projectModelRenames;
   /** Injected writer for tests and callers that own their own persistence. */
@@ -59,7 +79,7 @@ function adoptConfig(target: OcxConfig, source: OcxConfig): void {
  */
 export function runModelRenameStartupMigration(
   config: OcxConfig,
-  deps: ModelRenameStartupDeps = { project: projectModelRenames },
+  deps: ModelRenameStartupDeps = { project: projectStartupConfigRepairs },
 ): OcxConfig {
   const projection = deps.project(structuredClone(config));
   if (!projection.changed) {
diff --git a/src/providers/qoder-models.ts b/src/providers/qoder-models.ts
index 0f8d8c4350..bb127aedba 100644
--- a/src/providers/qoder-models.ts
+++ b/src/providers/qoder-models.ts
@@ -10,7 +10,6 @@ export const QODER_GLOBAL_MODELS = [
   "Kimi-K2.7-Code",
   "GLM-5.3",
   "GLM-5.2",
-  "DeepSeek-V4-Pro",
 ] as const;
 
 /** Live Qoder CN roster captured from the official CLI on 2026-09-03. */
diff --git a/src/providers/quota-key-accounts.ts b/src/providers/quota-key-accounts.ts
index 7f406e0bed..21d4124201 100644
--- a/src/providers/quota-key-accounts.ts
+++ b/src/providers/quota-key-accounts.ts
@@ -29,6 +29,56 @@ export function clearProviderApiKeyQuotaCache(): void {
   flights.clear();
 }
 
+/**
+ * Cached-only, synchronous per-key quota. Never probes, never awaits, never schedules a read.
+ *
+ * The selector that calls this sits on the first-attempt path, where a network read would be a
+ * worse defect than the one it is there to fix. A miss is simply "no evidence".
+ *
+ * An `unavailable` row is a miss too, and that is the whole point of the check. `readEntry`
+ * keeps a last-good quota attached for up to LAST_GOOD_MS after a probe starts failing, so
+ * returning `entry.quota` on any hit would rank on a number up to half an hour stale -- and
+ * rank it ABOVE a key with no row at all. Last-good is a display value, not a selection input.
+ *
+ * A SUCCESSFUL row expires too, on exactly `readEntry`'s freshness predicate. Checking only
+ * `unavailable` was not enough: nothing on the selection path probes or sweeps, so once a
+ * dashboard or CLI read had populated the cache, a row could outlive ACCOUNT_QUOTA_TTL_MS and
+ * keep a "roomy" ten-minute-old measurement ranked above a key with no evidence at all --
+ * until some unrelated write happened to sweep it. Expired is no evidence, same as absent.
+ */
+export function cachedApiKeyQuota(
+  name: string,
+  provider: OcxProviderConfig,
+  keyId: string,
+  key: string,
+): ProviderQuota | null {
+  let resolved: string | undefined;
+  // resolveProviderApiKey swallows its own failures; the catch is belt-and-braces because this
+  // runs on the dispatch path and must not throw there under any future change.
+  try { resolved = resolveProviderApiKey(key)?.trim(); } catch { return null; }
+  if (!resolved) return null;
+  const entry = cache.get(identity(name, provider, keyId, resolved));
+  if (!entry || entry.unavailable || !entry.quota) return null;
+  const now = Date.now();
+  if (now - entry.ts >= ACCOUNT_QUOTA_TTL_MS) return null;
+  if (now - entry.quota.updatedAt >= LAST_GOOD_MS) return null;
+  return entry.quota;
+}
+
+/** Test seam: keyed on identity(), so it takes the raw key rather than an account id. */
+export function setCachedProviderApiKeyQuotaForTests(
+  name: string,
+  provider: OcxProviderConfig,
+  keyId: string,
+  key: string,
+  quota: ProviderQuota | null,
+  unavailable?: true,
+): void {
+  const resolved = resolveProviderApiKey(key)?.trim();
+  if (!resolved) return;
+  remember(identity(name, provider, keyId, resolved), { ts: Date.now(), quota, ...(unavailable ? { unavailable } : {}) });
+}
+
 /** Four workers per roster, not a process-wide network limit. */
 export async function mapQuotaRoster<T, R>(rows: readonly T[], read: (row: T) => Promise<R>): Promise<R[]> {
   const out = new Array<R>(rows.length);
diff --git a/src/providers/quota-routing-cache.ts b/src/providers/quota-routing-cache.ts
index 065d7338ca..274d07feec 100644
--- a/src/providers/quota-routing-cache.ts
+++ b/src/providers/quota-routing-cache.ts
@@ -1,32 +1,91 @@
+import { createHash } from "node:crypto";
+import type { OcxProviderConfig } from "../types";
 import type { ProviderQuota, ProviderQuotaReport } from "./quota";
+import { providerUsesKeyAuthOverride, resolveProviderApiKey } from "./key-store";
+import { getProviderRegistryEntry } from "./registry";
+import { PROVIDER_QUOTA_MAX_AGE_MS } from "./quota-types";
 
-const quotaCache = new Map<string, ProviderQuota>();
+export interface ProviderQuotaRoutingEvidence {
+  quota: ProviderQuota;
+  binding: string;
+}
+
+type CachedQuota = {
+  quota: ProviderQuota;
+  routing?: ProviderQuotaRoutingEvidence | { quota: ProviderQuota; testOnly: true };
+};
+
+const quotaCache = new Map<string, CachedQuota>();
+
+/** Private cache identity; neither key material nor this digest enters management reports. */
+export function providerQuotaRoutingBinding(
+  name: string,
+  provider: OcxProviderConfig,
+  credential = resolveProviderApiKey(provider.apiKey)?.trim(),
+): string | null {
+  if ((provider.authMode ?? "key") !== "key" || !credential) return null;
+  // Registry-owned OAuth/forward rows normalize saved authMode before dispatch.
+  // A key probe must not constrain that later account selection.
+  const entry = getProviderRegistryEntry(name);
+  if (entry && (entry.authKind === "oauth" || entry.authKind === "forward")
+    && !providerUsesKeyAuthOverride(entry, provider, credential)) return null;
+  // Static auth headers can replace or combine with the probed API-key header.
+  // Its semantics belong to the adapter, so it is not provider-wide quota evidence.
+  if (Object.keys(provider.headers ?? {}).some(header =>
+    ["authorization", "x-api-key", "x-goog-api-key"].includes(header.toLowerCase()))) return null;
+  return createHash("sha256").update(JSON.stringify([
+    name, provider.adapter, provider.baseUrl, credential,
+  ])).digest("hex");
+}
 
 export function clearCachedProviderQuotas(): void {
   quotaCache.clear();
 }
 
-export function replaceCachedProviderQuotas(reports: ProviderQuotaReport[]): void {
+export function replaceCachedProviderQuotas(
+  reports: ProviderQuotaReport[],
+  routingEvidence?: WeakMap<ProviderQuotaReport, ProviderQuotaRoutingEvidence>,
+): void {
   quotaCache.clear();
   for (const report of reports) {
-    quotaCache.set(report.provider, report.quota);
+    quotaCache.set(report.provider, { quota: report.quota, routing: routingEvidence?.get(report) });
   }
 }
 
 export function getCachedProviderQuota(
   provider: string,
   now: number,
-  maxAgeMs = 30 * 60_000,
+  maxAgeMs = PROVIDER_QUOTA_MAX_AGE_MS,
 ): ProviderQuota | null {
-  const quota = quotaCache.get(provider);
+  const quota = quotaCache.get(provider)?.quota;
   if (!quota) return null;
   if (now - quota.updatedAt > maxAgeMs) return null;
   return quota;
 }
 
+/** Only inference-wide evidence for this sole credential may rank or veto a whole provider. */
+export function getCachedProviderRoutingQuota(
+  name: string,
+  provider: OcxProviderConfig | undefined,
+  now: number,
+  maxAgeMs = PROVIDER_QUOTA_MAX_AGE_MS,
+): ProviderQuota | null {
+  if (!provider || provider.disabled === true || (provider.authMode ?? "key") !== "key") return null;
+  // An active-key report cannot speak for the other keys the dispatcher may select.
+  if ((provider.apiKeyPool?.length ?? 0) > 1) return null;
+  const routing = quotaCache.get(name)?.routing;
+  if (!routing || !Number.isFinite(routing.quota.updatedAt) || routing.quota.updatedAt < 0
+    || routing.quota.updatedAt > now || now - routing.quota.updatedAt >= maxAgeMs) return null;
+  const binding = providerQuotaRoutingBinding(name, provider);
+  if (!binding || (!("testOnly" in routing) && routing.binding !== binding)) return null;
+  return routing.quota;
+}
+
 export function setCachedProviderQuotaForTests(
   provider: string,
   quota: ProviderQuota,
 ): void {
-  quotaCache.set(provider, quota);
+  // Unit tests deliberately assert the supplied quota's scope. Production publication
+  // requires the producer's private, credential-bound evidence map above.
+  quotaCache.set(provider, { quota, routing: { quota, testOnly: true } });
 }
diff --git a/src/providers/quota-types.ts b/src/providers/quota-types.ts
index 873eb30221..e0bdf9cb4f 100644
--- a/src/providers/quota-types.ts
+++ b/src/providers/quota-types.ts
@@ -8,6 +8,13 @@
  * blocks any later attempt to load one side without the other.
  */
 
+export const PROVIDER_QUOTA_MAX_AGE_MS = 30 * 60_000;
+
+/** Management-only eligibility evidence; private credential binding never leaves the server. */
+export type ProviderRoutingQuota =
+  | { state: "unknown" }
+  | { state: "available" | "exhausted"; updatedAt: number; validUntil: number };
+
 export interface ProviderQuotaWindow {
   label: string;
   percent: number;
diff --git a/src/providers/quota.ts b/src/providers/quota.ts
index 79e6a6bf91..fbff1afb1a 100644
--- a/src/providers/quota.ts
+++ b/src/providers/quota.ts
@@ -39,7 +39,9 @@ import {
 } from "./quota-wire";
 import {
   clearCachedProviderQuotas,
+  providerQuotaRoutingBinding,
   replaceCachedProviderQuotas,
+  type ProviderQuotaRoutingEvidence,
 } from "./quota-routing-cache";
 import {
   aggregateCodexPoolCapacity,
@@ -52,6 +54,7 @@ import type {
   ProviderQuota,
   ProviderQuotaCreditsUsd,
   ProviderQuotaWindow,
+  ProviderRoutingQuota,
 } from "./quota-types";
 import {
   clearKiroAccountUsageState,
@@ -103,6 +106,7 @@ const XAI_CREDITS_URL = `${XAI_BILLING_URL}?format=credits`;
 const LAST_GOOD_MAX_AGE_MS = CODEX_CAPACITY_MAX_QUOTA_AGE_MS;
 const nativeMainReportGenerations = new WeakMap<ProviderQuotaReport, number>();
 const accountReportCurrent = new WeakMap<ProviderQuotaReport, () => boolean>();
+const routingEvidence = new WeakMap<ProviderQuotaReport, ProviderQuotaRoutingEvidence>();
 let providerQuotaBeforePublishForTests: (() => void | Promise<void>) | null = null;
 
 /** Test-only seam for identity/config invalidation after probes but before publication. */
@@ -136,6 +140,8 @@ export interface ProviderQuotaReport {
   source: string;
   quota: ProviderQuota;
   updatedAt: number;
+  /** Added by the management response projection, never stored on a cached report. */
+  routingQuota?: ProviderRoutingQuota;
   reverseEngineered?: boolean;
   /**
    * The row was OBSERVED in-band on a streaming turn rather than probed.
@@ -345,14 +351,26 @@ function isCanonicalOllamaCloudBaseUrl(baseUrl?: string): boolean {
   }
 }
 
+function zaiQuotaMonitorHost(baseUrl: string): string | null {
+  // Admission and destination selection must share one mapping: admitting a new
+  // international wire must never fall through to the CN host/authentication scheme.
+  switch (normalizedBaseUrl(baseUrl)) {
+    case ZAI_BASE_URL:
+    case `${ZAI_BASE_URL}/api/coding/paas/v4`:
+    case `${ZAI_BASE_URL}/api/anthropic`:
+    case `${ZAI_BASE_URL}/api/v1`:
+      return ZAI_BASE_URL;
+    case ZAI_CN_BASE_URL:
+    case `${ZAI_CN_BASE_URL}/api/coding/paas/v4`:
+    case `${ZAI_CN_BASE_URL}/api/v1`:
+      return ZAI_CN_BASE_URL;
+    default:
+      return null;
+  }
+}
+
 function isCanonicalZaiBaseUrl(baseUrl: string): boolean {
-  const normalized = normalizedBaseUrl(baseUrl);
-  return normalized === ZAI_BASE_URL
-    || normalized === `${ZAI_BASE_URL}/api/coding/paas/v4`
-    || normalized === ZAI_CN_BASE_URL
-    || normalized === `${ZAI_CN_BASE_URL}/api/coding/paas/v4`
-    // BigModel serves the same GLM Coding Plan on the OpenAI Responses wire at /api/v1.
-    || normalized === `${ZAI_CN_BASE_URL}/api/v1`;
+  return zaiQuotaMonitorHost(baseUrl) !== null;
 }
 
 function isCanonicalMinimaxBaseUrl(baseUrl: string): boolean {
@@ -435,7 +453,9 @@ async function fetchA6apiQuota(provider: string, config: OcxProviderConfig): Pro
     ? { expiresAt: normalizedExpiry }
     : {};
   if (unlimited) {
-    return report(provider, "a6api:billing", {
+    // Every row is an API-credit constraint on inference, so the display quota is also
+    // the routing projection. Passing it explicitly is the opt-in.
+    const quota: ProviderQuota = {
       creditsUsd: {
         used: 0,
         limit: 0,
@@ -446,7 +466,8 @@ async function fetchA6apiQuota(provider: string, config: OcxProviderConfig): Pro
       },
       customWindows: [{ label: "Unlimited API credits", percent: 0 }],
       updatedAt: Date.now(),
-    });
+    };
+    return keyReport(provider, "a6api:billing", quota, config, apiKey, quota);
   }
   const limitUsd = firstFinite(subscription, ["hard_limit_usd"]);
   const grantedUnits = firstFinite(token, ["total_granted"]);
@@ -469,7 +490,7 @@ async function fetchA6apiQuota(provider: string, config: OcxProviderConfig): Pro
   const percent = normalizePercent((usedUsd / limitUsd) * 100);
   if (percent === undefined) return TERMINAL_QUOTA_FAILURE;
   const label = `API credits ($${remainingUsd.toFixed(2)} of $${limitUsd.toFixed(2)} remaining)`;
-  return report(provider, "a6api:billing", {
+  const quota: ProviderQuota = {
     creditsUsd: {
       used: usedUsd,
       limit: limitUsd,
@@ -479,7 +500,9 @@ async function fetchA6apiQuota(provider: string, config: OcxProviderConfig): Pro
     },
     customWindows: [{ label, percent }],
     updatedAt: Date.now(),
-  });
+  };
+  // The credit balance funds inference itself, so display and routing scope agree.
+  return keyReport(provider, "a6api:billing", quota, config, apiKey, quota);
 }
 
 function parseOpenCodeGoUsageWindow(value: unknown): { percent: number; resetAt?: number } | null {
@@ -527,7 +550,7 @@ async function fetchOpenCodeGoQuota(provider: string, config: OcxProviderConfig)
     } : {}),
     updatedAt: Date.now(),
   };
-  return report(provider, "opencode-go:usage", quota);
+  return keyReport(provider, "opencode-go:usage", quota, config, apiKey, quota);
 }
 
 /**
@@ -571,10 +594,13 @@ async function fetchOpenRouterQuota(provider: string, config: OcxProviderConfig)
   if (percent === undefined) return null;
   const remaining = Math.max(0, limit - used);
   const label = `API credits ($${remaining.toFixed(2)} of $${limit.toFixed(2)} remaining)`;
-  return report(provider, "openrouter:key-info", {
+  // The per-key spending cap stops every request this credential can make, so the
+  // whole report is inference-wide routing evidence.
+  const quota: ProviderQuota = {
     customWindows: [{ label, percent }],
     updatedAt: Date.now(),
-  });
+  };
+  return keyReport(provider, "openrouter:key-info", quota, config, apiKey, quota);
 }
 
 /**
@@ -673,7 +699,7 @@ async function fetchClineQuota(provider: string, config: OcxProviderConfig): Pro
       windows += 1;
     }
   }
-  return windows > 0 ? report(provider, "cline:plan-usage-limits", quota) : null;
+  return windows > 0 ? keyReport(provider, "cline:plan-usage-limits", quota, config, apiKey, quota) : null;
 }
 
 /**
@@ -745,7 +771,7 @@ async function fetchOllamaCloudQuota(provider: string, config: OcxProviderConfig
   }
   const body = asRecord(await readQuotaJson(response));
   const quota = parseOllamaCloudQuota(body);
-  return quota ? report(provider, "ollama-cloud:usage", quota) : null;
+  return quota ? keyReport(provider, "ollama-cloud:usage", quota, config, apiKey, quota) : null;
 }
 
 /**
@@ -851,13 +877,10 @@ function parseZaiQuotaLegacyFields(data: Record<string, unknown> | null): Provid
  * host or follow a redirect off-origin.
  */
 async function fetchZaiQuota(provider: string, config: OcxProviderConfig): Promise<ProviderQuotaProbeResult> {
-  if (!isCanonicalZaiBaseUrl(config.baseUrl)) return null;
+  const monitorHost = zaiQuotaMonitorHost(config.baseUrl);
+  if (!monitorHost) return null;
   const apiKey = resolveProviderApiKey(config.apiKey)?.trim();
   if (!apiKey) return null;
-  const normalized = normalizedBaseUrl(config.baseUrl);
-  const monitorHost = normalized === ZAI_BASE_URL || normalized === `${ZAI_BASE_URL}/api/coding/paas/v4`
-    ? ZAI_BASE_URL
-    : ZAI_CN_BASE_URL;
   const authorization = monitorHost === ZAI_CN_BASE_URL ? apiKey : `Bearer ${apiKey}`;
   const response = await fetch(`${monitorHost}/api/monitor/usage/quota/limit`, {
     headers: { Accept: "application/json", Authorization: authorization },
@@ -878,10 +901,18 @@ async function fetchZaiQuota(provider: string, config: OcxProviderConfig): Promi
     // model window — for example a plan reporting only the monthly MCP `TIME_LIMIT` row.
     // Returning `null` here would preserve the previous token windows for up to 30 minutes
     // and keep quota-aware routing acting on a report the provider has already superseded.
-    return quota ? report(provider, "zai:quota-limit", quota) : AUTHORITATIVE_EMPTY_QUOTA;
+    return quota
+      ? keyReport(provider, "zai:quota-limit", quota, config, apiKey, quota)
+      : AUTHORITATIVE_EMPTY_QUOTA;
   }
   const legacy = parseZaiQuotaLegacyFields(data);
-  return legacy ? report(provider, "zai:quota-limit", legacy) : null;
+  if (!legacy) return null;
+  // The legacy monthly figure also carries MCP usage; it is display evidence, not
+  // proof that model inference is unavailable. Modern TOKEN_LIMIT rows above are scoped.
+  const inferenceQuota = { ...legacy };
+  delete inferenceQuota.monthlyPercent;
+  delete inferenceQuota.monthlyResetAt;
+  return keyReport(provider, "zai:quota-limit", legacy, config, apiKey, inferenceQuota);
 }
 
 /**
@@ -1064,7 +1095,9 @@ async function fetchSyntheticQuota(provider: string, config: OcxProviderConfig):
     quota.customWindows = [...(quota.customWindows ?? []), { label: "Search hourly", percent: searchHourly }];
     windows += 1;
   }
-  return windows > 0 ? report(provider, "synthetic:quotas", quota) : null;
+  const inferenceQuota = { ...quota };
+  delete inferenceQuota.customWindows; // search.hourly does not constrain model inference.
+  return windows > 0 ? keyReport(provider, "synthetic:quotas", quota, config, apiKey, inferenceQuota) : null;
 }
 
 /**
@@ -1176,6 +1209,31 @@ function report(
   };
 }
 
+/**
+ * Publish a credential-bound report, and routing evidence only when the producer
+ * hands over its inference-only projection.
+ *
+ * The projection is deliberately not defaulted to the display quota. A producer must
+ * decide that its rows really do constrain inference on the probed credential; omitting
+ * the argument leaves the report display-only, so a new producer cannot inherit
+ * provider-veto authority merely by calling this helper. Ownership alone is not the
+ * scope decision: providerQuotaRoutingBinding resolving is necessary, never sufficient.
+ */
+function keyReport(
+  provider: string,
+  source: string,
+  quota: ProviderQuota,
+  config: OcxProviderConfig,
+  probedCredential: string,
+  inferenceQuota?: ProviderQuota,
+): ProviderQuotaReport | null {
+  const result = report(provider, source, quota);
+  if (!result || !inferenceQuota) return result;
+  const binding = providerQuotaRoutingBinding(provider, config, probedCredential);
+  if (binding) routingEvidence.set(result, { quota: inferenceQuota, binding });
+  return result;
+}
+
 function tagNativeMainReport(
   value: ProviderQuotaReport | null,
   generation: number,
@@ -1184,6 +1242,27 @@ function tagNativeMainReport(
   return value;
 }
 
+/**
+ * Test-only seam: publish exactly as a credential-bound producer does, and hand back the
+ * routing evidence the publication actually attached.
+ *
+ * Live producers all pass a projection today, so no probe fixture can prove the OTHER half
+ * of the contract: that omitting it stays display-only. Routing an omitted argument through
+ * the real helper keeps that provable, and a re-introduced `= quota` default would be
+ * observed here (a defaulted parameter also fires for an explicitly undefined argument).
+ */
+export function publishKeyReportForTests(
+  provider: string,
+  source: string,
+  quota: ProviderQuota,
+  config: OcxProviderConfig,
+  probedCredential: string,
+  inferenceQuota?: ProviderQuota,
+): { report: ProviderQuotaReport | null; routing: ProviderQuotaRoutingEvidence | undefined } {
+  const result = keyReport(provider, source, quota, config, probedCredential, inferenceQuota);
+  return { report: result, routing: result ? routingEvidence.get(result) : undefined };
+}
+
 function isProviderQuotaReportCurrent(value: ProviderQuotaReport): boolean {
   const generation = nativeMainReportGenerations.get(value);
   return (generation === undefined || isMainAccountIdentityGenerationLive(generation))
@@ -1879,7 +1958,7 @@ export function reconcileProviderAccountQuotaRows(context: GenerationContext): n
     const reports = cache.response.reports.filter(report => context.providerNames.has(report.provider));
     removed += cache.response.reports.length - reports.length;
     cache = { ...cache, response: { ...cache.response, reports } };
-    replaceCachedProviderQuotas(reports);
+    replaceCachedProviderQuotas(reports, routingEvidence);
   }
   liveAccountQuotaKeys = new Set(context.oauthAccountKeys);
   liveProviderQuotaKeys = new Set(context.providerNames);
@@ -2308,7 +2387,7 @@ async function fetchKimiQuota(provider: string, config: OcxProviderConfig, acces
   });
   if (!response.ok) return null;
   const quota = parseKimiQuotaPayload(await readQuotaJson(response));
-  return quota ? report(provider, "kimi:usages", quota) : null;
+  return quota ? keyReport(provider, "kimi:usages", quota, config, accessToken, quota) : null;
 }
 
 /**
@@ -2435,7 +2514,7 @@ async function fetchCommandCodeQuota(provider: string, config: OcxProviderConfig
   const fiveHour = parseCommandCodeWindow(limits?.fiveHour);
   const weekly = parseCommandCodeWindow(limits?.weekly);
   const creditsUsd = await fetchCommandCodeSpend(bearer, credits, orgQuery);
-  return report(provider, "command-code:credits", {
+  const quota: ProviderQuota = {
     ...(fiveHour ? {
       fiveHourPercent: fiveHour.percent,
       ...(fiveHour.resetAt !== undefined ? { fiveHourResetAt: fiveHour.resetAt } : {}),
@@ -2446,7 +2525,9 @@ async function fetchCommandCodeQuota(provider: string, config: OcxProviderConfig
     } : {}),
     ...(creditsUsd ? { creditsUsd } : {}),
     updatedAt: Date.now(),
-  });
+  };
+  // Rolling windows and the credit balance both gate inference on this bearer.
+  return keyReport(provider, "command-code:credits", quota, config, bearer, quota);
 }
 
 /** Cursor included usage via api2.cursor.sh (Bearer from OAuth) — unofficial, may change. */
@@ -2955,7 +3036,9 @@ async function maybeFetchProviderQuota(
     // probe to run — the row is the active account's last in-band observation.
     if (provider.authMode === "oauth" && hasPassiveAccountQuota(name)) return fetchPassiveProviderQuota(name);
     const reader = keyQuotaReaderForProvider(name, provider);
-    return reader ? reader(name, provider) : null;
+    // Keep destination/auth fields bound to the same request as the reader's captured
+    // bearer, even if the live provider object changes while the quota probe awaits.
+    return reader ? reader(name, { ...provider }) : null;
   } catch {
     return null;
   }
@@ -3142,7 +3225,7 @@ export async function fetchProviderQuotaReports(config: OcxConfig, forceRefresh
     ) {
       const reports = response.reports.filter(item => mayCommitProviderQuotaKey(item.provider, writerGeneration));
       cache = { key, ts: Date.now(), response: { ...response, reports } };
-      replaceCachedProviderQuotas(reports);
+      replaceCachedProviderQuotas(reports, routingEvidence);
       notifyProviderQuotaSnapshot(reports, config);
     }
     return response;
diff --git a/src/providers/registry.ts b/src/providers/registry.ts
index c4ea553d2d..e2189254fc 100644
--- a/src/providers/registry.ts
+++ b/src/providers/registry.ts
@@ -1,6 +1,7 @@
 import type { CodexAccountMode, FastWire, OcxProviderConfig } from "../types";
 import { fastWireDeclarationError } from "./fastwire";
 import { KIRO_MODELS, KIRO_MODEL_CONTEXT_WINDOWS, KIRO_MODEL_REASONING_EFFORTS } from "./kiro-models";
+import { DEVIN_MODEL_CONTEXT_WINDOWS } from "../adapters/devin/live-models";
 import { ANTIGRAVITY_MODELS, ANTIGRAVITY_MODEL_CONTEXT_WINDOWS, ANTIGRAVITY_MODEL_EFFORTS, ANTIGRAVITY_MODEL_INPUT_MODALITIES } from "./antigravity-models";
 import type { ProviderBaseUrlChoice } from "./base-url-choices";
 import {
@@ -229,6 +230,19 @@ export interface ProviderRegistryEntry {
    * per model. DeepSeek documents `POST /responses` with no `/v1` segment.
    */
   responsesPath?: string;
+  /**
+   * Relative send path for the `openai-chat` wire, seeded into saved config exactly like
+   * `responsesPath`. Needed when one upstream serves both wires under different prefixes,
+   * because a per-model wire override changes the adapter and not the base URL.
+   */
+  chatCompletionsPath?: string;
+  /**
+   * Endpoints this entry used to live at, kept so a saved custom provider that still points
+   * at one keeps receiving this row's metadata through `registryEntryForProviderDestination`.
+   * Destination matching is by adapter plus normalized base URL, so moving a row's wire or
+   * prefix would otherwise orphan every config a user wrote against the old address.
+   */
+  destinationAliases?: readonly { readonly baseUrl: string; readonly adapter: string }[];
   /**
    * Responses upstream that stores nothing server-side. Stateful request parameters
    * are dropped and `store` is pinned false, and orphaned tool results left by a
@@ -321,6 +335,12 @@ export interface ProviderRegistryEntry {
   noTemperatureModels?: string[];
   noTopPModels?: string[];
   noPenaltyModels?: string[];
+  /**
+   * Registry-only seed for `OcxProviderConfig.noJsonSchemaModels`. Merged into the
+   * resolved provider at route time rather than persisted as user config, the same way
+   * `directReasoningEffortModels` above is registry-owned.
+   */
+  noJsonSchemaModels?: string[];
   /** Opt this provider into parallel tool calls (see OcxProviderConfig.parallelToolCalls). */
   parallelToolCalls?: boolean;
   /** Opt this provider into forwarding prompt_cache_key (OpenAI-specific; strict backends reject it). */
@@ -354,7 +374,7 @@ export interface ProviderRegistryEntry {
 
 export type ProviderConfigSeed = Pick<
   OcxProviderConfig,
-  "adapter" | "baseUrl" | "apiKeyTransport" | "responsesPath" | "authMode" | "keyOptional" | "freeTier" | "modelSuffixBracketStrip" | "defaultModel" | "models"
+  "adapter" | "baseUrl" | "apiKeyTransport" | "responsesPath" | "chatCompletionsPath" | "authMode" | "keyOptional" | "freeTier" | "modelSuffixBracketStrip" | "defaultModel" | "models"
   | "liveModels" | "contextWindow" | "modelContextWindows" | "modelInputModalities"
   | "modelDisplayNames"
   | "modelMaxInputTokens" | "defaultMaxOutputTokens" | "modelMaxOutputTokens"
@@ -437,6 +457,30 @@ const ZAI_GLM_5X_MODELS = [...ZAI_GLM_53_MODELS, ...ZAI_GLM_52_MODELS];
  * `preserveReasoningContentModels`, where flash DOES belong.
  */
 const ZAI_GLM_5X_SIDECAR_VISION_MODELS = ZAI_GLM_5X_MODELS.filter(id => id !== "glm-5.3-flash");
+/**
+ * Positive input-modality declaration for the Chat-path GLM rows.
+ *
+ * `noVisionModels` already keeps Flash out of the vision sidecar, but that is a NEGATIVE
+ * statement: it stops a detour without telling the catalog what the model can read. With
+ * no `modelInputModalities` entry, `configuredInputModalities` returns undefined and the
+ * catalog falls through to the `["text"]` floor, so every client export (ZCode, Pi, OMP)
+ * listed a native VLM as text-only and its picker refused to attach an image.
+ *
+ * The Responses sibling row below already declares this positively, so the same model was
+ * described two different ways in one registry.
+ *
+ * Authoritative source: `GET https://api.z.ai/api/v1/models` returns `input_modalities:
+ * ["text"]` for glm-5.3 and `["text", "image"]` for glm-5.3-flash (captured in
+ * devlog/_plan/260912_zcode_protocol_and_catalog/evidence/zai-responses-models.json).
+ * docs.z.ai/devpack/latest-model says the same in prose: "GLM-5.3 is a text-only model...
+ * GLM-5.3-FLASH is a multimodal model". Upstream also lists video and file for Flash;
+ * neither the internal vocabulary nor the export vocabulary can express them, so `image`
+ * is where this stops.
+ */
+const ZAI_GLM_5X_INPUT_MODALITIES: Record<string, string[]> = {
+  ...Object.fromEntries(ZAI_GLM_5X_SIDECAR_VISION_MODELS.map(id => [id, ["text"]])),
+  "glm-5.3-flash": ["text", "image"],
+};
 const ZAI_GLM_52_REASONING_EFFORTS = ["low", "medium", "high", "xhigh", "max"];
 /**
  * GLM-5.3 does NOT share 5.2's five-tier ladder. docs.z.ai/devpack/latest-model folds every
@@ -610,7 +654,30 @@ const THINKING_BUDGET_MODELS = [
   "qwen3.5-plus", "qwen3.6-plus", "qwen3.7-max", "qwen3.7-plus",
 ];
 const OPENCODE_GO_THINKING_BUDGET_MODELS = ["qwen3.5-plus", "qwen3.6-plus", "qwen3.7-max", "qwen3.7-plus"];
-const DEEPSEEK_THINKING_MODELS = ["deepseek-v4-pro", "deepseek-v4-flash"];
+/*
+ * DeepSeek moved the whole V4 name set on 2026-09-10. V4.1-Flash ships as deepseek-flash
+ * on the first-party API; deepseek-v4-flash and the vision preview retire as models but
+ * keep routing there as compatibility aliases, and deepseek-v4-pro follows from
+ * 2026-09-14 04:00 UTC. Evidence: https://api-docs.deepseek.com/news/news260910/.
+ *
+ * The spelling differs by who serves it, so one shared list cannot express it: the
+ * first-party API answers to deepseek-flash, while the Zen gateway exposes the route as
+ * deepseek-v4.1-flash (issue #4253, PR #4258). Vendor-hosted rosters (Volcengine plan
+ * snapshots, Alibaba) publish on their own schedule and keep the legacy set until they say
+ * otherwise - a first-party retirement notice does not end their deployment.
+ */
+const DEEPSEEK_V4_LEGACY_MODELS = ["deepseek-v4-flash"];
+/*
+ * `deepseek-v4-pro` is deliberately absent from both live sets. DeepSeek retires it from
+ * 2026-09-14 04:00 UTC and routes its requests to V4.1-Flash until a V4.1 Pro exists, so a
+ * row here would advertise a Pro context window and Pro pricing for a route that serves
+ * Flash. The retirement is followed through every roster in this file, including the
+ * vendor-hosted ones; providers that discover their models live are handled by
+ * `ROUTED_MODEL_COMPATIBILITY_EXCLUSIONS` because deleting a row there removes the
+ * model's capabilities rather than the model.
+ */
+const DEEPSEEK_NATIVE_THINKING_MODELS = ["deepseek-flash", "deepseek-v4-flash"];
+const DEEPSEEK_GATEWAY_THINKING_MODELS = ["deepseek-v4.1-flash", "deepseek-v4-flash"];
 /*
  * DeepSeek's experimental vision preview (released 2026-08-21, api-docs.deepseek.com):
  * text+image input on the V4 Flash base. DeepSeek positions it as a preview id;
@@ -622,7 +689,7 @@ const DEEPSEEK_VISION_PREVIEW_MODEL = "deepseek-v4-flash-vision-exp";
  * CommandCode routes verified to accept image input end-to-end (#2406).
  *
  * Verified-negative and therefore deliberately ABSENT: deepseek/deepseek-v4-flash,
- * deepseek/deepseek-v4-pro, zai-org/GLM-5.2, zai-org/GLM-5.3, xai/grok-4.6. Those
+ * zai-org/GLM-5.2, zai-org/GLM-5.3, xai/grok-4.6. Those
  * routes accept the request and drop the image, which is worse than declining it — the
  * model answers about an image it never saw. Do not add an id here on family resemblance;
  * capability intersection trusts this map.
@@ -710,7 +777,7 @@ const DEEPSEEK_FLASH_REASONING_MAP: Record<string, string> = {
 };
 /**
  * Flash-versus-Pro classification for DeepSeek V4 model ids, including prefixed
- * (`deepseek/deepseek-v4-pro`) and suffixed (`deepseek-v4-flash-free`) forms.
+ * (`deepseek/deepseek-v4.1-flash`) and suffixed (`deepseek-v4-flash-free`) forms.
  * `tests/providers/provider-registry-parity.test.ts` enumerates every id the registry
  * actually passes here, so a future id this substring test would misread cannot
  * land silently.
@@ -727,7 +794,7 @@ const deepseekReasoningMapFor = (modelId: string): Record<string, string> =>
 //           https://help.aliyun.com/en/model-studio/token-plan-quickstart
 const ALIBABA_TOKEN_PLAN_MODELS = [
   "qwen3.8-max", "qwen3.7-max", "qwen3.7-plus", "qwen3.6-flash",
-  "glm-5.3", "glm-5.3-flash", "glm-5.2", "deepseek-v4-pro",
+  "glm-5.3", "glm-5.3-flash", "glm-5.2", 
 ];
 const ALIBABA_TOKEN_PLAN_QWEN_MODELS = [
   "qwen3.8-max", "qwen3.7-max", "qwen3.7-plus", "qwen3.6-flash",
@@ -740,7 +807,6 @@ const ALIBABA_TOKEN_PLAN_INPUT_MODALITIES: Record<string, string[]> = {
   "glm-5.3": ["text"],
   "glm-5.3-flash": ["text", "image"],
   "glm-5.2": ["text"],
-  "deepseek-v4-pro": ["text"],
 };
 
 // 260721 Alibaba Token Plan International (ap-southeast-1 / Singapore, hardened 260721).
@@ -749,7 +815,7 @@ const ALIBABA_TOKEN_PLAN_INPUT_MODALITIES: Record<string, string[]> = {
 //           https://qwencloud.com/pricing/token-plan (qwen3.8 metadata)
 const ALIBABA_INTL_TOKEN_PLAN_MODELS = [
   "qwen3.8-max", "qwen3.7-max", "qwen3.7-plus", "qwen3.6-plus", "qwen3.6-flash",
-  "deepseek-v4-pro", "deepseek-v4-flash", "deepseek-v3.2",
+  "deepseek-v4-flash", "deepseek-v3.2",
   "kimi-k2.7-code", "kimi-k2.6", "kimi-k2.5",
   "glm-5.3", "glm-5.3-flash", "glm-5.2", "glm-5.1", "glm-5",
   "MiniMax-M2.5",
@@ -782,7 +848,6 @@ const VOLCENGINE_ARK_MODELS = [
   "doubao-seed-2-1-pro-260628",
   "doubao-seed-2-1-turbo-260628",
   "doubao-seed-evolving",
-  "deepseek-v4-pro-260425",
   "deepseek-v4-flash-260425",
   "deepseek-v3-2-251201",
   // No glm-5-3 row: Ark pins date-stamped snapshot ids (glm-5-2-260617) that cannot be
@@ -798,7 +863,6 @@ const VOLCENGINE_DOUBAO_THINKING_MODELS = [
 const VOLCENGINE_CODING_PLAN_MODELS = [
   "ark-code-latest",
   "doubao-seed-2.0-code",
-  "deepseek-v4-pro",
   "deepseek-v4-flash",
   "glm-5.3",
   "glm-5.3-flash",
@@ -807,7 +871,6 @@ const VOLCENGINE_CODING_PLAN_MODELS = [
   "minimax-m3",
 ];
 const VOLCENGINE_AGENT_PLAN_MODELS = [
-  "deepseek-v4-pro",
   "deepseek-v4-flash",
   "glm-5.3",
   "glm-5.3-flash",
@@ -829,7 +892,6 @@ const VOLCENGINE_PLAN_INPUT_MODALITIES: Record<string, string[]> = {
 const VOLCENGINE_PLAN_TEXT_ONLY_MODELS = [
   "ark-code-latest",
   "doubao-seed-2.0-code",
-  "deepseek-v4-pro",
   "deepseek-v4-flash",
   "glm-5.3",
   "glm-5.2",
@@ -841,7 +903,6 @@ const ALIBABA_INTL_TOKEN_PLAN_INPUT_MODALITIES: Record<string, string[]> = {
   "qwen3.7-plus": ["text", "image"],
   "qwen3.6-plus": ["text", "image"],
   "qwen3.6-flash": ["text", "image"],
-  "deepseek-v4-pro": ["text"],
   "deepseek-v4-flash": ["text"],
   "deepseek-v3.2": ["text"],
   "kimi-k2.7-code": ["text", "image"],
@@ -960,7 +1021,7 @@ const NVIDIA_NIM_VISION_INPUT_MODALITIES: Record<string, string[]> = Object.from
  * reasoning suppression regardless of which list they appear in here.
  */
 const NVIDIA_NIM_NO_VISION_MODELS = [
-  "deepseek-ai/deepseek-v4-flash", "deepseek-ai/deepseek-v4-pro",
+  "deepseek-ai/deepseek-v4-flash",
   "google/codegemma-7b",
   "meta/llama-3.1-70b-instruct", "meta/llama-3.1-8b-instruct",
   "meta/llama-3.2-1b-instruct", "meta/llama-3.2-3b-instruct",
@@ -1001,7 +1062,6 @@ const NEURALWATT_REASONING_HISTORY_MODELS = [
 //           https://docs.baseten.co/inference/model-apis/vision
 const BASETEN_FULL_REASONING_EFFORTS = ["low", "medium", "high", "xhigh", "max"];
 const BASETEN_MODEL_REASONING_EFFORTS: Record<string, string[]> = {
-  "deepseek-ai/DeepSeek-V4-Pro": BASETEN_FULL_REASONING_EFFORTS,
   "thinkingmachines/inkling": BASETEN_FULL_REASONING_EFFORTS,
   "openai/gpt-oss-120b": BASETEN_FULL_REASONING_EFFORTS,
   "moonshotai/Kimi-K3": ["low", "high", "max"],
@@ -1012,7 +1072,6 @@ const BASETEN_MODEL_REASONING_EFFORTS: Record<string, string[]> = {
   "zai-org/GLM-5.2-Fast": ["high", "max"],
 };
 const BASETEN_MODEL_REASONING_EFFORT_MAP: Record<string, Record<string, string>> = {
-  "deepseek-ai/DeepSeek-V4-Pro": { none: "none", minimal: "minimal" },
   "thinkingmachines/inkling": { none: "none", minimal: "minimal" },
   "openai/gpt-oss-120b": { none: "none", minimal: "minimal" },
   "moonshotai/Kimi-K3": { none: "none" },
@@ -1022,7 +1081,6 @@ const BASETEN_MODEL_REASONING_EFFORT_MAP: Record<string, Record<string, string>>
   "zai-org/GLM-5.2-Fast": { none: "none" },
 };
 const BASETEN_MODEL_DEFAULT_REASONING_EFFORTS: Record<string, string> = {
-  "deepseek-ai/DeepSeek-V4-Pro": "medium",
   "thinkingmachines/inkling": "high",
   "openai/gpt-oss-120b": "medium",
   "moonshotai/Kimi-K3": "max",
@@ -1050,7 +1108,6 @@ const DIGITALOCEAN_CHAT_COMPLETION_MODELS = [
   "openai-gpt-5.6-luna",
   "qwen3-coder-flash",
   "qwen3.5-397b-a17b",
-  "deepseek-v4-pro",
   "deepseek-4-flash",
   "deepseek-3.2",
   "gemma-4-31B-it",
@@ -1135,7 +1192,6 @@ const CLINE_PASS_MODELS = [
   "cline-pass/kimi-k3",
   "cline-pass/kimi-k2.7-code",
   "cline-pass/kimi-k2.6",
-  "cline-pass/deepseek-v4-pro",
   "cline-pass/deepseek-v4-flash",
   "cline-pass/mimo-v2.5",
   "cline-pass/mimo-v2.5-pro",
@@ -1171,17 +1227,11 @@ const ORCAROUTER_MODELS = [
   "openai/gpt-5.5",
   "anthropic/claude-opus-4.8",
   "google/gemini-3.5-flash",
-  "deepseek/deepseek-v4-pro",
   "orcarouter/auto",
 ];
-const ORCAROUTER_TEXT_ONLY_MODELS = ["deepseek/deepseek-v4-pro"];
 const ORCAROUTER_MODEL_REASONING_EFFORTS = {
   // Live /models currently exposes ids and modalities, not the accepted reasoning ladder.
   "openai/gpt-5.5": ["low", "medium", "high", "xhigh"],
-  "deepseek/deepseek-v4-pro": deepseekThinkingEffortsFor("deepseek/deepseek-v4-pro"),
-};
-const ORCAROUTER_MODEL_REASONING_EFFORT_MAP = {
-  "deepseek/deepseek-v4-pro": deepseekReasoningMapFor("deepseek/deepseek-v4-pro"),
 };
 const CLINE_PASS_MODEL_CONTEXT_WINDOWS: Record<string, number> = {
   "cline-pass/glm-5.3": 1_048_576,
@@ -1190,7 +1240,6 @@ const CLINE_PASS_MODEL_CONTEXT_WINDOWS: Record<string, number> = {
   "cline-pass/kimi-k3": 1_048_576,
   "cline-pass/kimi-k2.7-code": 262_144,
   "cline-pass/kimi-k2.6": 262_144,
-  "cline-pass/deepseek-v4-pro": 1_048_576,
   "cline-pass/deepseek-v4-flash": 1_048_576,
   "cline-pass/mimo-v2.5": 1_050_000,
   "cline-pass/mimo-v2.5-pro": 1_050_000,
@@ -1265,6 +1314,57 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     // still advertises image for noVision members so Codex can attach (sidecar option B).
     noVisionModels: [...CURSOR_NO_VISION_MODELS],
   },
+  {
+    // The signed-in Devin CLI as an account source.
+    //
+    // The CLI writes a `devin-session-token$<JWT>` to its own credentials.toml,
+    // which is the same credential RegisterUser hands `ocx login devin` and which
+    // the cloud-direct client already speaks. So this provider imports that token
+    // and streams over Connect-RPC like its browser-login sibling, rather than
+    // spawning `devin acp`.
+    //
+    // `oauth` classifies the ACCOUNT, not the transport. This is not a local
+    // runtime: unlike Ollama or LM Studio it cannot answer at all until a vendor
+    // account is signed in, and `local` grouped it with things that have no
+    // account. It is also the only classification that reaches the dashboard
+    // Accounts tab, which is built from OAUTH_PROVIDERS.
+    //
+    // The ACP adapter stays registered and tested. It is no longer reachable
+    // under THIS id — `routedProviderConfig` pins the adapter from the registry
+    // for any row whose name is a registry id — but a custom-named row such as
+    // `{"devin-acp": {"adapter": "devin-cli", ...}}` is not pinned and still gets it.
+    id: "devin-cli",
+    label: "Devin CLI",
+    adapter: "devin",
+    baseUrl: "https://server.codeium.com",
+    authKind: "oauth",
+    featured: false,
+    // Off, like `devin`. `deriveProviderPresets` keys the preset catalog off this
+    // flag, so leaving it true would draw the row twice: an Accounts login row and
+    // a preset tile.
+    dashboardPreset: false,
+    note: "Imports the credential your installed Devin CLI already holds (`devin auth login`), then streams over Cognition's Connect-RPC api-server like the `devin` provider. No browser sign-in and no key to paste. For the CLI's own local agent loop over ACP stdio instead, configure a custom-named provider row with \"adapter\": \"devin-cli\".",
+    // Degraded-mode seed only; `liveModels` discovers the account's real roster,
+    // which is where `swe-2` and the rest of the current catalog come from.
+    models: ["swe-2", "swe-1-7", "gpt-5-6-sol", "gpt-6-astra", "claude-opus-5", "claude-fable-5-1", "claude-sonnet-5", "glm-5-3", "kimi-k3", "gemini-3-8-flash", "grok-4-6"],
+    liveModels: true,
+    defaultModel: "swe-2",
+    modelContextWindows: DEVIN_MODEL_CONTEXT_WINDOWS,
+  },
+  {
+    id: "devin",
+    label: "Cognition (Devin/Windsurf)",
+    adapter: "devin",
+    baseUrl: "https://server.codeium.com",
+    authKind: "oauth",
+    featured: false,
+    dashboardPreset: false,
+    note: "Experimental unofficial Cognition/Devin bridge. ocx login devin opens Auth0 browser sign-in, then exchanges the token via Cognition's RegisterUser for a long-lived API key.",
+    models: ["swe-1-7", "swe-1-7-lightning", "gpt-5-6-sol", "gpt-5-6-luna", "gpt-5-6-terra", "claude-opus-4-8", "claude-fable-5-1", "claude-sonnet-5", "glm-5-2", "kimi-k2-7", "grok-4-5"],
+    liveModels: true,
+    defaultModel: "swe-1-7",
+    modelContextWindows: DEVIN_MODEL_CONTEXT_WINDOWS,
+  },
   {
     id: "xai",
     label: "xAI Grok",
@@ -1434,10 +1534,7 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     models: ORCAROUTER_MODELS,
     liveModels: true,
     modelDiscovery: ORCAROUTER_MODEL_DISCOVERY,
-    noVisionModels: ORCAROUTER_TEXT_ONLY_MODELS,
     modelReasoningEfforts: ORCAROUTER_MODEL_REASONING_EFFORTS,
-    modelReasoningEffortMap: ORCAROUTER_MODEL_REASONING_EFFORT_MAP,
-    preserveReasoningContentModels: ORCAROUTER_TEXT_ONLY_MODELS,
     note: "Connect your OrcaRouter account with OAuth 2.0 + PKCE; the issued API key is stored in OpenCodex's existing credential store.",
   },
   {
@@ -1751,7 +1848,7 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
       "kimi-k2.7-code-highspeed": [],
       ...Object.fromEntries(OPENCODE_GO_THINKING_TOGGLE_MODELS.map(id => [id, THINKING_TOGGLE_EFFORTS])),
       ...Object.fromEntries(OPENCODE_GO_THINKING_BUDGET_MODELS.map(id => [id, THINKING_BUDGET_EFFORTS])),
-      ...Object.fromEntries(DEEPSEEK_THINKING_MODELS.map(id => [id, deepseekThinkingEffortsFor(id)])),
+      ...Object.fromEntries(DEEPSEEK_GATEWAY_THINKING_MODELS.map(id => [id, deepseekThinkingEffortsFor(id)])),
     },
     modelDefaultReasoningEfforts: { "grok-4.6": "high", "kimi-k3": "max" },
     // glm-5.2 uses identity labels now that `max` is a native Codex level (no alias map);
@@ -1759,7 +1856,7 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     modelReasoningEffortMap: {
       "kimi-k3": KIMI_CODING_K3_REASONING_EFFORT_MAP,
       ...Object.fromEntries(OPENCODE_GO_THINKING_TOGGLE_MODELS.map(id => [id, THINKING_TOGGLE_MAP])),
-      ...Object.fromEntries(DEEPSEEK_THINKING_MODELS.map(id => [id, deepseekReasoningMapFor(id)])),
+      ...Object.fromEntries(DEEPSEEK_GATEWAY_THINKING_MODELS.map(id => [id, deepseekReasoningMapFor(id)])),
     },
     modelSupportsReasoningSummaries: {
       "glm-5.3": true,
@@ -1767,17 +1864,24 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
       "glm-5.2": true,
       "glm-5.1": true,
       "glm-5": true,
-      ...Object.fromEntries(DEEPSEEK_THINKING_MODELS.map(id => [id, true])),
+      ...Object.fromEntries(DEEPSEEK_GATEWAY_THINKING_MODELS.map(id => [id, true])),
     },
     thinkingToggleModels: OPENCODE_GO_THINKING_TOGGLE_MODELS,
-    thinkingBudgetModels: THINKING_BUDGET_MODELS,
+    /*
+     * The Go-specific list, not the shared one. The shared `THINKING_BUDGET_MODELS` also
+     * carries Neuralwatt-only ids (`qwen3.5-397b`, `qwen3.6-35b`) that this preset never
+     * gives a ladder to, so a live roster serving one of them armed the thinking-budget
+     * wire path with nothing to advertise: the catalog showed no effort control while the
+     * adapter still translated effort into `thinking_budget`.
+     */
+    thinkingBudgetModels: OPENCODE_GO_THINKING_BUDGET_MODELS,
     noReasoningModels: ["kimi-k2.7-code", "kimi-k2.7-code-highspeed"],
     // Text-only Zen Go models (jawcode metadata) — the vision sidecar describes images for
     // every model listed here (and the catalog advertises image input on their behalf).
     // Kimi K2.7 Code accepts text+image+video: do NOT list it here.
     noVisionModels: [
       "glm-5.3", "glm-5.2", "glm-5", "glm-5.1",
-      "deepseek-v4-flash", "deepseek-v4-pro",
+      "deepseek-v4.1-flash", "deepseek-v4-flash",
       "mimo-v2-pro", "mimo-v2.5-pro",
       "minimax-m2.5", "minimax-m2.7",
       "qwen3.7-max",
@@ -1787,7 +1891,17 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     noPenaltyModels: ["kimi-k3", "kimi-k2.7-code", "kimi-k2.7-code-highspeed"],
     autoToolChoiceOnlyModels: ["kimi-k2.7-code", "kimi-k2.7-code-highspeed"],
     // Issue #78: DeepSeek V4 thinking mode requires reasoning_content replay on tool-call turns.
-    preserveReasoningContentModels: ["glm-5.3", "glm-5.3-flash", "glm-5.2", "kimi-k3", "kimi-k2.7-code", "kimi-k2.7-code-highspeed", ...DEEPSEEK_THINKING_MODELS],
+    preserveReasoningContentModels: ["glm-5.3", "glm-5.3-flash", "glm-5.2", "kimi-k3", "kimi-k2.7-code", "kimi-k2.7-code-highspeed", ...DEEPSEEK_GATEWAY_THINKING_MODELS],
+    /*
+     * Issues #1338 / #1415: this gateway answers a `response_format` of type
+     * `json_schema` with HTTP 400 `This response_format type is unavailable now`
+     * (quoted from the upstream body as `Error from provider (Console Go)`), which
+     * breaks every Codex auto-review turn on a DeepSeek route. #1424 shipped the
+     * operator-side opt-out; operators have been applying it by hand ever since.
+     * The reported rejection is type-specific, so this narrower list downgrades the
+     * request to `json_object` instead of claiming the whole field is unavailable.
+     */
+    noJsonSchemaModels: [...DEEPSEEK_GATEWAY_THINKING_MODELS],
   },
   {
     id: "neuralwatt",
@@ -1934,10 +2048,7 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     modelDiscovery: ORCAROUTER_MODEL_DISCOVERY,
     // Catalog discovery owns WHICH models exist. These entries only retain verified
     // request-shaping facts that the upstream catalog does not currently publish.
-    noVisionModels: ORCAROUTER_TEXT_ONLY_MODELS,
     modelReasoningEfforts: ORCAROUTER_MODEL_REASONING_EFFORTS,
-    modelReasoningEffortMap: ORCAROUTER_MODEL_REASONING_EFFORT_MAP,
-    preserveReasoningContentModels: ORCAROUTER_TEXT_ONLY_MODELS,
     note: "OpenAI-compatible adaptive router. Models and multimodal capabilities are discovered live from the public chat catalog. Use the OrcaRouter account entry for PKCE login.",
   },
   {
@@ -1994,7 +2105,14 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
   // 2026-07-10: defaultModel is frozen pending Vertex-specific Tier-2 evidence; Gemini API
   // evidence from ai.google.dev does not establish Vertex publisher availability.
   { id: "google-vertex", label: "Google Vertex AI", adapter: "google", baseUrl: "https://aiplatform.googleapis.com", authKind: "key", dashboardUrl: "https://console.cloud.google.com/vertex-ai", defaultModel: "gemini-3-pro", googleMode: "vertex", jawcodeBundle: "google", extraMetadataAliases: ["gemini-vertex"] },
-  { id: "google-antigravity", alias: "agy", label: "Google Antigravity", adapter: "google", baseUrl: "https://daily-cloudcode-pa.googleapis.com", authKind: "oauth", allowBaseUrlOverride: true, dashboardUrl: "https://antigravity.google", models: ANTIGRAVITY_MODELS, liveModels: true, defaultModel: "gemini-3.8-flash", modelContextWindows: ANTIGRAVITY_MODEL_CONTEXT_WINDOWS, modelInputModalities: ANTIGRAVITY_MODEL_INPUT_MODALITIES, modelReasoningEfforts: ANTIGRAVITY_MODEL_EFFORTS, googleMode: "cloud-code-assist", jawcodeBundle: "google", extraMetadataAliases: ["antigravity", "gemini-antigravity"] },
+  // Antigravity discovers models with a POST to the CCA `:fetchAvailableModels` RPC, which
+  // `buildModelsRequest` already built by hand. Declaring it here changes no request URL — the
+  // relative path resolves to the same destination — but it lets `isRegistryModelDiscoveryUrl`
+  // prove that URL, which is what admits a Clash/Surge/Mihomo TUN fake-IP answer (#4261). The
+  // path must stay RELATIVE: this row sets `allowBaseUrlOverride`, and an absolute `url` would
+  // retarget a user's custom base back to Google. A leading `./` is required because a bare
+  // `v1internal:` reads as a URL scheme and `providerModelDiscoverySpecError` rejects it.
+  { id: "google-antigravity", alias: "agy", label: "Google Antigravity", adapter: "google", baseUrl: "https://daily-cloudcode-pa.googleapis.com", authKind: "oauth", allowBaseUrlOverride: true, dashboardUrl: "https://antigravity.google", models: ANTIGRAVITY_MODELS, liveModels: true, defaultModel: "gemini-3.8-flash", modelContextWindows: ANTIGRAVITY_MODEL_CONTEXT_WINDOWS, modelInputModalities: ANTIGRAVITY_MODEL_INPUT_MODALITIES, modelReasoningEfforts: ANTIGRAVITY_MODEL_EFFORTS, googleMode: "cloud-code-assist", jawcodeBundle: "google", extraMetadataAliases: ["antigravity", "gemini-antigravity"], modelDiscovery: { path: "./v1internal:fetchAvailableModels" } },
   { id: "azure-openai", label: "Azure OpenAI", adapter: "azure-openai", baseUrl: "https://{resource}.openai.azure.com/openai", authKind: "key", featured: true, dashboardUrl: "https://portal.azure.com" },
   { id: "ollama", label: "Ollama (local)", adapter: "openai-chat", baseUrl: "http://localhost:11434/v1", authKind: "local", allowPrivateNetworkByDefault: true, allowBaseUrlOverride: true, featured: true, note: "Local — key usually blank" },
   { id: "vllm", label: "vLLM (local)", adapter: "openai-chat", baseUrl: "http://localhost:8000/v1", authKind: "local", allowPrivateNetworkByDefault: true, allowBaseUrlOverride: true, featured: true, note: "Local — key usually blank" },
@@ -2012,18 +2130,20 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     // verified 2026-08-08).
     jawcodeBundle: "deepseek",
     // deepseek-chat/deepseek-reasoner were deprecated upstream on 2026-07-24 15:59 UTC;
-    // official identifiers are now deepseek-v4-flash / deepseek-v4-pro. They stay in
+    // the current official identifier is deepseek-flash. They stay in
     // the list only as compatibility aliases so existing saved configs and requests
     // keep validating and routing (they previously mapped to v4-flash; devlog
     // _fin/260710_provider_hardening/002_research_cn.md). The current offerings are
     // the V4 ids — defaultModel and the model-specific wiring above use them.
     // deepseek-v4-flash-vision-exp: experimental vision preview (2026-08-21) —
     // expected to merge into deepseek-v4-flash later; see DEEPSEEK_VISION_PREVIEW_MODEL.
-    models: ["deepseek-chat", "deepseek-reasoner", ...DEEPSEEK_THINKING_MODELS, DEEPSEEK_VISION_PREVIEW_MODEL],
-    defaultModel: "deepseek-v4-flash",
+    models: ["deepseek-chat", "deepseek-reasoner", ...DEEPSEEK_NATIVE_THINKING_MODELS, DEEPSEEK_VISION_PREVIEW_MODEL],
+    // V4.1-Flash is the current first-party offering; `deepseek-v4-flash` now routes there
+    // as a compatibility alias, so a new install should ask for the live id by name.
+    defaultModel: "deepseek-flash",
     // Official DeepSeek Codex setup (codex-deepseek-setup.sh) advertises 1,048,576
     // for both V4 models; the older 1,000,000 figure was a rounded approximation.
-    modelContextWindows: { "deepseek-v4-flash": 1_048_576, "deepseek-v4-pro": 1_048_576, [DEEPSEEK_VISION_PREVIEW_MODEL]: 1_048_576 },
+    modelContextWindows: { "deepseek-flash": 1_048_576, "deepseek-v4-flash": 1_048_576, [DEEPSEEK_VISION_PREVIEW_MODEL]: 1_048_576 },
     modelInputModalities: { [DEEPSEEK_VISION_PREVIEW_MODEL]: ["text", "image"] },
     // DeepSeek documents both V4 models as native Responses API models adapted for Codex
     // (model table marks Responses API ✓ for flash and pro; the /responses reference lists
@@ -2037,7 +2157,9 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
       // translating them into Responses would add a hop onto our newest upstream path
       // for no gain.
       "deepseek-v4-flash": { wire: "openai-responses", inbound: ["responses"] },
-      "deepseek-v4-pro": { wire: "openai-responses", inbound: ["responses"] },
+      // Same Responses contract as the V4 ids it succeeds; without this row the new
+      // default would fall back to the provider-wide Chat wire.
+      "deepseek-flash": { wire: "openai-responses", inbound: ["responses"] },
     },
     // The #875-era bounded-JSON force (`modelResponsesUpstreamStreaming`) is retired
     // for this entry: the official guide documents a `response.completed` /
@@ -2052,7 +2174,7 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     // devlog/_fin/260807_deepseek_responses_streaming/000_plan.md.
     // Current official streams normally carry a real terminal; retain a narrow grace
     // repair for the historical shape that closes after a complete graph without one.
-    modelResponsesTerminalRepair: { "deepseek-v4-flash": { graceMs: 5_000 }, "deepseek-v4-pro": { graceMs: 5_000 } },
+    modelResponsesTerminalRepair: { "deepseek-flash": { graceMs: 5_000 }, "deepseek-v4-flash": { graceMs: 5_000 } },
     // DeepSeek's Responses route emits bare UUID item ids, which leave Codex
     // clients stuck on an uncommitted turn (#938). Client-facing only — raw
     // continuation snapshots keep the upstream ids.
@@ -2088,14 +2210,14 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     - 대안 분석: Globally preserve reasoning_content for all OpenAI-compatible models; preserve it for legacy deepseek-reasoner too; mark only V4 thinking models in registry metadata.
     - 선택 근거: DeepSeek V4 thinking mode requires history replay, while older DeepSeek reasoner has different compatibility rules. A model-scoped registry flag fixes built-in and stale saved configs without broad provider regressions.
     */
-    modelReasoningEfforts: Object.fromEntries(DEEPSEEK_THINKING_MODELS.map(id => [id, deepseekThinkingEffortsFor(id)])),
-    modelReasoningEffortMap: Object.fromEntries(DEEPSEEK_THINKING_MODELS.map(id => [id, deepseekReasoningMapFor(id)])),
-    modelSupportsReasoningSummaries: Object.fromEntries(DEEPSEEK_THINKING_MODELS.map(id => [id, true])),
-    preserveReasoningContentModels: DEEPSEEK_THINKING_MODELS,
+    modelReasoningEfforts: Object.fromEntries(DEEPSEEK_NATIVE_THINKING_MODELS.map(id => [id, deepseekThinkingEffortsFor(id)])),
+    modelReasoningEffortMap: Object.fromEntries(DEEPSEEK_NATIVE_THINKING_MODELS.map(id => [id, deepseekReasoningMapFor(id)])),
+    modelSupportsReasoningSummaries: Object.fromEntries(DEEPSEEK_NATIVE_THINKING_MODELS.map(id => [id, true])),
+    preserveReasoningContentModels: DEEPSEEK_NATIVE_THINKING_MODELS,
     // Issue #88: every DeepSeek API model is text-only input (no image support upstream) — the
     // vision sidecar describes attached images for them, and the catalog advertises image input
     // on their behalf (same treatment as opencode-go's DeepSeek V4 entries above).
-    noVisionModels: ["deepseek-chat", "deepseek-reasoner", ...DEEPSEEK_THINKING_MODELS],
+    noVisionModels: ["deepseek-chat", "deepseek-reasoner", ...DEEPSEEK_NATIVE_THINKING_MODELS],
   },
   // llama-3.3-70b was deprecated by Cerebras on 2026-02-16. Evidence: devlog/_plan/260710_provider_hardening/003_research_aggregators.md.
   { id: "cerebras", label: "Cerebras", baseUrl: "https://api.cerebras.ai/v1", adapter: "openai-chat", authKind: "key", dashboardUrl: "https://cloud.cerebras.ai/platform/apikeys", defaultModel: "gpt-oss-120b" },
@@ -2279,7 +2401,7 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     // Official Command Code model-profile reasoning facts (shared with the OAuth
     // `command-code` entry). Without them the API-key preset never advertises a
     // reasoning picker, and the router's known-ids decode source misses the native
-    // slash ids — so a Codex-facing slug like `commandcode/deepseek-deepseek-v4-pro`
+    // slash ids — so a Codex-facing slug like `commandcode/deepseek-deepseek-v4-flash`
     // is sent upstream verbatim and rejected with `unsupported_model`.
     modelReasoningEfforts: COMMAND_CODE_MODEL_REASONING_EFFORTS,
     // The DeepSeek vision preview id is preemptive for when the catalog serves it
@@ -2541,19 +2663,43 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
   // exact 131_072 every other source in this repo uses for that model. Coding Plan pricing stays
   // unpublished, so no cost entry is asserted.
   {
-    id: "zai", label: "Z.AI — GLM Coding Plan", baseUrl: "https://api.z.ai/api/coding/paas/v4", adapter: "openai-chat", authKind: "key",
+    id: "zai", label: "Z.AI — GLM Coding Plan", baseUrl: "https://api.z.ai", adapter: "openai-responses", authKind: "key",
+    // One subscription and one key, three protocols. docs.z.ai/guides/llm/glm-5.3 lists them:
+    // Chat Completions at /api/coding/paas/v4, Responses at /api/v1, Anthropic Messages at
+    // /api/anthropic. docs.z.ai/devpack/latest-model points Codex-family clients at /api/v1,
+    // and the Chat path is the one that misbehaves in practice.
+    //
+    // Responses is the default and Chat stays reachable per model through `modelAdapters`.
+    // The two wires sit under different prefixes, and a wire override swaps the adapter
+    // without touching baseUrl, so each wire carries its own relative send path.
+    //
+    // Measured 2026-09-12 against a live key: every roster id answers 200 on
+    // /api/v1/responses, and every one also answers 200 on the Chat prefix, so no model
+    // needs a `modelWireDefaults` pin. /api/v1/chat/completions returns 403
+    // model_access_denied, which is why the Chat path cannot simply hang off the new base.
+    responsesPath: "/api/v1/responses",
+    chatCompletionsPath: "/api/coding/paas/v4/chat/completions",
+    // The address this row occupied before the move. A saved custom provider still pointing
+    // at the Chat endpoint keeps receiving this row's metadata (#1100).
+    destinationAliases: [{ baseUrl: "https://api.z.ai/api/coding/paas/v4", adapter: "openai-chat" }],
     dashboardUrl: "https://z.ai/manage-apikey/apikey-list", defaultModel: "glm-5.3",
     note: "GLM-5.3 coding subscription",
     models: ["glm-5.3", "glm-5.3[1m]", "glm-5.3-flash", "glm-5.2", "glm-5.2[1m]", "glm-5.1", "glm-5", "glm-4.6"],
-    modelContextWindows: { "glm-5.3": 1_000_000, "glm-5.3[1m]": 1_000_000, "glm-5.3-flash": 1_000_000, "glm-5.2": 1_000_000, "glm-5.2[1m]": 1_000_000 },
-    // Z.AI's OpenAI path returns 400 code 1211 for bracketed model ids.
+    // The upstream catalog reports 1_048_576 for the 5.3 family, which is what the domestic
+    // Responses row already carries. Both are documented as "1M"; this is that number.
+    modelContextWindows: { "glm-5.3": 1_048_576, "glm-5.3[1m]": 1_048_576, "glm-5.3-flash": 1_048_576, "glm-5.2": 1_000_000, "glm-5.2[1m]": 1_000_000 },
+    // Z.AI returns 400 for bracketed model ids on both wires; the aliases are local.
     modelSuffixBracketStrip: true,
     noVisionModels: ZAI_GLM_5X_SIDECAR_VISION_MODELS,
+    modelInputModalities: ZAI_GLM_5X_INPUT_MODALITIES,
     modelReasoningEfforts: ZAI_GLM_5X_REASONING_EFFORTS,
     modelDefaultReasoningEfforts: Object.fromEntries(ZAI_GLM_53_MODELS.map(id => [id, "max"])),
     modelMaxOutputTokens: Object.fromEntries(ZAI_GLM_53_MODELS.map(id => [id, 131_072])),
     modelSupportsReasoningSummaries: Object.fromEntries(ZAI_GLM_5X_MODELS.map(id => [id, true])),
     preserveReasoningContentModels: ZAI_GLM_5X_MODELS,
+    // Responses replay uses this provider-level flag; the model list above still covers a
+    // caller who opts back into Chat.
+    preserveResponsesReasoningContent: true,
   },
   // Zhipu's domestic BigModel platform: OpenAI-compatible pay-as-you-go on open.bigmodel.cn — a
   // different host and billing product from the `zai` coding-plan subscription above.
@@ -2630,6 +2776,7 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     modelContextWindows: { "glm-5.3": 1_000_000, "glm-5.3[1m]": 1_000_000, "glm-5.3-flash": 1_000_000, "glm-5.2": 1_000_000, "glm-5.2[1m]": 1_000_000 },
     modelSuffixBracketStrip: true,
     noVisionModels: ZAI_GLM_5X_SIDECAR_VISION_MODELS,
+    modelInputModalities: ZAI_GLM_5X_INPUT_MODALITIES,
     modelReasoningEfforts: ZAI_GLM_5X_REASONING_EFFORTS,
     modelSupportsReasoningSummaries: Object.fromEntries(ZAI_GLM_5X_MODELS.map(id => [id, true])),
     preserveReasoningContentModels: ZAI_GLM_5X_MODELS,
@@ -2759,13 +2906,11 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     ),
     thinkingToggleModels: VOLCENGINE_DOUBAO_THINKING_MODELS,
     preserveReasoningContentModels: [
-      "deepseek-v4-pro-260425",
       "deepseek-v4-flash-260425",
       "glm-5-2-260617",
       "glm-4-7-251222",
     ],
     noVisionModels: [
-      "deepseek-v4-pro-260425",
       "deepseek-v4-flash-260425",
       "deepseek-v3-2-251201",
       "glm-5-2-260617",
@@ -2787,12 +2932,12 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     modelInputModalities: VOLCENGINE_PLAN_INPUT_MODALITIES,
     noVisionModels: VOLCENGINE_PLAN_TEXT_ONLY_MODELS,
     modelReasoningEfforts: Object.fromEntries(
-      DEEPSEEK_THINKING_MODELS.map(id => [id, deepseekThinkingEffortsFor(id)]),
+      DEEPSEEK_V4_LEGACY_MODELS.map(id => [id, deepseekThinkingEffortsFor(id)]),
     ),
     modelReasoningEffortMap: Object.fromEntries(
-      DEEPSEEK_THINKING_MODELS.map(id => [id, deepseekReasoningMapFor(id)]),
+      DEEPSEEK_V4_LEGACY_MODELS.map(id => [id, deepseekReasoningMapFor(id)]),
     ),
-    preserveReasoningContentModels: DEEPSEEK_THINKING_MODELS,
+    preserveReasoningContentModels: DEEPSEEK_V4_LEGACY_MODELS,
     note: "Coding tools only. Volcengine restricts Coding Plan quota to supported AI coding tools and warns that using this key for general API calls may suspend the subscription or ban the account. Use the plan key issued by the Ark console.",
   },
   {
@@ -2806,7 +2951,9 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     supportsServiceTier: false,
     preserveCustomDestination: true,
     dashboardUrl: "https://console.volcengine.com/ark/region:ark+cn-beijing/overview",
-    defaultModel: "deepseek-v4-pro",
+    // Was `deepseek-v4-pro` until DeepSeek retired it; the plan roster's other DeepSeek
+    // entry takes over so a fresh install still lands on a working default.
+    defaultModel: "deepseek-v4-flash",
     models: VOLCENGINE_AGENT_PLAN_MODELS,
     liveModels: false,
     modelInputModalities: VOLCENGINE_PLAN_INPUT_MODALITIES,
@@ -2831,7 +2978,7 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     modelInputModalities: ALIBABA_TOKEN_PLAN_INPUT_MODALITIES,
     modelContextWindows: {
       "qwen3.8-max": 983_616, "qwen3.7-max": 1_000_000, "qwen3.7-plus": 1_000_000,
-      "qwen3.6-flash": 1_000_000, "glm-5.3": 1_000_000, "glm-5.3-flash": 1_000_000, "glm-5.2": 1_000_000, "deepseek-v4-pro": 1_000_000,
+      "qwen3.6-flash": 1_000_000, "glm-5.3": 1_000_000, "glm-5.3-flash": 1_000_000, "glm-5.2": 1_000_000, 
     },
     modelReasoningEfforts: {
       ...Object.fromEntries(ALIBABA_TOKEN_PLAN_QWEN_MODELS.map(id => [id, THINKING_BUDGET_EFFORTS])),
@@ -2839,14 +2986,12 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
       "glm-5.3": ZAI_GLM_53_REASONING_EFFORTS,
       "glm-5.3-flash": ZAI_GLM_53_REASONING_EFFORTS,
       "glm-5.2": ZAI_GLM_52_REASONING_EFFORTS,
-      "deepseek-v4-pro": deepseekThinkingEffortsFor("deepseek-v4-pro"),
     },
     modelDefaultReasoningEfforts: { "qwen3.8-max": "xhigh" },
-    modelReasoningEffortMap: { "deepseek-v4-pro": deepseekReasoningMapFor("deepseek-v4-pro") },
     directReasoningEffortModels: ["qwen3.8-max"],
     thinkingBudgetModels: ALIBABA_TOKEN_PLAN_QWEN_MODELS.filter(id => id !== "qwen3.8-max"),
-    preserveReasoningContentModels: ["glm-5.3", "glm-5.3-flash", "glm-5.2", "deepseek-v4-pro", "qwen3.8-max", "qwen3.7-max", "qwen3.7-plus", "qwen3.6-flash"],
-    noVisionModels: ["glm-5.3", "glm-5.2", "deepseek-v4-pro"],
+    preserveReasoningContentModels: ["glm-5.3", "glm-5.3-flash", "glm-5.2", "qwen3.8-max", "qwen3.7-max", "qwen3.7-plus", "qwen3.6-flash"],
+    noVisionModels: ["glm-5.3", "glm-5.2"],
   },
   {
     id: "alibaba-token-plan-intl",
@@ -2866,7 +3011,7 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     modelContextWindows: {
       "qwen3.8-max": 983_616,
       "qwen3.7-max": 1_000_000, "qwen3.7-plus": 1_000_000, "qwen3.6-plus": 1_000_000, "qwen3.6-flash": 1_000_000,
-      "deepseek-v4-pro": 1_000_000, "deepseek-v4-flash": 1_000_000, "deepseek-v3.2": 131_072,
+      "deepseek-v4-flash": 1_000_000, "deepseek-v3.2": 131_072,
       "kimi-k2.7-code": 262_144, "kimi-k2.6": 262_144, "kimi-k2.5": 262_144,
       "glm-5.3": 1_000_000, "glm-5.3-flash": 1_000_000, "glm-5.2": 1_000_000, "glm-5.1": 1_000_000, "glm-5": 1_000_000,
       "MiniMax-M2.5": 204_800,
@@ -2877,17 +3022,15 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
       "glm-5.3": ZAI_GLM_53_REASONING_EFFORTS,
       "glm-5.3-flash": ZAI_GLM_53_REASONING_EFFORTS,
       "glm-5.2": ZAI_GLM_52_REASONING_EFFORTS,
-      "deepseek-v4-pro": deepseekThinkingEffortsFor("deepseek-v4-pro"),
       "deepseek-v4-flash": deepseekThinkingEffortsFor("deepseek-v4-flash"),
     },
     modelReasoningEffortMap: {
-      "deepseek-v4-pro": deepseekReasoningMapFor("deepseek-v4-pro"),
       "deepseek-v4-flash": deepseekReasoningMapFor("deepseek-v4-flash"),
     },
     directReasoningEffortModels: ["qwen3.8-max"],
     thinkingBudgetModels: ALIBABA_INTL_TOKEN_PLAN_QWEN_MODELS.filter(id => id !== "qwen3.8-max"),
-    preserveReasoningContentModels: ["glm-5.3", "glm-5.3-flash", "glm-5.2", "deepseek-v4-pro", "deepseek-v4-flash", "qwen3.8-max", "qwen3.7-max", "qwen3.7-plus", "qwen3.6-plus", "qwen3.6-flash"],
-    noVisionModels: ["deepseek-v4-pro", "deepseek-v4-flash", "deepseek-v3.2", "glm-5.3", "glm-5.2", "glm-5.1", "glm-5", "MiniMax-M2.5"],
+    preserveReasoningContentModels: ["glm-5.3", "glm-5.3-flash", "glm-5.2", "deepseek-v4-flash", "qwen3.8-max", "qwen3.7-max", "qwen3.7-plus", "qwen3.6-plus", "qwen3.6-flash"],
+    noVisionModels: ["deepseek-v4-flash", "deepseek-v3.2", "glm-5.3", "glm-5.2", "glm-5.1", "glm-5", "MiniMax-M2.5"],
     noReasoningModels: ["kimi-k2.7-code", "kimi-k2.6", "kimi-k2.5", "deepseek-v3.2", "glm-5.1", "glm-5", "MiniMax-M2.5"],
     modelDefaultReasoningEfforts: { "qwen3.8-max": "xhigh" },
   },
@@ -2925,7 +3068,7 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     authKind: "key",
     dashboardUrl: "https://ollama.com/settings/keys",
     // Live IDs verified 2026-07-10; qwen3-coder:480b retires 2026-07-15.
-    models: ["glm-5.3", "glm-5.3-flash", "glm-5.2", "deepseek-v4-pro", "qwen3-coder:480b", "gpt-oss:120b", "kimi-k2.6", "minimax-m3", "qwen3.5:397b", "gemma4:31b"],
+    models: ["glm-5.3", "glm-5.3-flash", "glm-5.2", "qwen3-coder:480b", "gpt-oss:120b", "kimi-k2.6", "minimax-m3", "qwen3.5:397b", "gemma4:31b"],
     defaultModel: "glm-5.3",
     // Owner-audited exact outage fallback: these current Ollama Cloud GLM-5.3 rows have
     // 1,048,576-token context windows. Live discovery and successful /api/show enrichment keep
@@ -2937,7 +3080,7 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
       "glm-5.3", "glm-5.2", "glm-5.1", "glm-5", "glm-4.7",
       "minimax-m2.7", "minimax-m2.5", "minimax-m2.1",
       "nemotron-3-ultra", "nemotron-3-super",
-      "deepseek-v4-pro", "deepseek-v4-flash",
+      "deepseek-v4-flash",
       "gpt-oss", "qwen3-coder:480b",
     ],
     // Ollama's native chat API has no `text.verbosity` equivalent and the ollama-native adapter
@@ -3021,12 +3164,12 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     // Zen DeepSeek thinking models — never serialize a bare tool-call turn.
     note: "Keyed OpenCode Zen gateway. Free models on this tier are often short-window rate-limited at roughly 15-20 requests/minute (community-measured; OpenCode does not publish RPM). Zen may return generic 429s without Retry-After / X-RateLimit headers; when Retry-After is omitted, opencodex adds a synthetic backoff hint (upstream Retry-After still wins). Distinct from the keyless opencode-free desktop quota (~200 Big Pickle/free-model requests per 5 hours). Docs: https://opencode.ai/docs/zen/. Free-model prompts may be retained for training — do not send confidential material.",
     modelReasoningEfforts: Object.fromEntries(
-      [...DEEPSEEK_THINKING_MODELS, ...OPENCODE_FREE_DEEPSEEK_MODELS].map(id => [id, deepseekThinkingEffortsFor(id)]),
+      [...DEEPSEEK_GATEWAY_THINKING_MODELS, ...OPENCODE_FREE_DEEPSEEK_MODELS].map(id => [id, deepseekThinkingEffortsFor(id)]),
     ),
     modelReasoningEffortMap: Object.fromEntries(
-      [...DEEPSEEK_THINKING_MODELS, ...OPENCODE_FREE_DEEPSEEK_MODELS].map(id => [id, deepseekReasoningMapFor(id)]),
+      [...DEEPSEEK_GATEWAY_THINKING_MODELS, ...OPENCODE_FREE_DEEPSEEK_MODELS].map(id => [id, deepseekReasoningMapFor(id)]),
     ),
-    preserveReasoningContentModels: [...DEEPSEEK_THINKING_MODELS, ...OPENCODE_FREE_DEEPSEEK_MODELS],
+    preserveReasoningContentModels: [...DEEPSEEK_GATEWAY_THINKING_MODELS, ...OPENCODE_FREE_DEEPSEEK_MODELS],
     // Same Zen gateway as opencode-free: the DeepSeek vision preview id
     // (merges into deepseek-v4-flash later).
     modelContextWindows: {
@@ -3035,7 +3178,10 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     modelInputModalities: {
       [DEEPSEEK_VISION_PREVIEW_MODEL]: ["text", "image"],
     },
-    noVisionModels: [...OPENCODE_ZEN_TEXT_ONLY_MODELS, ...DEEPSEEK_THINKING_MODELS],
+    noVisionModels: [...OPENCODE_ZEN_TEXT_ONLY_MODELS, ...DEEPSEEK_GATEWAY_THINKING_MODELS],
+    // Same DeepSeek routes as the Go preset above, behind the same vendor, so they carry
+    // the same json_schema rejection (#1338 / #1415).
+    noJsonSchemaModels: [...DEEPSEEK_GATEWAY_THINKING_MODELS, ...OPENCODE_FREE_DEEPSEEK_MODELS],
   },
   { id: "vercel-ai-gateway", label: "Vercel AI Gateway", baseUrl: "https://ai-gateway.vercel.sh/v1", adapter: "openai-chat", authKind: "key", dashboardUrl: "https://vercel.com/dashboard" },
   {
@@ -3076,6 +3222,10 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     // Same Zen roster behind the same base URL, so it carries the same measured
     // text-only list rather than only its DeepSeek member (#1043).
     noVisionModels: OPENCODE_ZEN_TEXT_ONLY_MODELS,
+    // Same reasoning: the free tier is the same Zen roster, so its DeepSeek members get
+    // the keyed tier's json_schema treatment and its reasoning contract rather than a
+    // narrower table that silently falls behind whenever the keyed one is updated.
+    noJsonSchemaModels: [...DEEPSEEK_GATEWAY_THINKING_MODELS, ...OPENCODE_FREE_DEEPSEEK_MODELS],
   },
   { id: "xiaomi", label: "Xiaomi MiMo", baseUrl: "https://api.xiaomimimo.com/anthropic", adapter: "anthropic", authKind: "key", dashboardUrl: "https://xiaomimimo.com", defaultModel: "mimo-v2.5-pro" },
   // Xiaomi's public OpenAI-compatible endpoint is a distinct transport from both the Anthropic
@@ -3417,12 +3567,22 @@ export function registryEntryForProviderDestination(
   if (typeof provider.baseUrl !== "string" || !provider.baseUrl) return undefined;
   if (provider.authMode !== undefined && provider.authMode !== "key") return undefined;
   const endpoint = normalizedProviderEndpoint(provider.baseUrl);
-  return PROVIDER_REGISTRY.find(entry =>
+  const eligible = (entry: ProviderRegistryEntry): boolean =>
     entry.authKind === "key"
     && !entry.allowBaseUrlOverride
-    && !/\{[^}]*\}/.test(entry.baseUrl)
+    && !/\{[^}]*\}/.test(entry.baseUrl);
+  const direct = PROVIDER_REGISTRY.find(entry =>
+    eligible(entry)
     && entry.adapter === provider.adapter
     && normalizedProviderEndpoint(entry.baseUrl) === endpoint);
+  if (direct) return direct;
+  // A row that moved keeps answering for the address it used to occupy, so an existing
+  // custom provider written against the old endpoint does not silently lose its metadata.
+  return PROVIDER_REGISTRY.find(entry =>
+    eligible(entry)
+    && (entry.destinationAliases ?? []).some(alias =>
+      alias.adapter === provider.adapter
+      && normalizedProviderEndpoint(alias.baseUrl) === endpoint));
 }
 
 /**
diff --git a/src/providers/stale-context-window-migration.ts b/src/providers/stale-context-window-migration.ts
new file mode 100644
index 0000000000..5fb1eea2ec
--- /dev/null
+++ b/src/providers/stale-context-window-migration.ts
@@ -0,0 +1,92 @@
+/**
+ * Repair context windows that a saved config inherited from a wrong registry seed.
+ *
+ * `enrichProviderFromRegistry` is fill-only: it seeds `modelContextWindows` when
+ * the row has none and never rewrites it afterwards. That posture is right — a
+ * hand-tuned window must survive an upgrade — but it means a registry table that
+ * shipped WRONG numbers is frozen into every config that was saved while those
+ * numbers were current. Correcting the registry alone fixes new installs and
+ * leaves existing ones reporting the old figure forever.
+ *
+ * This rewrites one thing: a window whose saved value is still byte-for-byte the
+ * wrong number this file names, on a provider that still carries the registry's
+ * adapter. A value the user changed does not match `from` and is left alone, and
+ * nothing else in the row is touched. Same shape and the same restraint as
+ * `model-rename-migration`, for the case where the id was right and the number
+ * was not.
+ */
+import { PROVIDER_REGISTRY } from "./registry";
+import type { OcxConfig } from "../types";
+
+export interface StaleContextWindow {
+  /** Registry provider id whose saved rows may carry the wrong window. */
+  provider: string;
+  model: string;
+  /** The wrong value this migration is allowed to replace, and nothing else. */
+  from: number;
+  to: number;
+}
+
+export interface StaleContextWindowProjection {
+  config: OcxConfig;
+  changed: boolean;
+  warnings: string[];
+}
+
+/**
+ * Cognition windows corrected against a live `GetCascadeModelConfigs` response.
+ *
+ * The shipped table had been assembled from each model's ORIGINAL vendor window
+ * rather than from what Cognition serves, so the Claude rows claimed 200k against
+ * an actual 1M and Grok claimed 256k against 500k. Cognition documents no window
+ * anywhere, so the per-account catalog is the only first-party source; these are
+ * the degraded-mode figures, and live discovery supersedes them when it runs.
+ */
+export const STALE_CONTEXT_WINDOWS: readonly StaleContextWindow[] = [
+  { provider: "devin", model: "swe-1-7", from: 256_000, to: 262_000 },
+  { provider: "devin", model: "swe-1-7-lightning", from: 256_000, to: 202_752 },
+  { provider: "devin", model: "gpt-5-6-sol", from: 1_050_000, to: 1_000_000 },
+  { provider: "devin", model: "gpt-5-6-luna", from: 1_050_000, to: 1_000_000 },
+  { provider: "devin", model: "gpt-5-6-terra", from: 1_050_000, to: 1_000_000 },
+  { provider: "devin", model: "claude-opus-4-8", from: 200_000, to: 1_000_000 },
+  { provider: "devin", model: "claude-fable-5-1", from: 200_000, to: 1_000_000 },
+  { provider: "devin", model: "claude-sonnet-5", from: 200_000, to: 1_000_000 },
+  { provider: "devin", model: "kimi-k2-7", from: 256_000, to: 262_144 },
+  { provider: "devin", model: "grok-4-5", from: 256_000, to: 500_000 },
+];
+
+function providerStillMatchesRegistry(id: string, adapter: unknown): boolean {
+  const entry = PROVIDER_REGISTRY.find(row => row.id === id);
+  return entry !== undefined && entry.adapter === adapter;
+}
+
+/** Pure projection. The caller decides whether to persist. */
+export function projectStaleContextWindows(
+  config: OcxConfig,
+  entries: readonly StaleContextWindow[] = STALE_CONTEXT_WINDOWS,
+): StaleContextWindowProjection {
+  const warnings: string[] = [];
+  const repaired = new Map<string, string[]>();
+
+  for (const entry of entries) {
+    const prov = config.providers?.[entry.provider];
+    if (!prov) continue;
+    if (!providerStillMatchesRegistry(entry.provider, prov.adapter)) continue;
+    const windows = prov.modelContextWindows;
+    if (!windows || windows[entry.model] !== entry.from) continue;
+    windows[entry.model] = entry.to;
+    const list = repaired.get(entry.provider) ?? [];
+    list.push(`${entry.model} ${entry.from} -> ${entry.to}`);
+    repaired.set(entry.provider, list);
+  }
+
+  for (const [provider, list] of repaired) {
+    warnings.push(
+      `corrected ${list.length} context window(s) on "${provider}" that the saved config `
+      + `inherited from a wrong registry seed: ${list.join(", ")}.`,
+    );
+  }
+
+  return { config, changed: repaired.size > 0, warnings };
+}
+
diff --git a/src/providers/zai-responses-migration.ts b/src/providers/zai-responses-migration.ts
new file mode 100644
index 0000000000..c31b26e398
--- /dev/null
+++ b/src/providers/zai-responses-migration.ts
@@ -0,0 +1,45 @@
+import { getProviderRegistryEntry, providerMatchesRegistryTransport } from "./registry";
+import type { OcxConfig } from "../types";
+
+export const ZAI_PROVIDER_ID = "zai";
+export const ZAI_RESPONSES_DEFAULT_VERSION = 1;
+
+/**
+ * Persist the Responses destination the router already applies to the `zai` row.
+ *
+ * The Z.AI coding plan moved from Chat Completions at /api/coding/paas/v4 to Responses at
+ * /api/v1 (#4297). A config written before that move still stores the Chat adapter and the old
+ * base URL, and `routedProviderConfig()` rewrites both on every request because the registry
+ * entry owns a fixed destination. The row therefore already talks Responses while the dashboard,
+ * `ocx doctor` and any direct config reader show the retired Chat endpoint, and each boot logs a
+ * "configured baseUrl is ignored" warning about a value the user never chose.
+ *
+ * This migration writes the canonical pair once so the stored row matches the live wire. It is
+ * behavior-preserving by construction: it only rewrites rows the router canonicalizes anyway.
+ * Chat remains reachable per model through `modelAdapters`, and the persisted marker keeps a
+ * later explicit Chat choice from being migrated again.
+ *
+ * A custom-named provider pointing at the retired endpoint is deliberately left alone. The router
+ * does not canonicalize it, so rewriting it would change a wire the operator actually configured;
+ * `destinationAliases` already gives it this row's metadata.
+ */
+export function migrateZaiResponsesDefault(config: OcxConfig): boolean {
+  const provider = config.providers[ZAI_PROVIDER_ID];
+  if (!provider || (provider.zaiResponsesDefaultVersion ?? 0) >= ZAI_RESPONSES_DEFAULT_VERSION) return false;
+  const entry = getProviderRegistryEntry(ZAI_PROVIDER_ID);
+  if (!entry) return false;
+  // Fail closed if a later registry edit makes this destination operator-owned: only a fixed,
+  // non-templated endpoint is canonicalized at request time, so only that one may be persisted.
+  if (entry.allowBaseUrlOverride || /\{[^}]*\}/.test(entry.baseUrl)) return false;
+  if (!providerMatchesRegistryTransport(ZAI_PROVIDER_ID, provider)) return false;
+  config.providers = {
+    ...config.providers,
+    [ZAI_PROVIDER_ID]: {
+      ...provider,
+      adapter: entry.adapter,
+      baseUrl: entry.baseUrl,
+      zaiResponsesDefaultVersion: ZAI_RESPONSES_DEFAULT_VERSION,
+    },
+  };
+  return true;
+}
diff --git a/src/quota/reset-observer.ts b/src/quota/reset-observer.ts
index 524e4de2e1..6b67194236 100644
--- a/src/quota/reset-observer.ts
+++ b/src/quota/reset-observer.ts
@@ -55,6 +55,7 @@ export function observeQuotaSnapshot(input: {
   readonly accountKey: string;
   readonly windows: ReadonlyArray<QuotaWindowObservation>;
   readonly now?: number;
+  readonly retainAbsentShortWindow?: boolean;
 }): QuotaResetEvent[] {
   try {
     if (!sink) return [];
@@ -65,7 +66,7 @@ export function observeQuotaSnapshot(input: {
     // between two observations to tell a rolling window's natural decay from a real reset,
     // and only this layer knows when the snapshot was taken.
     const stamped = input.windows.map(window => ({ ...window, observedAt: now }));
-    const previous = swapLastObservedWindows(input.scope, accountTag, stamped);
+    const previous = swapLastObservedWindows(input.scope, accountTag, stamped, input.retainAbsentShortWindow);
     if (!previous) return [];
 
     const detected = detectQuotaResets({
diff --git a/src/quota/reset-seen-store.ts b/src/quota/reset-seen-store.ts
index 72cad7a876..6b06884ece 100644
--- a/src/quota/reset-seen-store.ts
+++ b/src/quota/reset-seen-store.ts
@@ -306,6 +306,7 @@ export function swapLastObservedWindows(
   scope: string,
   accountTag: string,
   windows: ReadonlyArray<QuotaWindowObservation>,
+  retainAbsentShortWindow = false,
 ): ReadonlyArray<QuotaWindowObservation> | undefined {
   hydrate();
   const key = observedKey(scope, accountTag);
@@ -317,7 +318,14 @@ export function swapLastObservedWindows(
   // Measured: the hottest scope was evicted and its next genuine scheduled reset was
   // silently missed, because a re-baselined row has no previous value to diff against.
   observed.delete(key);
-  observed.set(key, windows.map(window => ({ ...window })));
+  const next = windows.map(window => ({ ...window }));
+  // Codex display eviction is not a new short observation. Retain notification history
+  // with its original clock until a real reading replaces it or account cleanup forgets it.
+  if (retainAbsentShortWindow && !next.some(window => window.window === "5h")) {
+    const short = previous?.find(window => window.window === "5h");
+    if (short) next.push({ ...short });
+  }
+  observed.set(key, next);
   if (observed.size > MAX_OBSERVED_SCOPES) {
     // Least-recently-observed first. Evicting only costs a re-baseline, never a duplicate
     // notification, because the claim ledger is separate — but a re-baseline DOES cost the
diff --git a/src/remote-control/crypto.ts b/src/remote-control/crypto.ts
new file mode 100644
index 0000000000..830340078f
--- /dev/null
+++ b/src/remote-control/crypto.ts
@@ -0,0 +1,442 @@
+import {
+  createCipheriv,
+  createDecipheriv,
+  createHash,
+  createPrivateKey,
+  createPublicKey,
+  diffieHellman,
+  generateKeyPairSync,
+  hkdfSync,
+  randomBytes,
+  sign,
+  verify,
+  type KeyObject,
+} from "node:crypto";
+import {
+  REMOTE_CONTROL_MAX_RELAY_PAYLOAD_BYTES,
+  REMOTE_CONTROL_PROTOCOL_VERSION,
+  isRemoteControlCommandProfile,
+  isRemoteControlUuid,
+  normalizeRemoteControlCapabilities,
+  remoteControlUuidBytes,
+  type RemoteControlCapability,
+  type RemoteControlClientHello,
+  type RemoteControlCommandProfile,
+  type RemoteControlHostHello,
+} from "./protocol";
+
+const HELLO_MAX_BYTES = 16 * 1024;
+const NONCE_BYTES = 32;
+const GCM_TAG_BYTES = 16;
+const COUNTER_BYTES = 8;
+const MAX_COUNTER = 0xffff_ffff_ffff_ffffn;
+const MAX_ENCRYPTED_PLAINTEXT_BYTES = REMOTE_CONTROL_MAX_RELAY_PAYLOAD_BYTES - GCM_TAG_BYTES - COUNTER_BYTES;
+const BASE64URL_PATTERN = /^[A-Za-z0-9_-]+$/;
+
+export interface RemoteControlIdentityKeyPair {
+  publicKey: string;
+  privateKey: string;
+}
+
+export interface CreateRemoteControlClientHandshakeOptions {
+  sessionId: string;
+  deviceId: string;
+  commandProfile: RemoteControlCommandProfile;
+  capabilities: readonly RemoteControlCapability[];
+  accountPrivateKey: string;
+}
+
+export interface AcceptRemoteControlClientHelloOptions {
+  expectedSessionId: string;
+  expectedDeviceId: string;
+  accountPublicKey: string;
+  devicePrivateKey: string;
+  allowedCapabilities: readonly RemoteControlCapability[];
+}
+
+function encode(value: Uint8Array): string {
+  return Buffer.from(value).toString("base64url");
+}
+
+function decode(value: unknown, label: string, maxBytes: number): Buffer {
+  if (typeof value !== "string" || !BASE64URL_PATTERN.test(value) || value.length > Math.ceil(maxBytes * 4 / 3) + 4) {
+    throw new Error(`invalid ${label}`);
+  }
+  const decoded = Buffer.from(value, "base64url");
+  if (decoded.byteLength === 0 || decoded.byteLength > maxBytes || encode(decoded) !== value) throw new Error(`invalid ${label}`);
+  return decoded;
+}
+
+function privateSigningKey(value: string): KeyObject {
+  const key = createPrivateKey({ key: decode(value, "remote control private key", 256), format: "der", type: "pkcs8" });
+  if (key.asymmetricKeyType !== "ed25519") throw new Error("remote control private key must be Ed25519");
+  return key;
+}
+
+function publicSigningKey(value: string): KeyObject {
+  const key = createPublicKey({ key: decode(value, "remote control public key", 256), format: "der", type: "spki" });
+  if (key.asymmetricKeyType !== "ed25519") throw new Error("remote control public key must be Ed25519");
+  return key;
+}
+
+function publicEphemeralKey(value: string): KeyObject {
+  const key = createPublicKey({ key: decode(value, "remote control ephemeral key", 256), format: "der", type: "spki" });
+  if (key.asymmetricKeyType !== "ec" || key.asymmetricKeyDetails?.namedCurve !== "prime256v1") {
+    throw new Error("remote control ephemeral key must use P-256");
+  }
+  return key;
+}
+
+function lengthPrefixed(value: Uint8Array): Buffer {
+  if (value.byteLength > 0xffff) throw new Error("remote control transcript field is too large");
+  const length = Buffer.alloc(2);
+  length.writeUInt16BE(value.byteLength);
+  return Buffer.concat([length, Buffer.from(value)]);
+}
+
+function capabilityTranscript(capabilities: readonly RemoteControlCapability[]): Buffer {
+  const normalized = normalizeRemoteControlCapabilities([...capabilities]);
+  return Buffer.concat([
+    Buffer.from([normalized.length]),
+    ...normalized.map(capability => lengthPrefixed(Buffer.from(capability, "utf8"))),
+  ]);
+}
+
+function clientTranscript(hello: Omit<RemoteControlClientHello, "signature">): Buffer {
+  return Buffer.concat([
+    Buffer.from("opencodex-remote-control-client-v1\0", "utf8"),
+    Buffer.from([hello.version]),
+    Buffer.from(remoteControlUuidBytes(hello.sessionId)),
+    Buffer.from(remoteControlUuidBytes(hello.deviceId)),
+    lengthPrefixed(Buffer.from(hello.commandProfile, "utf8")),
+    capabilityTranscript(hello.capabilities),
+    lengthPrefixed(decode(hello.ephemeralPublicKey, "remote control ephemeral key", 256)),
+    decode(hello.nonce, "remote control client nonce", NONCE_BYTES),
+  ]);
+}
+
+function hostTranscript(
+  client: Buffer,
+  hello: Omit<RemoteControlHostHello, "signature">,
+): Buffer {
+  return Buffer.concat([
+    Buffer.from("opencodex-remote-control-host-v1\0", "utf8"),
+    createHash("sha256").update(client).digest(),
+    capabilityTranscript(hello.capabilities),
+    lengthPrefixed(decode(hello.ephemeralPublicKey, "remote control ephemeral key", 256)),
+    decode(hello.nonce, "remote control host nonce", NONCE_BYTES),
+  ]);
+}
+
+function parseJsonObject(value: Uint8Array, label: string): Record<string, unknown> {
+  if (!(value instanceof Uint8Array) || value.byteLength === 0 || value.byteLength > HELLO_MAX_BYTES) {
+    throw new Error(`invalid ${label}`);
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(value));
+  } catch {
+    throw new Error(`invalid ${label}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`invalid ${label}`);
+  return parsed as Record<string, unknown>;
+}
+
+function validateCommonHello(raw: Record<string, unknown>, label: string): {
+  sessionId: string;
+  deviceId: string;
+  capabilities: RemoteControlCapability[];
+  ephemeralPublicKey: string;
+  nonce: string;
+  signature: string;
+} {
+  if (raw.version !== REMOTE_CONTROL_PROTOCOL_VERSION) throw new Error(`unsupported ${label} version`);
+  if (!isRemoteControlUuid(raw.sessionId) || !isRemoteControlUuid(raw.deviceId)) throw new Error(`invalid ${label} identity`);
+  const capabilities = normalizeRemoteControlCapabilities(raw.capabilities);
+  if (typeof raw.ephemeralPublicKey !== "string" || typeof raw.nonce !== "string" || typeof raw.signature !== "string") {
+    throw new Error(`invalid ${label} cryptographic fields`);
+  }
+  const ephemeralPublicKey = raw.ephemeralPublicKey;
+  const encodedNonce = raw.nonce;
+  const encodedSignature = raw.signature;
+  decode(ephemeralPublicKey, `${label} ephemeral key`, 256);
+  const nonce = decode(encodedNonce, `${label} nonce`, NONCE_BYTES);
+  if (nonce.byteLength !== NONCE_BYTES) throw new Error(`invalid ${label} nonce`);
+  const signature = decode(encodedSignature, `${label} signature`, 128);
+  if (signature.byteLength !== 64) throw new Error(`invalid ${label} signature`);
+  return {
+    sessionId: raw.sessionId,
+    deviceId: raw.deviceId,
+    capabilities,
+    ephemeralPublicKey,
+    nonce: encodedNonce,
+    signature: encodedSignature,
+  };
+}
+
+export function parseRemoteControlClientHello(value: Uint8Array): RemoteControlClientHello {
+  const raw = parseJsonObject(value, "remote control client hello");
+  const common = validateCommonHello(raw, "remote control client hello");
+  if (!isRemoteControlCommandProfile(raw.commandProfile)) throw new Error("invalid remote control command profile");
+  return {
+    version: REMOTE_CONTROL_PROTOCOL_VERSION,
+    ...common,
+    commandProfile: raw.commandProfile,
+  };
+}
+
+export function parseRemoteControlHostHello(value: Uint8Array): RemoteControlHostHello {
+  const raw = parseJsonObject(value, "remote control host hello");
+  return { version: REMOTE_CONTROL_PROTOCOL_VERSION, ...validateCommonHello(raw, "remote control host hello") };
+}
+
+export function serializeRemoteControlHello(value: RemoteControlClientHello | RemoteControlHostHello): Uint8Array {
+  const encoded = new TextEncoder().encode(JSON.stringify(value));
+  if (encoded.byteLength > HELLO_MAX_BYTES) throw new Error("remote control hello is too large");
+  return encoded;
+}
+
+export function generateRemoteControlIdentityKeyPair(): RemoteControlIdentityKeyPair {
+  const pair = generateKeyPairSync("ed25519");
+  return {
+    publicKey: encode(pair.publicKey.export({ format: "der", type: "spki" })),
+    privateKey: encode(pair.privateKey.export({ format: "der", type: "pkcs8" })),
+  };
+}
+
+function nonce(prefix: Buffer, counter: bigint): Buffer {
+  const result = Buffer.alloc(12);
+  prefix.copy(result, 0);
+  result.writeBigUInt64BE(counter, 4);
+  return result;
+}
+
+function frameAad(sessionId: string, direction: 0 | 1, counter: bigint): Buffer {
+  const counterBytes = Buffer.alloc(COUNTER_BYTES);
+  counterBytes.writeBigUInt64BE(counter);
+  return Buffer.concat([
+    Buffer.from("opencodex-remote-control-frame-v1\0", "utf8"),
+    Buffer.from(remoteControlUuidBytes(sessionId)),
+    Buffer.from([direction]),
+    counterBytes,
+  ]);
+}
+
+export class RemoteControlCipher {
+  private sendCounter = 0n;
+  private receiveCounter = 0n;
+  private destroyed = false;
+
+  constructor(
+    private readonly sessionId: string,
+    private readonly sendDirection: 0 | 1,
+    private readonly sendKey: Buffer,
+    private readonly receiveKey: Buffer,
+    private readonly sendNoncePrefix: Buffer,
+    private readonly receiveNoncePrefix: Buffer,
+  ) {}
+
+  encrypt(value: Uint8Array): Uint8Array {
+    if (this.destroyed) throw new Error("remote control cipher is closed");
+    if (!(value instanceof Uint8Array) || value.byteLength > MAX_ENCRYPTED_PLAINTEXT_BYTES) {
+      throw new Error("remote control encrypted payload is too large");
+    }
+    if (this.sendCounter > MAX_COUNTER) throw new Error("remote control send counter exhausted");
+    const counter = this.sendCounter;
+    const cipher = createCipheriv("aes-256-gcm", this.sendKey, nonce(this.sendNoncePrefix, counter), { authTagLength: GCM_TAG_BYTES });
+    cipher.setAAD(frameAad(this.sessionId, this.sendDirection, counter));
+    const ciphertext = Buffer.concat([cipher.update(value), cipher.final()]);
+    const counterBytes = Buffer.alloc(COUNTER_BYTES);
+    counterBytes.writeBigUInt64BE(counter);
+    this.sendCounter += 1n;
+    return Buffer.concat([counterBytes, ciphertext, cipher.getAuthTag()]);
+  }
+
+  decrypt(value: Uint8Array): Uint8Array {
+    if (this.destroyed) throw new Error("remote control cipher is closed");
+    if (
+      !(value instanceof Uint8Array)
+      || value.byteLength < COUNTER_BYTES + GCM_TAG_BYTES
+      || value.byteLength > REMOTE_CONTROL_MAX_RELAY_PAYLOAD_BYTES
+    ) throw new Error("invalid remote control encrypted frame");
+    const bytes = Buffer.from(value);
+    const counter = bytes.readBigUInt64BE(0);
+    if (counter !== this.receiveCounter) throw new Error("replayed or out-of-order remote control frame");
+    const ciphertextEnd = bytes.byteLength - GCM_TAG_BYTES;
+    const decipher = createDecipheriv(
+      "aes-256-gcm",
+      this.receiveKey,
+      nonce(this.receiveNoncePrefix, counter),
+      { authTagLength: GCM_TAG_BYTES },
+    );
+    decipher.setAAD(frameAad(this.sessionId, this.sendDirection === 0 ? 1 : 0, counter));
+    decipher.setAuthTag(bytes.subarray(ciphertextEnd));
+    const plaintext = Buffer.concat([decipher.update(bytes.subarray(COUNTER_BYTES, ciphertextEnd)), decipher.final()]);
+    this.receiveCounter += 1n;
+    return plaintext;
+  }
+
+  destroy(): void {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    this.sendKey.fill(0);
+    this.receiveKey.fill(0);
+    this.sendNoncePrefix.fill(0);
+    this.receiveNoncePrefix.fill(0);
+  }
+}
+
+function deriveCipher(options: {
+  sessionId: string;
+  shared: Buffer;
+  clientNonce: Buffer;
+  hostNonce: Buffer;
+  role: "client" | "host";
+}): RemoteControlCipher {
+  const salt = createHash("sha256").update(options.clientNonce).update(options.hostNonce).digest();
+  const expand = (info: string, length: number): Buffer => Buffer.from(hkdfSync(
+    "sha256",
+    options.shared,
+    salt,
+    Buffer.from(info, "utf8"),
+    length,
+  ));
+  const clientToHostKey = expand("opencodex remote control client to host key v1", 32);
+  const hostToClientKey = expand("opencodex remote control host to client key v1", 32);
+  const clientToHostNonce = expand("opencodex remote control client to host nonce v1", 4);
+  const hostToClientNonce = expand("opencodex remote control host to client nonce v1", 4);
+  options.shared.fill(0);
+  return options.role === "client"
+    ? new RemoteControlCipher(options.sessionId, 0, clientToHostKey, hostToClientKey, clientToHostNonce, hostToClientNonce)
+    : new RemoteControlCipher(options.sessionId, 1, hostToClientKey, clientToHostKey, hostToClientNonce, clientToHostNonce);
+}
+
+export class RemoteControlClientHandshake {
+  readonly hello: RemoteControlClientHello;
+  private completed = false;
+
+  private constructor(
+    hello: RemoteControlClientHello,
+    private readonly ephemeralPrivateKey: KeyObject,
+    private readonly transcript: Buffer,
+  ) {
+    this.hello = hello;
+  }
+
+  static create(options: CreateRemoteControlClientHandshakeOptions): RemoteControlClientHandshake {
+    if (!isRemoteControlUuid(options.sessionId) || !isRemoteControlUuid(options.deviceId)) {
+      throw new Error("invalid remote control handshake identity");
+    }
+    if (!isRemoteControlCommandProfile(options.commandProfile)) throw new Error("invalid remote control command profile");
+    const capabilities = normalizeRemoteControlCapabilities([...options.capabilities]);
+    const ephemeral = generateKeyPairSync("ec", { namedCurve: "prime256v1" });
+    const unsigned: Omit<RemoteControlClientHello, "signature"> = {
+      version: REMOTE_CONTROL_PROTOCOL_VERSION,
+      sessionId: options.sessionId,
+      deviceId: options.deviceId,
+      commandProfile: options.commandProfile,
+      capabilities,
+      ephemeralPublicKey: encode(ephemeral.publicKey.export({ format: "der", type: "spki" })),
+      nonce: encode(randomBytes(NONCE_BYTES)),
+    };
+    const transcript = clientTranscript(unsigned);
+    const hello: RemoteControlClientHello = {
+      ...unsigned,
+      signature: encode(sign(null, transcript, privateSigningKey(options.accountPrivateKey))),
+    };
+    return new RemoteControlClientHandshake(hello, ephemeral.privateKey, transcript);
+  }
+
+  complete(hostHello: RemoteControlHostHello, devicePublicKey: string): RemoteControlCipher {
+    if (this.completed) throw new Error("remote control client handshake already completed");
+    const validated = parseRemoteControlHostHello(serializeRemoteControlHello(hostHello));
+    if (validated.sessionId !== this.hello.sessionId || validated.deviceId !== this.hello.deviceId) {
+      throw new Error("remote control host hello identity mismatch");
+    }
+    const requested = new Set(this.hello.capabilities);
+    if (validated.capabilities.some(capability => !requested.has(capability))) {
+      throw new Error("remote control host granted an unrequested capability");
+    }
+    const unsigned: Omit<RemoteControlHostHello, "signature"> = {
+      version: validated.version,
+      sessionId: validated.sessionId,
+      deviceId: validated.deviceId,
+      capabilities: validated.capabilities,
+      ephemeralPublicKey: validated.ephemeralPublicKey,
+      nonce: validated.nonce,
+    };
+    if (!verify(
+      null,
+      hostTranscript(this.transcript, unsigned),
+      publicSigningKey(devicePublicKey),
+      decode(validated.signature, "remote control host signature", 128),
+    )) throw new Error("remote control host identity verification failed");
+    const cipher = deriveCipher({
+      sessionId: this.hello.sessionId,
+      shared: Buffer.from(diffieHellman({
+        privateKey: this.ephemeralPrivateKey,
+        publicKey: publicEphemeralKey(validated.ephemeralPublicKey),
+      })),
+      clientNonce: decode(this.hello.nonce, "remote control client nonce", NONCE_BYTES),
+      hostNonce: decode(validated.nonce, "remote control host nonce", NONCE_BYTES),
+      role: "client",
+    });
+    this.completed = true;
+    return cipher;
+  }
+}
+
+export function acceptRemoteControlClientHello(
+  clientHello: RemoteControlClientHello,
+  options: AcceptRemoteControlClientHelloOptions,
+): { hello: RemoteControlHostHello; cipher: RemoteControlCipher } {
+  const validated = parseRemoteControlClientHello(serializeRemoteControlHello(clientHello));
+  if (validated.sessionId !== options.expectedSessionId || validated.deviceId !== options.expectedDeviceId) {
+    throw new Error("remote control client hello identity mismatch");
+  }
+  const allowed = new Set(normalizeRemoteControlCapabilities([...options.allowedCapabilities]));
+  const capabilities = validated.capabilities.filter(capability => allowed.has(capability));
+  const unsignedClient: Omit<RemoteControlClientHello, "signature"> = {
+    version: validated.version,
+    sessionId: validated.sessionId,
+    deviceId: validated.deviceId,
+    commandProfile: validated.commandProfile,
+    capabilities: validated.capabilities,
+    ephemeralPublicKey: validated.ephemeralPublicKey,
+    nonce: validated.nonce,
+  };
+  const transcript = clientTranscript(unsignedClient);
+  if (!verify(
+    null,
+    transcript,
+    publicSigningKey(options.accountPublicKey),
+    decode(validated.signature, "remote control client signature", 128),
+  )) throw new Error("remote control account identity verification failed");
+
+  const ephemeral = generateKeyPairSync("ec", { namedCurve: "prime256v1" });
+  const unsignedHost: Omit<RemoteControlHostHello, "signature"> = {
+    version: REMOTE_CONTROL_PROTOCOL_VERSION,
+    sessionId: validated.sessionId,
+    deviceId: validated.deviceId,
+    capabilities,
+    ephemeralPublicKey: encode(ephemeral.publicKey.export({ format: "der", type: "spki" })),
+    nonce: encode(randomBytes(NONCE_BYTES)),
+  };
+  const hello: RemoteControlHostHello = {
+    ...unsignedHost,
+    signature: encode(sign(null, hostTranscript(transcript, unsignedHost), privateSigningKey(options.devicePrivateKey))),
+  };
+  return {
+    hello,
+    cipher: deriveCipher({
+      sessionId: validated.sessionId,
+      shared: Buffer.from(diffieHellman({
+        privateKey: ephemeral.privateKey,
+        publicKey: publicEphemeralKey(validated.ephemeralPublicKey),
+      })),
+      clientNonce: decode(validated.nonce, "remote control client nonce", NONCE_BYTES),
+      hostNonce: decode(hello.nonce, "remote control host nonce", NONCE_BYTES),
+      role: "host",
+    }),
+  };
+}
diff --git a/src/remote-control/host.ts b/src/remote-control/host.ts
new file mode 100644
index 0000000000..f18166189f
--- /dev/null
+++ b/src/remote-control/host.ts
@@ -0,0 +1,175 @@
+import {
+  acceptRemoteControlClientHello,
+  parseRemoteControlClientHello,
+  serializeRemoteControlHello,
+  type RemoteControlCipher,
+} from "./crypto";
+import {
+  REMOTE_CONTROL_CAPABILITIES,
+  REMOTE_CONTROL_MAX_RELAY_PAYLOAD_BYTES,
+  REMOTE_CONTROL_MAX_SESSIONS_PER_DEVICE,
+  decodeRemoteControlApplicationFrame,
+  encodeRemoteControlApplicationFrame,
+  type RemoteControlApplicationFrame,
+  type RemoteControlCapability,
+  type RemoteControlCommandProfile,
+} from "./protocol";
+
+export interface RemoteControlTerminal {
+  write(value: Uint8Array): void | Promise<void>;
+  resize(columns: number, rows: number): void | Promise<void>;
+  close(): void | Promise<void>;
+}
+
+export interface RemoteControlTerminalFactory {
+  create(options: {
+    commandProfile: RemoteControlCommandProfile;
+    onOutput(value: Uint8Array): void;
+    onExit(code: number): void;
+  }): RemoteControlTerminal | Promise<RemoteControlTerminal>;
+}
+
+interface HostSession {
+  commandProfile: RemoteControlCommandProfile;
+  capabilities: Set<RemoteControlCapability>;
+  cipher: RemoteControlCipher;
+  onCiphertext(value: Uint8Array): void;
+  terminal?: RemoteControlTerminal;
+  queue: Promise<void>;
+  closed: boolean;
+}
+
+export interface RemoteControlHostOptions {
+  deviceId: string;
+  devicePrivateKey: string;
+  accountPublicKey: string;
+  terminalFactory: RemoteControlTerminalFactory;
+  allowedCapabilities?: readonly RemoteControlCapability[];
+  maxSessions?: number;
+}
+
+/**
+ * Local execution boundary for the Paseo-style topology. The relay never owns
+ * this registry or a terminal. A successfully signed hello reserves only a
+ * session; the first authenticated input/resize frame starts the local process.
+ */
+export class RemoteControlHost {
+  private readonly sessions = new Map<string, HostSession>();
+  private readonly allowedCapabilities: readonly RemoteControlCapability[];
+  private readonly maxSessions: number;
+
+  constructor(private readonly options: RemoteControlHostOptions) {
+    this.allowedCapabilities = options.allowedCapabilities ?? REMOTE_CONTROL_CAPABILITIES;
+    this.maxSessions = options.maxSessions ?? REMOTE_CONTROL_MAX_SESSIONS_PER_DEVICE;
+    if (!Number.isSafeInteger(this.maxSessions) || this.maxSessions < 1) {
+      throw new Error("invalid remote control host session limit");
+    }
+  }
+
+  open(sessionId: string, clientHelloPayload: Uint8Array, onCiphertext: (value: Uint8Array) => void): Uint8Array {
+    if (this.sessions.has(sessionId)) throw new Error("remote control host session already exists");
+    if (this.sessions.size >= this.maxSessions) throw new Error("remote control host session limit reached");
+    const clientHello = parseRemoteControlClientHello(clientHelloPayload);
+    const accepted = acceptRemoteControlClientHello(clientHello, {
+      expectedSessionId: sessionId,
+      expectedDeviceId: this.options.deviceId,
+      accountPublicKey: this.options.accountPublicKey,
+      devicePrivateKey: this.options.devicePrivateKey,
+      allowedCapabilities: this.allowedCapabilities,
+    });
+    this.sessions.set(sessionId, {
+      commandProfile: clientHello.commandProfile,
+      capabilities: new Set(accepted.hello.capabilities),
+      cipher: accepted.cipher,
+      onCiphertext,
+      queue: Promise.resolve(),
+      closed: false,
+    });
+    return serializeRemoteControlHello(accepted.hello);
+  }
+
+  receive(sessionId: string, encryptedPayload: Uint8Array): Promise<void> {
+    const session = this.sessions.get(sessionId);
+    if (!session || session.closed) return Promise.reject(new Error("unknown remote control host session"));
+    const run = session.queue
+      .then(() => this.handleAuthenticatedFrame(sessionId, session, encryptedPayload))
+      .catch(async error => {
+        await this.close(sessionId);
+        throw error;
+      });
+    session.queue = run.catch(() => undefined);
+    return run;
+  }
+
+  async close(sessionId: string): Promise<void> {
+    const session = this.sessions.get(sessionId);
+    if (!session) return;
+    this.sessions.delete(sessionId);
+    session.closed = true;
+    session.cipher.destroy();
+    if (session.terminal) await session.terminal.close();
+  }
+
+  private async handleAuthenticatedFrame(
+    sessionId: string,
+    session: HostSession,
+    encryptedPayload: Uint8Array,
+  ): Promise<void> {
+    let frame: RemoteControlApplicationFrame;
+    try {
+      frame = decodeRemoteControlApplicationFrame(session.cipher.decrypt(encryptedPayload));
+    } catch (error) {
+      await this.close(sessionId);
+      throw error;
+    }
+    if (frame.kind !== "input" && frame.kind !== "resize") {
+      await this.close(sessionId);
+      throw new Error("remote control client sent a host-only terminal frame");
+    }
+    const required: RemoteControlCapability = frame.kind === "input" ? "terminal.input" : "terminal.resize";
+    if (!session.capabilities.has(required)) {
+      await this.close(sessionId);
+      throw new Error(`remote control capability ${required} was not granted`);
+    }
+    if (!session.terminal) {
+      const terminal = await this.startTerminal(sessionId, session);
+      if (session.closed) {
+        await terminal.close();
+        throw new Error("remote control host session closed while starting the terminal");
+      }
+      session.terminal = terminal;
+    }
+    if (frame.kind === "input") await session.terminal.write(frame.data);
+    else await session.terminal.resize(frame.columns, frame.rows);
+  }
+
+  private async startTerminal(sessionId: string, session: HostSession): Promise<RemoteControlTerminal> {
+    return await this.options.terminalFactory.create({
+      commandProfile: session.commandProfile,
+      onOutput: value => {
+        if (session.closed || !session.capabilities.has("terminal.output")) return;
+        const maxChunk = REMOTE_CONTROL_MAX_RELAY_PAYLOAD_BYTES - 25;
+        for (let offset = 0; offset < value.byteLength; offset += maxChunk) {
+          this.emitApplicationFrame(sessionId, session, { kind: "output", data: value.subarray(offset, offset + maxChunk) });
+        }
+      },
+      onExit: code => {
+        if (session.closed) return;
+        this.emitApplicationFrame(sessionId, session, { kind: "exit", code });
+        void this.close(sessionId);
+      },
+    });
+  }
+
+  private emitApplicationFrame(
+    sessionId: string,
+    session: HostSession,
+    frame: RemoteControlApplicationFrame,
+  ): void {
+    try {
+      session.onCiphertext(session.cipher.encrypt(encodeRemoteControlApplicationFrame(frame)));
+    } catch {
+      void this.close(sessionId);
+    }
+  }
+}
diff --git a/src/remote-control/index.ts b/src/remote-control/index.ts
new file mode 100644
index 0000000000..256832a324
--- /dev/null
+++ b/src/remote-control/index.ts
@@ -0,0 +1,100 @@
+export {
+  REMOTE_CONTROL_PROTOCOL_VERSION,
+  REMOTE_CONTROL_RELAY_HEADER_BYTES,
+  REMOTE_CONTROL_MAX_RELAY_PAYLOAD_BYTES,
+  REMOTE_CONTROL_MAX_SESSIONS_PER_DEVICE,
+  REMOTE_CONTROL_MAX_BUFFERED_BYTES,
+  REMOTE_CONTROL_COMMAND_PROFILES,
+  REMOTE_CONTROL_CAPABILITIES,
+  isRemoteControlUuid,
+  remoteControlUuidBytes,
+  isRemoteControlCommandProfile,
+  normalizeRemoteControlCapabilities,
+  encodeRemoteControlRelayFrame,
+  decodeRemoteControlRelayFrame,
+  encodeRemoteControlApplicationFrame,
+  decodeRemoteControlApplicationFrame,
+} from "./protocol";
+export type {
+  RemoteControlCommandProfile,
+  RemoteControlCapability,
+  RemoteControlClientHello,
+  RemoteControlHostHello,
+  RemoteControlRelayFrameKind,
+  RemoteControlRelayFrame,
+  RemoteControlApplicationFrame,
+} from "./protocol";
+export {
+  parseRemoteControlClientHello,
+  parseRemoteControlHostHello,
+  serializeRemoteControlHello,
+  generateRemoteControlIdentityKeyPair,
+  RemoteControlCipher,
+  RemoteControlClientHandshake,
+  acceptRemoteControlClientHello,
+} from "./crypto";
+export type {
+  RemoteControlIdentityKeyPair,
+  CreateRemoteControlClientHandshakeOptions,
+  AcceptRemoteControlClientHelloOptions,
+} from "./crypto";
+export {
+  RemoteControlHost,
+} from "./host";
+export type {
+  RemoteControlTerminal,
+  RemoteControlTerminalFactory,
+  RemoteControlHostOptions,
+} from "./host";
+export {
+  OpaqueRemoteControlRelay,
+} from "./relay";
+export type {
+  RemoteControlRelayPeer,
+  OpaqueRemoteControlRelayOptions,
+} from "./relay";
+export {
+  REMOTE_WORKSPACE_TOOL_NAMESPACE,
+  REMOTE_WORKSPACE_MAX_TOOL_RESULT_BYTES,
+  REMOTE_WORKSPACE_CAPABILITIES,
+  REMOTE_WORKSPACE_DYNAMIC_TOOLS,
+  parseRemoteWorkspaceCapabilities,
+  remoteWorkspaceToolsForCapabilities,
+  remoteWorkspaceDynamicToolsForCapabilities,
+  remoteWorkspaceCapabilityForTool,
+  isRemoteWorkspaceCapability,
+  isRemoteWorkspaceToolName,
+  parseRemoteWorkspaceToolCall,
+  remoteWorkspaceDeveloperInstructions,
+  remoteWorkspaceCodexDeveloperInstructions,
+} from "./workspace-tools";
+export type {
+  RemoteWorkspaceCapability,
+  RemoteWorkspaceToolName,
+  RemoteWorkspaceDynamicToolFunction,
+  RemoteWorkspaceDynamicToolNamespace,
+  RemoteWorkspaceToolCallParams,
+  RemoteWorkspaceToolResult,
+} from "./workspace-tools";
+export {
+  REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION,
+  REMOTE_WORKSPACE_AGENT_MAX_CONTROL_BYTES,
+  isRemoteWorkspaceAgentProfile,
+  serializeRemoteWorkspaceHubMessage,
+  serializeRemoteWorkspaceAgentMessage,
+  parseRemoteWorkspaceHubMessage,
+  parseRemoteWorkspaceAgentMessage,
+} from "./workspace-agent-protocol";
+export type {
+  RemoteWorkspaceAgentProfile,
+  RemoteWorkspaceHubMessage,
+  RemoteWorkspaceAgentMessage,
+} from "./workspace-agent-protocol";
+export {
+  REMOTE_WORKSPACE_RPC_MAX_MESSAGE_BYTES,
+  frameRemoteWorkspaceRpcMessage,
+  RemoteWorkspaceRpcReassembler,
+} from "./workspace-rpc-framing";
+export {
+  truncateRemoteWorkspaceUtf8,
+} from "./workspace-utf8";
diff --git a/src/remote-control/protocol.ts b/src/remote-control/protocol.ts
new file mode 100644
index 0000000000..d167b9eeab
--- /dev/null
+++ b/src/remote-control/protocol.ts
@@ -0,0 +1,200 @@
+export const REMOTE_CONTROL_PROTOCOL_VERSION = 1 as const;
+export const REMOTE_CONTROL_RELAY_HEADER_BYTES = 18;
+export const REMOTE_CONTROL_MAX_RELAY_PAYLOAD_BYTES = 64 * 1024;
+export const REMOTE_CONTROL_MAX_SESSIONS_PER_DEVICE = 4;
+export const REMOTE_CONTROL_MAX_BUFFERED_BYTES = 1024 * 1024;
+
+export const REMOTE_CONTROL_COMMAND_PROFILES = ["shell", "codex", "claude", "pi"] as const;
+export type RemoteControlCommandProfile = typeof REMOTE_CONTROL_COMMAND_PROFILES[number];
+
+export const REMOTE_CONTROL_CAPABILITIES = [
+  "terminal.input",
+  "terminal.output",
+  "terminal.resize",
+  "workspace.read",
+  "workspace.write",
+  "workspace.exec",
+] as const;
+export type RemoteControlCapability = typeof REMOTE_CONTROL_CAPABILITIES[number];
+
+export interface RemoteControlClientHello {
+  version: typeof REMOTE_CONTROL_PROTOCOL_VERSION;
+  sessionId: string;
+  deviceId: string;
+  commandProfile: RemoteControlCommandProfile;
+  capabilities: RemoteControlCapability[];
+  ephemeralPublicKey: string;
+  nonce: string;
+  signature: string;
+}
+
+export interface RemoteControlHostHello {
+  version: typeof REMOTE_CONTROL_PROTOCOL_VERSION;
+  sessionId: string;
+  deviceId: string;
+  capabilities: RemoteControlCapability[];
+  ephemeralPublicKey: string;
+  nonce: string;
+  signature: string;
+}
+
+export type RemoteControlRelayFrameKind = "open" | "data" | "close";
+
+export interface RemoteControlRelayFrame {
+  kind: RemoteControlRelayFrameKind;
+  sessionId: string;
+  payload: Uint8Array;
+}
+
+export type RemoteControlApplicationFrame =
+  | { kind: "input"; data: Uint8Array }
+  | { kind: "resize"; columns: number; rows: number }
+  | { kind: "output"; data: Uint8Array }
+  | { kind: "exit"; code: number };
+
+const RELAY_KIND_TO_BYTE: Record<RemoteControlRelayFrameKind, number> = {
+  open: 1,
+  data: 2,
+  close: 3,
+};
+const RELAY_BYTE_TO_KIND = new Map<number, RemoteControlRelayFrameKind>([
+  [1, "open"],
+  [2, "data"],
+  [3, "close"],
+]);
+
+const APPLICATION_KIND_TO_BYTE = {
+  input: 1,
+  resize: 2,
+  output: 3,
+  exit: 4,
+} as const;
+
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export function isRemoteControlUuid(value: unknown): value is string {
+  return typeof value === "string" && UUID_PATTERN.test(value);
+}
+
+export function remoteControlUuidBytes(value: string): Uint8Array {
+  if (!isRemoteControlUuid(value)) throw new Error("invalid remote control UUID");
+  return Uint8Array.from(value.replaceAll("-", "").match(/.{2}/g)!, byte => Number.parseInt(byte, 16));
+}
+
+function remoteControlUuidString(value: Uint8Array): string {
+  if (value.byteLength !== 16) throw new Error("invalid remote control UUID bytes");
+  const hex = Buffer.from(value).toString("hex");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+export function isRemoteControlCommandProfile(value: unknown): value is RemoteControlCommandProfile {
+  return typeof value === "string" && (REMOTE_CONTROL_COMMAND_PROFILES as readonly string[]).includes(value);
+}
+
+export function normalizeRemoteControlCapabilities(value: unknown): RemoteControlCapability[] {
+  if (!Array.isArray(value) || value.length > REMOTE_CONTROL_CAPABILITIES.length) {
+    throw new Error("invalid remote control capabilities");
+  }
+  const allowed = new Set<string>(REMOTE_CONTROL_CAPABILITIES);
+  const result = value.map(capability => {
+    if (typeof capability !== "string" || !allowed.has(capability)) {
+      throw new Error("invalid remote control capability");
+    }
+    return capability as RemoteControlCapability;
+  });
+  if (new Set(result).size !== result.length) throw new Error("duplicate remote control capability");
+  return result.sort();
+}
+
+export function encodeRemoteControlRelayFrame(frame: RemoteControlRelayFrame): Uint8Array {
+  if (!isRemoteControlUuid(frame.sessionId)) throw new Error("invalid relay session ID");
+  if (!(frame.payload instanceof Uint8Array) || frame.payload.byteLength > REMOTE_CONTROL_MAX_RELAY_PAYLOAD_BYTES) {
+    throw new Error("remote control relay payload is too large");
+  }
+  const kind = RELAY_KIND_TO_BYTE[frame.kind];
+  if (!kind) throw new Error("invalid remote control relay frame kind");
+  const result = new Uint8Array(REMOTE_CONTROL_RELAY_HEADER_BYTES + frame.payload.byteLength);
+  result[0] = REMOTE_CONTROL_PROTOCOL_VERSION;
+  result[1] = kind;
+  result.set(remoteControlUuidBytes(frame.sessionId), 2);
+  result.set(frame.payload, REMOTE_CONTROL_RELAY_HEADER_BYTES);
+  return result;
+}
+
+export function decodeRemoteControlRelayFrame(value: Uint8Array): RemoteControlRelayFrame {
+  if (
+    !(value instanceof Uint8Array)
+    || value.byteLength < REMOTE_CONTROL_RELAY_HEADER_BYTES
+    || value.byteLength > REMOTE_CONTROL_RELAY_HEADER_BYTES + REMOTE_CONTROL_MAX_RELAY_PAYLOAD_BYTES
+  ) throw new Error("invalid remote control relay frame length");
+  if (value[0] !== REMOTE_CONTROL_PROTOCOL_VERSION) throw new Error("unsupported remote control relay protocol");
+  const kind = RELAY_BYTE_TO_KIND.get(value[1]!);
+  if (!kind) throw new Error("invalid remote control relay frame kind");
+  return {
+    kind,
+    sessionId: remoteControlUuidString(value.subarray(2, REMOTE_CONTROL_RELAY_HEADER_BYTES)),
+    payload: value.slice(REMOTE_CONTROL_RELAY_HEADER_BYTES),
+  };
+}
+
+function validTerminalDimension(value: number): boolean {
+  return Number.isInteger(value) && value >= 1 && value <= 4096;
+}
+
+export function encodeRemoteControlApplicationFrame(frame: RemoteControlApplicationFrame): Uint8Array {
+  if (frame.kind === "input" || frame.kind === "output") {
+    if (!(frame.data instanceof Uint8Array) || frame.data.byteLength > REMOTE_CONTROL_MAX_RELAY_PAYLOAD_BYTES - 25) {
+      throw new Error("remote control terminal payload is too large");
+    }
+    const result = new Uint8Array(1 + frame.data.byteLength);
+    result[0] = APPLICATION_KIND_TO_BYTE[frame.kind];
+    result.set(frame.data, 1);
+    return result;
+  }
+  if (frame.kind === "resize") {
+    if (!validTerminalDimension(frame.columns) || !validTerminalDimension(frame.rows)) {
+      throw new Error("invalid remote control terminal size");
+    }
+    const result = new Uint8Array(5);
+    result[0] = APPLICATION_KIND_TO_BYTE.resize;
+    const view = new DataView(result.buffer);
+    view.setUint16(1, frame.columns, false);
+    view.setUint16(3, frame.rows, false);
+    return result;
+  }
+  if (!Number.isInteger(frame.code) || frame.code < -0x80000000 || frame.code > 0x7fffffff) {
+    throw new Error("invalid remote control terminal exit code");
+  }
+  const result = new Uint8Array(5);
+  result[0] = APPLICATION_KIND_TO_BYTE.exit;
+  new DataView(result.buffer).setInt32(1, frame.code, false);
+  return result;
+}
+
+export function decodeRemoteControlApplicationFrame(value: Uint8Array): RemoteControlApplicationFrame {
+  if (!(value instanceof Uint8Array) || value.byteLength < 1) throw new Error("empty remote control application frame");
+  if (value[0] === APPLICATION_KIND_TO_BYTE.input || value[0] === APPLICATION_KIND_TO_BYTE.output) {
+    if (value.byteLength > REMOTE_CONTROL_MAX_RELAY_PAYLOAD_BYTES - 24) {
+      throw new Error("remote control terminal payload is too large");
+    }
+    return {
+      kind: value[0] === APPLICATION_KIND_TO_BYTE.input ? "input" : "output",
+      data: value.slice(1),
+    };
+  }
+  if (value[0] === APPLICATION_KIND_TO_BYTE.resize) {
+    if (value.byteLength !== 5) throw new Error("invalid remote control resize frame");
+    const view = new DataView(value.buffer, value.byteOffset, value.byteLength);
+    const columns = view.getUint16(1, false);
+    const rows = view.getUint16(3, false);
+    if (!validTerminalDimension(columns) || !validTerminalDimension(rows)) {
+      throw new Error("invalid remote control terminal size");
+    }
+    return { kind: "resize", columns, rows };
+  }
+  if (value[0] === APPLICATION_KIND_TO_BYTE.exit) {
+    if (value.byteLength !== 5) throw new Error("invalid remote control exit frame");
+    return { kind: "exit", code: new DataView(value.buffer, value.byteOffset, value.byteLength).getInt32(1, false) };
+  }
+  throw new Error("unknown remote control application frame");
+}
diff --git a/src/remote-control/relay.ts b/src/remote-control/relay.ts
new file mode 100644
index 0000000000..0c11ed961d
--- /dev/null
+++ b/src/remote-control/relay.ts
@@ -0,0 +1,162 @@
+import {
+  REMOTE_CONTROL_MAX_BUFFERED_BYTES,
+  REMOTE_CONTROL_MAX_SESSIONS_PER_DEVICE,
+  decodeRemoteControlRelayFrame,
+  encodeRemoteControlRelayFrame,
+  isRemoteControlUuid,
+  type RemoteControlRelayFrameKind,
+} from "./protocol";
+
+export interface RemoteControlRelayPeer {
+  bufferedAmount(): number;
+  send(value: Uint8Array): void;
+  close(code: number, reason: string): void;
+}
+
+interface RelaySession {
+  deviceId: string;
+  client: RemoteControlRelayPeer;
+}
+
+export interface OpaqueRemoteControlRelayOptions {
+  maxBufferedBytes?: number;
+  maxSessionsPerDevice?: number;
+}
+
+/**
+ * Routes bounded envelopes without decoding the handshake or application payload.
+ * Account/session authorization belongs at the HTTP/WebSocket upgrade boundary;
+ * this class begins only after that control-plane decision has succeeded.
+ */
+export class OpaqueRemoteControlRelay {
+  private readonly hosts = new Map<string, RemoteControlRelayPeer>();
+  private readonly sessions = new Map<string, RelaySession>();
+  private readonly maxBufferedBytes: number;
+  private readonly maxSessionsPerDevice: number;
+
+  constructor(options: OpaqueRemoteControlRelayOptions = {}) {
+    this.maxBufferedBytes = options.maxBufferedBytes ?? REMOTE_CONTROL_MAX_BUFFERED_BYTES;
+    this.maxSessionsPerDevice = options.maxSessionsPerDevice ?? REMOTE_CONTROL_MAX_SESSIONS_PER_DEVICE;
+    if (!Number.isSafeInteger(this.maxBufferedBytes) || this.maxBufferedBytes < 1) {
+      throw new Error("invalid remote control relay buffer limit");
+    }
+    if (!Number.isSafeInteger(this.maxSessionsPerDevice) || this.maxSessionsPerDevice < 1) {
+      throw new Error("invalid remote control relay session limit");
+    }
+  }
+
+  registerHost(deviceId: string, host: RemoteControlRelayPeer): () => void {
+    if (!isRemoteControlUuid(deviceId)) throw new Error("invalid remote control device ID");
+    const previous = this.hosts.get(deviceId);
+    if (previous && previous !== host) {
+      previous.close(1012, "remote control host reconnected");
+      this.closeDeviceSessions(deviceId, 1012, "remote control host reconnected");
+    }
+    this.hosts.set(deviceId, host);
+    return () => {
+      if (this.hosts.get(deviceId) !== host) return;
+      this.hosts.delete(deviceId);
+      this.closeDeviceSessions(deviceId, 1013, "remote control host disconnected");
+    };
+  }
+
+  attachClient(options: {
+    sessionId: string;
+    deviceId: string;
+    client: RemoteControlRelayPeer;
+    openPayload: Uint8Array;
+  }): () => void {
+    if (this.sessions.has(options.sessionId)) throw new Error("remote control session is already attached");
+    const host = this.hosts.get(options.deviceId);
+    if (!host) throw new Error("remote control host is offline");
+    const active = [...this.sessions.values()].filter(session => session.deviceId === options.deviceId).length;
+    if (active >= this.maxSessionsPerDevice) throw new Error("remote control device session limit reached");
+    const session: RelaySession = { deviceId: options.deviceId, client: options.client };
+    this.sessions.set(options.sessionId, session);
+    try {
+      this.forward(host, "open", options.sessionId, options.openPayload);
+    } catch (error) {
+      this.sessions.delete(options.sessionId);
+      throw error;
+    }
+    return () => this.detachClient(options.sessionId, options.client);
+  }
+
+  receiveFromClient(sessionId: string, client: RemoteControlRelayPeer, payload: Uint8Array): void {
+    const session = this.sessions.get(sessionId);
+    if (!session || session.client !== client) throw new Error("unknown remote control client session");
+    const host = this.hosts.get(session.deviceId);
+    if (!host) {
+      this.sessions.delete(sessionId);
+      client.close(1013, "remote control host is offline");
+      return;
+    }
+    try {
+      this.forward(host, "data", sessionId, payload);
+    } catch (error) {
+      this.sessions.delete(sessionId);
+      client.close(1013, "remote control host is backpressured");
+      throw error;
+    }
+  }
+
+  receiveFromHost(deviceId: string, host: RemoteControlRelayPeer, encoded: Uint8Array): void {
+    if (this.hosts.get(deviceId) !== host) throw new Error("unknown remote control host");
+    const frame = decodeRemoteControlRelayFrame(encoded);
+    if (frame.kind === "open") throw new Error("remote control host cannot open browser sessions");
+    const session = this.sessions.get(frame.sessionId);
+    if (!session) return;
+    if (session.deviceId !== deviceId) {
+      host.close(1008, "remote control session ownership mismatch");
+      return;
+    }
+    if (frame.kind === "close") {
+      this.sessions.delete(frame.sessionId);
+      session.client.close(1000, "remote control host closed the session");
+      return;
+    }
+    if (session.client.bufferedAmount() > this.maxBufferedBytes) {
+      this.sessions.delete(frame.sessionId);
+      session.client.close(1013, "remote control relay backpressure");
+      this.forward(host, "close", frame.sessionId, new Uint8Array());
+      return;
+    }
+    // Intentionally forward the payload byte-for-byte. Only the endpoints parse it.
+    session.client.send(frame.payload);
+  }
+
+  private detachClient(sessionId: string, client: RemoteControlRelayPeer): void {
+    const session = this.sessions.get(sessionId);
+    if (!session || session.client !== client) return;
+    this.sessions.delete(sessionId);
+    const host = this.hosts.get(session.deviceId);
+    if (host) {
+      try {
+        this.forward(host, "close", sessionId, new Uint8Array());
+      } catch {
+        // The client is already detached; the host transport owns its own close path.
+      }
+    }
+  }
+
+  private closeDeviceSessions(deviceId: string, code: number, reason: string): void {
+    for (const [sessionId, session] of this.sessions) {
+      if (session.deviceId !== deviceId) continue;
+      this.sessions.delete(sessionId);
+      session.client.close(code, reason);
+    }
+  }
+
+  private forward(
+    target: RemoteControlRelayPeer,
+    kind: RemoteControlRelayFrameKind,
+    sessionId: string,
+    payload: Uint8Array,
+  ): void {
+    if (target.bufferedAmount() > this.maxBufferedBytes) {
+      target.close(1013, "remote control relay backpressure");
+      throw new Error("remote control relay target is backpressured");
+    }
+    target.send(encodeRemoteControlRelayFrame({ kind, sessionId, payload }));
+  }
+}
diff --git a/src/remote-control/workspace-agent-protocol.ts b/src/remote-control/workspace-agent-protocol.ts
new file mode 100644
index 0000000000..da82d495b7
--- /dev/null
+++ b/src/remote-control/workspace-agent-protocol.ts
@@ -0,0 +1,246 @@
+import {
+  parseRemoteControlClientHello,
+  parseRemoteControlHostHello,
+  serializeRemoteControlHello,
+} from "./crypto";
+import {
+  isRemoteControlCommandProfile,
+  isRemoteControlUuid,
+  type RemoteControlClientHello,
+  type RemoteControlCommandProfile,
+  type RemoteControlHostHello,
+} from "./protocol";
+import {
+  parseRemoteWorkspaceCapabilities,
+  type RemoteWorkspaceCapability,
+} from "./workspace-tools";
+
+export const REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION = 1 as const;
+export const REMOTE_WORKSPACE_AGENT_MAX_CONTROL_BYTES = 96 * 1024;
+
+export type RemoteWorkspaceAgentProfile = Extract<RemoteControlCommandProfile, "codex" | "claude" | "pi">;
+
+export type RemoteWorkspaceHubMessage =
+  | {
+      version: typeof REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION;
+      type: "presence_ack";
+      capabilities: RemoteWorkspaceCapability[];
+    }
+  | {
+      version: typeof REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION;
+      type: "session_open";
+      rootId: string;
+      clientHello: RemoteControlClientHello;
+    }
+  | {
+      version: typeof REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION;
+      type: "ciphertext";
+      sessionId: string;
+      payload: Uint8Array;
+    }
+  | {
+      version: typeof REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION;
+      type: "session_close";
+      sessionId: string;
+      reason: string;
+    };
+
+export type RemoteWorkspaceAgentMessage =
+  | {
+      version: typeof REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION;
+      type: "presence";
+      capabilities: RemoteWorkspaceCapability[];
+    }
+  | {
+      version: typeof REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION;
+      type: "session_accept";
+      sessionId: string;
+      hostHello: RemoteControlHostHello;
+    }
+  | {
+      version: typeof REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION;
+      type: "session_reject";
+      sessionId: string;
+      reason: string;
+    }
+  | {
+      version: typeof REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION;
+      type: "ciphertext";
+      sessionId: string;
+      payload: Uint8Array;
+    }
+  | {
+      version: typeof REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION;
+      type: "heartbeat";
+      nonce: string;
+    };
+
+function identifier(value: unknown, label: string): string {
+  if (typeof value !== "string" || value.length < 1 || value.length > 256 || /[\x00-\x1f\x7f]/.test(value)) {
+    throw new Error(`invalid remote workspace ${label}`);
+  }
+  return value;
+}
+
+function reason(value: unknown): string {
+  if (typeof value !== "string" || value.length < 1 || value.length > 512 || /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(value)) {
+    throw new Error("invalid remote workspace close reason");
+  }
+  return value;
+}
+
+function exactKeys(value: Record<string, unknown>, keys: readonly string[]): void {
+  if (Object.keys(value).length !== keys.length || keys.some(key => !Object.hasOwn(value, key))) {
+    throw new Error("invalid remote workspace control message fields");
+  }
+}
+
+function encodedHello(value: RemoteControlClientHello | RemoteControlHostHello): string {
+  return Buffer.from(serializeRemoteControlHello(value)).toString("base64url");
+}
+
+function decodedHello(value: unknown, kind: "client"): RemoteControlClientHello;
+function decodedHello(value: unknown, kind: "host"): RemoteControlHostHello;
+function decodedHello(value: unknown, kind: "client" | "host"): RemoteControlClientHello | RemoteControlHostHello {
+  if (typeof value !== "string" || value.length < 1 || value.length > 24 * 1024 || !/^[A-Za-z0-9_-]+$/.test(value)) {
+    throw new Error("invalid remote workspace handshake encoding");
+  }
+  const bytes = Buffer.from(value, "base64url");
+  return kind === "client" ? parseRemoteControlClientHello(bytes) : parseRemoteControlHostHello(bytes);
+}
+
+function payload(value: unknown): Uint8Array {
+  if (typeof value !== "string" || value.length < 1 || value.length > 88 * 1024 || !/^[A-Za-z0-9_-]+$/.test(value)) {
+    throw new Error("invalid remote workspace ciphertext encoding");
+  }
+  const decoded = Buffer.from(value, "base64url");
+  if (decoded.byteLength < 24 || decoded.byteLength > 64 * 1024) {
+    throw new Error("invalid remote workspace ciphertext length");
+  }
+  return decoded;
+}
+
+function parseObject(raw: string | Uint8Array): Record<string, unknown> {
+  const bytes = typeof raw === "string" ? Buffer.from(raw, "utf8") : Buffer.from(raw);
+  if (bytes.byteLength < 1 || bytes.byteLength > REMOTE_WORKSPACE_AGENT_MAX_CONTROL_BYTES) {
+    throw new Error("invalid remote workspace control message length");
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(bytes.toString("utf8"));
+  } catch {
+    throw new Error("invalid remote workspace control message JSON");
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("invalid remote workspace control message");
+  }
+  const value = parsed as Record<string, unknown>;
+  if (value.version !== REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION) {
+    throw new Error("unsupported remote workspace agent protocol");
+  }
+  return value;
+}
+
+export function isRemoteWorkspaceAgentProfile(value: unknown): value is RemoteWorkspaceAgentProfile {
+  return isRemoteControlCommandProfile(value) && value !== "shell";
+}
+
+export function serializeRemoteWorkspaceHubMessage(message: RemoteWorkspaceHubMessage): string {
+  const value: Record<string, unknown> = { ...message };
+  if (message.type === "session_open") value.clientHello = encodedHello(message.clientHello);
+  if (message.type === "ciphertext") value.payload = Buffer.from(message.payload).toString("base64url");
+  const encoded = JSON.stringify(value);
+  if (Buffer.byteLength(encoded, "utf8") > REMOTE_WORKSPACE_AGENT_MAX_CONTROL_BYTES) {
+    throw new Error("remote workspace hub message is too large");
+  }
+  return encoded;
+}
+
+export function serializeRemoteWorkspaceAgentMessage(message: RemoteWorkspaceAgentMessage): string {
+  const value: Record<string, unknown> = { ...message };
+  if (message.type === "session_accept") value.hostHello = encodedHello(message.hostHello);
+  if (message.type === "ciphertext") value.payload = Buffer.from(message.payload).toString("base64url");
+  const encoded = JSON.stringify(value);
+  if (Buffer.byteLength(encoded, "utf8") > REMOTE_WORKSPACE_AGENT_MAX_CONTROL_BYTES) {
+    throw new Error("remote workspace agent message is too large");
+  }
+  return encoded;
+}
+
+export function parseRemoteWorkspaceHubMessage(raw: string | Uint8Array): RemoteWorkspaceHubMessage {
+  const value = parseObject(raw);
+  if (value.type === "presence_ack") {
+    exactKeys(value, ["version", "type", "capabilities"]);
+    return {
+      version: REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION,
+      type: "presence_ack",
+      capabilities: parseRemoteWorkspaceCapabilities(value.capabilities),
+    };
+  }
+  if (value.type === "session_open") {
+    exactKeys(value, ["version", "type", "rootId", "clientHello"]);
+    const clientHello = decodedHello(value.clientHello, "client");
+    if (!isRemoteWorkspaceAgentProfile(clientHello.commandProfile)) {
+      throw new Error("invalid remote workspace session profile");
+    }
+    return {
+      version: REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION,
+      type: "session_open",
+      rootId: identifier(value.rootId, "root ID"),
+      clientHello,
+    };
+  }
+  if (value.type === "ciphertext") {
+    exactKeys(value, ["version", "type", "sessionId", "payload"]);
+    const sessionId = identifier(value.sessionId, "session ID");
+    if (!isRemoteControlUuid(sessionId)) throw new Error("invalid remote workspace session ID");
+    return { version: REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION, type: "ciphertext", sessionId, payload: payload(value.payload) };
+  }
+  if (value.type === "session_close") {
+    exactKeys(value, ["version", "type", "sessionId", "reason"]);
+    const sessionId = identifier(value.sessionId, "session ID");
+    if (!isRemoteControlUuid(sessionId)) throw new Error("invalid remote workspace session ID");
+    return { version: REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION, type: "session_close", sessionId, reason: reason(value.reason) };
+  }
+  throw new Error("unsupported remote workspace hub message");
+}
+
+export function parseRemoteWorkspaceAgentMessage(raw: string | Uint8Array): RemoteWorkspaceAgentMessage {
+  const value = parseObject(raw);
+  if (value.type === "presence") {
+    exactKeys(value, ["version", "type", "capabilities"]);
+    return {
+      version: REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION,
+      type: "presence",
+      capabilities: parseRemoteWorkspaceCapabilities(value.capabilities),
+    };
+  }
+  if (value.type === "session_accept") {
+    exactKeys(value, ["version", "type", "sessionId", "hostHello"]);
+    const sessionId = identifier(value.sessionId, "session ID");
+    if (!isRemoteControlUuid(sessionId)) throw new Error("invalid remote workspace session ID");
+    return {
+      version: REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION,
+      type: "session_accept",
+      sessionId,
+      hostHello: decodedHello(value.hostHello, "host"),
+    };
+  }
+  if (value.type === "session_reject") {
+    exactKeys(value, ["version", "type", "sessionId", "reason"]);
+    const sessionId = identifier(value.sessionId, "session ID");
+    if (!isRemoteControlUuid(sessionId)) throw new Error("invalid remote workspace session ID");
+    return { version: REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION, type: "session_reject", sessionId, reason: reason(value.reason) };
+  }
+  if (value.type === "ciphertext") {
+    exactKeys(value, ["version", "type", "sessionId", "payload"]);
+    const sessionId = identifier(value.sessionId, "session ID");
+    if (!isRemoteControlUuid(sessionId)) throw new Error("invalid remote workspace session ID");
+    return { version: REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION, type: "ciphertext", sessionId, payload: payload(value.payload) };
+  }
+  if (value.type === "heartbeat") {
+    exactKeys(value, ["version", "type", "nonce"]);
+    return { version: REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION, type: "heartbeat", nonce: identifier(value.nonce, "heartbeat nonce") };
+  }
+  throw new Error("unsupported remote workspace agent message");
+}
diff --git a/src/remote-control/workspace-rpc-framing.ts b/src/remote-control/workspace-rpc-framing.ts
new file mode 100644
index 0000000000..3482d005f2
--- /dev/null
+++ b/src/remote-control/workspace-rpc-framing.ts
@@ -0,0 +1,128 @@
+import { randomBytes } from "node:crypto";
+import { REMOTE_CONTROL_MAX_RELAY_PAYLOAD_BYTES } from "./protocol";
+
+const RPC_FRAME_MAGIC = Uint8Array.of(0x4f, 0x43, 0x58, 0x52); // OCXR
+const RPC_FRAME_VERSION = 1;
+const RPC_FRAME_HEADER_BYTES = 30;
+const RPC_FRAME_MESSAGE_ID_BYTES = 16;
+const RPC_FRAME_MESSAGE_ID_OFFSET = 6;
+const RPC_FRAME_TOTAL_BYTES_OFFSET = 22;
+const RPC_FRAME_CHUNK_OFFSET = 26;
+const RPC_ENCRYPTION_OVERHEAD_BYTES = 24;
+const RPC_MAX_PLAINTEXT_FRAME_BYTES = REMOTE_CONTROL_MAX_RELAY_PAYLOAD_BYTES - RPC_ENCRYPTION_OVERHEAD_BYTES;
+const RPC_MAX_CHUNK_BYTES = RPC_MAX_PLAINTEXT_FRAME_BYTES - RPC_FRAME_HEADER_BYTES;
+const RPC_MAX_INCOMPLETE_MESSAGES = 8;
+const RPC_INCOMPLETE_MESSAGE_TTL_MS = 30_000;
+
+// A 256 KiB UTF-8 write can expand by up to 6x when JSON escapes control bytes.
+// Keep the wire contract bounded while still carrying every executor-approved text file.
+export const REMOTE_WORKSPACE_RPC_MAX_MESSAGE_BYTES = 2 * 1024 * 1024;
+
+interface IncompleteMessage {
+  buffer: Uint8Array;
+  nextOffset: number;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+function hasMagic(value: Uint8Array): boolean {
+  return RPC_FRAME_MAGIC.every((byte, index) => value[index] === byte);
+}
+
+function messageKey(frame: Uint8Array): string {
+  return Buffer.from(
+    frame.subarray(RPC_FRAME_MESSAGE_ID_OFFSET, RPC_FRAME_MESSAGE_ID_OFFSET + RPC_FRAME_MESSAGE_ID_BYTES),
+  ).toString("hex");
+}
+
+function writeHeader(frame: Uint8Array, messageId: Uint8Array, totalBytes: number, offset: number): void {
+  frame.set(RPC_FRAME_MAGIC, 0);
+  frame[4] = RPC_FRAME_VERSION;
+  frame[5] = 0;
+  frame.set(messageId, RPC_FRAME_MESSAGE_ID_OFFSET);
+  const view = new DataView(frame.buffer, frame.byteOffset, frame.byteLength);
+  view.setUint32(RPC_FRAME_TOTAL_BYTES_OFFSET, totalBytes);
+  view.setUint32(RPC_FRAME_CHUNK_OFFSET, offset);
+}
+
+/**
+ * Splits one logical RPC message without retaining a second full-size copy.
+ * Each yielded plaintext fits one authenticated relay frame.
+ */
+export function* frameRemoteWorkspaceRpcMessage(message: Uint8Array): Generator<Uint8Array> {
+  if (!(message instanceof Uint8Array)
+    || message.byteLength < 1
+    || message.byteLength > REMOTE_WORKSPACE_RPC_MAX_MESSAGE_BYTES) {
+    throw new Error("invalid remote workspace RPC message length");
+  }
+  const messageId = randomBytes(RPC_FRAME_MESSAGE_ID_BYTES);
+  for (let offset = 0; offset < message.byteLength; offset += RPC_MAX_CHUNK_BYTES) {
+    const end = Math.min(offset + RPC_MAX_CHUNK_BYTES, message.byteLength);
+    const frame = new Uint8Array(RPC_FRAME_HEADER_BYTES + end - offset);
+    writeHeader(frame, messageId, message.byteLength, offset);
+    frame.set(message.subarray(offset, end), RPC_FRAME_HEADER_BYTES);
+    yield frame;
+  }
+}
+
+/** Bounded, ordered reassembly for authenticated RPC fragments. */
+export class RemoteWorkspaceRpcReassembler {
+  private readonly incomplete = new Map<string, IncompleteMessage>();
+
+  accept(frame: Uint8Array): Uint8Array | null {
+    if (!(frame instanceof Uint8Array)
+      || frame.byteLength <= RPC_FRAME_HEADER_BYTES
+      || frame.byteLength > RPC_MAX_PLAINTEXT_FRAME_BYTES
+      || !hasMagic(frame)
+      || frame[4] !== RPC_FRAME_VERSION
+      || frame[5] !== 0) {
+      throw new Error("invalid remote workspace RPC frame");
+    }
+    const view = new DataView(frame.buffer, frame.byteOffset, frame.byteLength);
+    const totalBytes = view.getUint32(RPC_FRAME_TOTAL_BYTES_OFFSET);
+    const offset = view.getUint32(RPC_FRAME_CHUNK_OFFSET);
+    const payload = frame.subarray(RPC_FRAME_HEADER_BYTES);
+    if (totalBytes < 1
+      || totalBytes > REMOTE_WORKSPACE_RPC_MAX_MESSAGE_BYTES
+      || offset >= totalBytes
+      || payload.byteLength > totalBytes - offset
+      || (offset + payload.byteLength < totalBytes && payload.byteLength !== RPC_MAX_CHUNK_BYTES)) {
+      throw new Error("invalid remote workspace RPC fragment bounds");
+    }
+    if (offset === 0 && payload.byteLength === totalBytes) return payload;
+
+    const key = messageKey(frame);
+    let state = this.incomplete.get(key);
+    if (!state) {
+      if (offset !== 0) throw new Error("remote workspace RPC fragment started out of order");
+      if (this.incomplete.size >= RPC_MAX_INCOMPLETE_MESSAGES) {
+        throw new Error("remote workspace RPC fragment limit reached");
+      }
+      const timer = setTimeout(() => this.drop(key), RPC_INCOMPLETE_MESSAGE_TTL_MS);
+      timer.unref?.();
+      state = { buffer: new Uint8Array(totalBytes), nextOffset: 0, timer };
+      this.incomplete.set(key, state);
+    } else if (state.buffer.byteLength !== totalBytes || state.nextOffset !== offset) {
+      this.drop(key);
+      throw new Error("remote workspace RPC fragments are inconsistent or out of order");
+    }
+
+    state.buffer.set(payload, offset);
+    state.nextOffset += payload.byteLength;
+    if (state.nextOffset !== totalBytes) return null;
+    this.incomplete.delete(key);
+    clearTimeout(state.timer);
+    return state.buffer;
+  }
+
+  clear(): void {
+    for (const state of this.incomplete.values()) clearTimeout(state.timer);
+    this.incomplete.clear();
+  }
+
+  private drop(key: string): void {
+    const state = this.incomplete.get(key);
+    if (!state) return;
+    clearTimeout(state.timer);
+    this.incomplete.delete(key);
+  }
+}
diff --git a/src/remote-control/workspace-tools.ts b/src/remote-control/workspace-tools.ts
new file mode 100644
index 0000000000..401428e4c3
--- /dev/null
+++ b/src/remote-control/workspace-tools.ts
@@ -0,0 +1,237 @@
+export const REMOTE_WORKSPACE_TOOL_NAMESPACE = "ocx_remote_workspace" as const;
+export const REMOTE_WORKSPACE_MAX_TOOL_RESULT_BYTES = 256 * 1024;
+
+export const REMOTE_WORKSPACE_CAPABILITIES = [
+  "workspace.read",
+  "workspace.write",
+  "workspace.exec",
+] as const;
+
+export type RemoteWorkspaceCapability = typeof REMOTE_WORKSPACE_CAPABILITIES[number];
+
+export type RemoteWorkspaceToolName =
+  | "list_directory"
+  | "read_file"
+  | "write_file"
+  | "exec";
+
+export interface RemoteWorkspaceDynamicToolFunction {
+  type: "function";
+  name: RemoteWorkspaceToolName;
+  description: string;
+  inputSchema: Record<string, unknown>;
+}
+
+export interface RemoteWorkspaceDynamicToolNamespace {
+  type: "namespace";
+  name: typeof REMOTE_WORKSPACE_TOOL_NAMESPACE;
+  description: string;
+  tools: RemoteWorkspaceDynamicToolFunction[];
+}
+
+export interface RemoteWorkspaceToolCallParams {
+  threadId: string;
+  turnId: string;
+  callId: string;
+  namespace: typeof REMOTE_WORKSPACE_TOOL_NAMESPACE;
+  tool: RemoteWorkspaceToolName;
+  arguments: unknown;
+}
+
+export type RemoteWorkspaceToolResult =
+  | { ok: true; value?: unknown; error?: never }
+  | { ok: false; error: string; value?: never };
+
+const RELATIVE_PATH = {
+  type: "string",
+  minLength: 1,
+  maxLength: 4096,
+  description: "Path relative to the workspace root. Absolute paths and parent traversal are rejected.",
+} as const;
+
+export const REMOTE_WORKSPACE_DYNAMIC_TOOLS: readonly [RemoteWorkspaceDynamicToolNamespace] = [{
+  type: "namespace",
+  name: REMOTE_WORKSPACE_TOOL_NAMESPACE,
+  description: "Operate only on the selected remote OpenCodex executor workspace.",
+  tools: [
+    {
+      type: "function",
+      name: "list_directory",
+      description: "List one directory inside the selected remote workspace.",
+      inputSchema: {
+        type: "object",
+        properties: { path: { ...RELATIVE_PATH, default: "." } },
+        additionalProperties: false,
+      },
+    },
+    {
+      type: "function",
+      name: "read_file",
+      description: "Read a bounded UTF-8 regular file from the selected remote workspace.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          path: RELATIVE_PATH,
+          maxBytes: { type: "integer", minimum: 1, maximum: REMOTE_WORKSPACE_MAX_TOOL_RESULT_BYTES },
+        },
+        required: ["path"],
+        additionalProperties: false,
+      },
+    },
+    {
+      type: "function",
+      name: "write_file",
+      description: "Atomically replace a bounded UTF-8 file in the selected remote workspace.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          path: RELATIVE_PATH,
+          content: { type: "string", maxLength: REMOTE_WORKSPACE_MAX_TOOL_RESULT_BYTES },
+          expectedSha256: {
+            type: ["string", "null"],
+            pattern: "^[0-9a-f]{64}$",
+            description: "Expected current file hash, or null when the file must not already exist.",
+          },
+        },
+        required: ["path", "content", "expectedSha256"],
+        additionalProperties: false,
+      },
+    },
+    {
+      type: "function",
+      name: "exec",
+      description: "Execute an argv vector in a directory inside the selected remote workspace.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          command: {
+            type: "array",
+            minItems: 1,
+            maxItems: 64,
+            items: { type: "string", minLength: 1, maxLength: 4096 },
+          },
+          cwd: { ...RELATIVE_PATH, default: "." },
+          timeoutMs: { type: "integer", minimum: 1, maximum: 60_000 },
+        },
+        required: ["command"],
+        additionalProperties: false,
+      },
+    },
+  ],
+}];
+
+const TOOL_CAPABILITY: Readonly<Record<RemoteWorkspaceToolName, RemoteWorkspaceCapability>> = {
+  list_directory: "workspace.read",
+  read_file: "workspace.read",
+  write_file: "workspace.write",
+  exec: "workspace.exec",
+};
+
+export function parseRemoteWorkspaceCapabilities(
+  value: unknown,
+  fallback: readonly RemoteWorkspaceCapability[] = ["workspace.read", "workspace.write"],
+): RemoteWorkspaceCapability[] {
+  if (value === undefined) return [...fallback];
+  if (!Array.isArray(value) || value.length < 1 || value.length > REMOTE_WORKSPACE_CAPABILITIES.length) {
+    throw new Error("invalid remote workspace capabilities");
+  }
+  const result = new Set<RemoteWorkspaceCapability>();
+  for (const capability of value) {
+    if (!isRemoteWorkspaceCapability(capability)) {
+      throw new Error("invalid remote workspace capability");
+    }
+    result.add(capability);
+  }
+  if (!result.has("workspace.read")) {
+    throw new Error("remote workspace executors must support workspace.read");
+  }
+  return REMOTE_WORKSPACE_CAPABILITIES.filter(capability => result.has(capability));
+}
+
+export function remoteWorkspaceToolsForCapabilities(
+  capabilities: readonly RemoteWorkspaceCapability[],
+): RemoteWorkspaceToolName[] {
+  const allowed = new Set(parseRemoteWorkspaceCapabilities(capabilities));
+  return REMOTE_WORKSPACE_DYNAMIC_TOOLS[0].tools
+    .filter(tool => allowed.has(TOOL_CAPABILITY[tool.name]))
+    .map(tool => tool.name);
+}
+
+export function remoteWorkspaceDynamicToolsForCapabilities(
+  capabilities: readonly RemoteWorkspaceCapability[],
+): readonly [RemoteWorkspaceDynamicToolNamespace] {
+  const names = new Set(remoteWorkspaceToolsForCapabilities(capabilities));
+  return [{
+    ...REMOTE_WORKSPACE_DYNAMIC_TOOLS[0],
+    tools: REMOTE_WORKSPACE_DYNAMIC_TOOLS[0].tools.filter(tool => names.has(tool.name)),
+  }];
+}
+
+export function remoteWorkspaceCapabilityForTool(tool: RemoteWorkspaceToolName): RemoteWorkspaceCapability {
+  return TOOL_CAPABILITY[tool];
+}
+
+const TOOL_NAMES: ReadonlySet<string> = new Set(
+  REMOTE_WORKSPACE_DYNAMIC_TOOLS[0].tools.map(tool => tool.name),
+);
+
+export function isRemoteWorkspaceCapability(value: unknown): value is RemoteWorkspaceCapability {
+  return value === "workspace.read" || value === "workspace.write" || value === "workspace.exec";
+}
+
+export function isRemoteWorkspaceToolName(value: unknown): value is RemoteWorkspaceToolName {
+  return typeof value === "string" && TOOL_NAMES.has(value);
+}
+
+function boundedIdentifier(value: unknown): value is string {
+  return typeof value === "string" && value.length >= 1 && value.length <= 256 && !/[\x00-\x1f\x7f]/.test(value);
+}
+
+export function parseRemoteWorkspaceToolCall(value: unknown): RemoteWorkspaceToolCallParams {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("invalid remote workspace tool call");
+  }
+  const raw = value as Record<string, unknown>;
+  if (
+    !boundedIdentifier(raw.threadId)
+    || !boundedIdentifier(raw.turnId)
+    || !boundedIdentifier(raw.callId)
+    || raw.namespace !== REMOTE_WORKSPACE_TOOL_NAMESPACE
+    || !isRemoteWorkspaceToolName(raw.tool)
+  ) throw new Error("invalid remote workspace tool call identity");
+  return {
+    threadId: raw.threadId,
+    turnId: raw.turnId,
+    callId: raw.callId,
+    namespace: REMOTE_WORKSPACE_TOOL_NAMESPACE,
+    tool: raw.tool,
+    arguments: raw.arguments,
+  };
+}
+
+export function remoteWorkspaceDeveloperInstructions(
+  deviceName: string,
+  tools: readonly RemoteWorkspaceToolName[] = REMOTE_WORKSPACE_DYNAMIC_TOOLS[0].tools.map(tool => tool.name),
+): string {
+  const safeName = deviceName.replace(/[\x00-\x1f\x7f]/g, " ").slice(0, 120) || "remote executor";
+  const allowed = tools.map(tool => `${REMOTE_WORKSPACE_TOOL_NAMESPACE}.${tool}`).join(", ");
+  return [
+    `This thread operates on the OpenCodex remote executor named ${JSON.stringify(safeName)}.`,
+    `Its available remote tools are: ${allowed}. Use no other tool for filesystem or command work.`,
+    "The coordinator filesystem is an empty isolation boundary and is not the user's workspace.",
+    "Never use local shell, local file, or local patch tools for this thread.",
+    "If a remote tool is unavailable, stop and report that the executor is offline; never fall back locally.",
+  ].join(" ");
+}
+
+export function remoteWorkspaceCodexDeveloperInstructions(
+  deviceName: string,
+  tools: readonly RemoteWorkspaceToolName[] = REMOTE_WORKSPACE_DYNAMIC_TOOLS[0].tools.map(tool => tool.name),
+): string {
+  const nestedTools = tools.map(tool => `tools.mcp__${REMOTE_WORKSPACE_TOOL_NAMESPACE}__${tool}`).join(", ");
+  return [
+    remoteWorkspaceDeveloperInstructions(deviceName, tools),
+    `Current Codex versions expose MCP through the functions.exec code-mode tool. Inside it, call only: ${nestedTools}.`,
+    "Do not call exec_command, apply_patch, view_image, browser, apps, plugins, or any other nested helper on the Hub.",
+  ].join(" ");
+}
diff --git a/src/remote-control/workspace-utf8.ts b/src/remote-control/workspace-utf8.ts
new file mode 100644
index 0000000000..d4f22832e5
--- /dev/null
+++ b/src/remote-control/workspace-utf8.ts
@@ -0,0 +1,24 @@
+import { Buffer } from "node:buffer";
+
+export function truncateRemoteWorkspaceUtf8(value: string, maximumBytes: number): string {
+  if (!Number.isSafeInteger(maximumBytes) || maximumBytes < 0) {
+    throw new Error("invalid remote workspace UTF-8 limit");
+  }
+  if (Buffer.byteLength(value, "utf8") <= maximumBytes) return value;
+  let low = 0;
+  let high = Math.min(value.length, maximumBytes);
+  while (low < high) {
+    const middle = Math.ceil((low + high) / 2);
+    if (Buffer.byteLength(value.slice(0, middle), "utf8") <= maximumBytes) low = middle;
+    else high = middle - 1;
+  }
+  if (
+    low > 0
+    && low < value.length
+    && value.charCodeAt(low - 1) >= 0xd800
+    && value.charCodeAt(low - 1) <= 0xdbff
+    && value.charCodeAt(low) >= 0xdc00
+    && value.charCodeAt(low) <= 0xdfff
+  ) low -= 1;
+  return value.slice(0, low);
+}
diff --git a/src/responses/custom-tool-compat.ts b/src/responses/custom-tool-compat.ts
index ce8f9591d1..3577a23256 100644
--- a/src/responses/custom-tool-compat.ts
+++ b/src/responses/custom-tool-compat.ts
@@ -261,6 +261,29 @@ export function rewriteRoutedCustomToolsForUpstream(
   return { body: rewriteForUpstream(body, conversionNames, callIds), names, repairNames };
 }
 
+/**
+ * A delta result has no tool name. Without its call, lowering cannot tell whether it belongs
+ * to a converted function or a native custom tool. Request full replay instead of guessing.
+ */
+export function hasUnmappedRoutedCustomToolOutput(
+  body: unknown,
+  supportsResponsesCustomTools?: boolean,
+): boolean {
+  if (!isPlainObject(body) || !Array.isArray(body.input)) return false;
+  if (collectRoutedCustomToolNames(body, supportsResponsesCustomTools).size === 0) return false;
+  const callIds = new Set<string>();
+  for (const item of body.input) {
+    if (isPlainObject(item)
+      && (item.type === "custom_tool_call" || item.type === "function_call")
+      && typeof item.call_id === "string") callIds.add(item.call_id);
+  }
+  return body.input.some(item => isPlainObject(item)
+    && item.type === "custom_tool_call_output"
+    && typeof item.call_id === "string"
+    && item.call_id.length > 0
+    && !callIds.has(item.call_id));
+}
+
 export function restoreRoutedCustomCalls(
   value: unknown,
   names: ReadonlySet<string>,
diff --git a/src/router.ts b/src/router.ts
index 8528370efb..bd8e9dc690 100644
--- a/src/router.ts
+++ b/src/router.ts
@@ -349,6 +349,7 @@ export function routedProviderConfig(providerName: string, provider: OcxProvider
   const noTemperatureModels = mergeStringArray(registryEntry.noTemperatureModels, provider.noTemperatureModels);
   const noTopPModels = mergeStringArray(registryEntry.noTopPModels, provider.noTopPModels);
   const noPenaltyModels = mergeStringArray(registryEntry.noPenaltyModels, provider.noPenaltyModels);
+  const noJsonSchemaModels = mergeStringArray(registryEntry.noJsonSchemaModels, provider.noJsonSchemaModels);
   const autoToolChoiceOnlyModels = mergeStringArray(registryEntry.autoToolChoiceOnlyModels, provider.autoToolChoiceOnlyModels);
   const preserveReasoningContentModels = mergeStringArray(registryEntry.preserveReasoningContentModels, provider.preserveReasoningContentModels);
   const requiresReasoningPlaceholderModels = mergeStringArray(registryEntry.requiresReasoningPlaceholderModels, provider.requiresReasoningPlaceholderModels);
@@ -376,6 +377,9 @@ export function routedProviderConfig(providerName: string, provider: OcxProvider
     ...(provider.responsesPath === undefined && registryEntry.responsesPath !== undefined
       ? { responsesPath: registryEntry.responsesPath }
       : {}),
+    ...(provider.chatCompletionsPath === undefined && registryEntry.chatCompletionsPath !== undefined
+      ? { chatCompletionsPath: registryEntry.chatCompletionsPath }
+      : {}),
     ...(provider.requiresAdjacentResponsesToolResults === undefined
       && registryEntry.requiresAdjacentResponsesToolResults !== undefined
       ? { requiresAdjacentResponsesToolResults: registryEntry.requiresAdjacentResponsesToolResults }
@@ -473,6 +477,7 @@ export function routedProviderConfig(providerName: string, provider: OcxProvider
     ...(noTemperatureModels ? { noTemperatureModels } : {}),
     ...(noTopPModels ? { noTopPModels } : {}),
     ...(noPenaltyModels ? { noPenaltyModels } : {}),
+    ...(noJsonSchemaModels ? { noJsonSchemaModels } : {}),
     ...(autoToolChoiceOnlyModels ? { autoToolChoiceOnlyModels } : {}),
     ...(preserveReasoningContentModels ? { preserveReasoningContentModels } : {}),
     ...(requiresReasoningPlaceholderModels ? { requiresReasoningPlaceholderModels } : {}),
@@ -681,7 +686,7 @@ function routeModelInternal(
     }
   }
 
-  // 0. Explicit "<provider>/<model>" namespace (e.g. "opencode-go/deepseek-v4-pro").
+  // 0. Explicit "<provider>/<model>" namespace (e.g. "opencode-go/deepseek-v4.1-flash").
   //    Only triggers when the prefix matches a CONFIGURED provider, so genuine
   //    slash-containing model ids (e.g. "anthropic/claude-...") fall through when
   //    no such provider exists.
diff --git a/src/routing/compatibility/behavior.ts b/src/routing/compatibility/behavior.ts
index 2677864454..700eb333bc 100644
--- a/src/routing/compatibility/behavior.ts
+++ b/src/routing/compatibility/behavior.ts
@@ -14,6 +14,8 @@ export function upstreamProtocolForAdapter(adapter: string): string {
     case "openai-chat":
     case "command-code":
     case "cursor":
+    case "devin-cli":
+    case "devin":
     case "azure":
     case "azure-openai":
     case "kiro":
@@ -147,6 +149,7 @@ export function resolveProductionBehaviorValues(
     "wire.adapter": behaviorRow("provider_config", adapter),
     "wire.upstreamProtocol": behaviorRow("provider_config", upstreamProtocol),
     "wire.responsesPath": behaviorRow("provider_config", effective.responsesPath ?? null),
+    "wire.chatCompletionsPath": behaviorRow("provider_config", effective.chatCompletionsPath ?? null),
     "wire.commandCodeVersion": behaviorRow("provider_config", effective.commandCodeVersion ?? null),
     "wire.modelSuffixMode": behaviorRow(
       "provider_config",
diff --git a/src/server/adapter-resolve.ts b/src/server/adapter-resolve.ts
index 8587b3191d..32bec2825b 100644
--- a/src/server/adapter-resolve.ts
+++ b/src/server/adapter-resolve.ts
@@ -48,6 +48,10 @@ export function resolveWireProtocolOverride(
 }
 
 /** Build the provider adapter for a resolved provider config. */
-export function resolveAdapter(providerConfig: OcxProviderConfig, cacheRetention?: "none" | "short" | "long") {
-  return createRegisteredAdapter(providerConfig, { cacheRetention });
+export function resolveAdapter(
+  providerConfig: OcxProviderConfig,
+  cacheRetention?: "none" | "short" | "long",
+  providerId?: string,
+) {
+  return createRegisteredAdapter(providerConfig, { cacheRetention, ...(providerId ? { providerId } : {}) });
 }
diff --git a/src/server/auth-cors.ts b/src/server/auth-cors.ts
index 8b845c8460..4bf99b4f0f 100644
--- a/src/server/auth-cors.ts
+++ b/src/server/auth-cors.ts
@@ -1,4 +1,4 @@
-import { timingSafeEqual } from "node:crypto";
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import { initialModelSelection } from "../providers/initial-model-selection";
 import { extractAccountId } from "../oauth/chatgpt";
 import { formatErrorResponse } from "../bridge";
@@ -353,9 +353,29 @@ function secretEquals(actual: string, expected: string | undefined): boolean {
  */
 export type DataPlaneAdmissionSource = "loopback" | "dedicated" | "bearer" | "x-api-key";
 
+/**
+ * Process-local, salted identity of the admission secret that was actually matched.
+ *
+ * Context-relay ownership is partitioned by this value, so two operators holding different
+ * keys cannot reach each other's sessions even when both resolve to the same upstream
+ * workspace. `source` is deliberately excluded: the same key arriving as a bearer or in the
+ * dedicated header is one principal. Rotating or replacing a secret mints a new principal and
+ * drops continuity, which is the safe direction — a reused key id or a replaced environment
+ * secret must not inherit the previous holder's sessions. Loopback admission carries no caller
+ * identity and mints nothing, so the relay refuses it rather than treating every local process
+ * as one user.
+ */
+const CONTEXT_PRINCIPAL_SALT = randomBytes(32);
+
+function mintContextPrincipal(kind: string, keyId: string, credential: string): string {
+  return createHmac("sha256", CONTEXT_PRINCIPAL_SALT)
+    .update(kind).update("\0").update(keyId).update("\0").update(credential)
+    .digest("hex");
+}
+
 export type DataPlaneAdmission =
-  | { kind: "configured"; keyId: string; source: DataPlaneAdmissionSource }
-  | { kind: "environment"; source: DataPlaneAdmissionSource }
+  | { kind: "configured"; keyId: string; source: DataPlaneAdmissionSource; contextPrincipalId?: string }
+  | { kind: "environment"; source: DataPlaneAdmissionSource; contextPrincipalId?: string }
   | { kind: "loopback"; source: "loopback" };
 
 /**
@@ -374,17 +394,52 @@ export function resolveDataPlaneAdmissionSecret(
 ): DataPlaneAdmission | null {
   const actual = token.trim();
   if (!actual) return null;
-  if (secretEquals(actual, configuredApiAuthToken(config))) return { kind: "environment", source };
+  if (secretEquals(actual, configuredApiAuthToken(config))) {
+    return { kind: "environment", source, contextPrincipalId: mintContextPrincipal("environment", "", actual) };
+  }
   for (const k of config.apiKeys ?? []) {
-    if (secretEquals(actual, k.key)) return { kind: "configured", keyId: k.id, source };
+    if (secretEquals(actual, k.key)) {
+      return { kind: "configured", keyId: k.id, source, contextPrincipalId: mintContextPrincipal("configured", k.id, actual) };
+    }
     const pending = k.pendingRotation;
     if (pending && Date.parse(pending.expiresAt) > Date.now() && secretEquals(actual, pending.key)) {
-      return { kind: "configured", keyId: k.id, source };
+      return { kind: "configured", keyId: k.id, source, contextPrincipalId: mintContextPrincipal("configured", k.id, pending.key) };
     }
   }
   return null;
 }
 
+/** The principal an authenticated admission belongs to, or undefined for loopback. */
+export function contextPrincipalIdOf(admission: DataPlaneAdmission | undefined): string | undefined {
+  return admission && "contextPrincipalId" in admission ? admission.contextPrincipalId : undefined;
+}
+
+/**
+ * The caller principal for a context-relay request, which is a stricter question than admission.
+ *
+ * The default bind is loopback, where admission deliberately never reads a token, so an admitted
+ * request carries no caller identity. History ownership needs one, so the relay asks separately:
+ * a caller that presents a real opencodex API key gets that key’s principal even on loopback,
+ * and a caller that presents none gets nothing and is refused. This adds identity where the caller
+ * volunteered it; it does not admit anyone who was not already admitted, and it does not change
+ * which credential goes upstream.
+ */
+export function resolveContextPrincipal(req: Request, config: OcxConfig, admission: DataPlaneAdmission | undefined): string | undefined {
+  const named = contextPrincipalIdOf(admission);
+  if (named) return named;
+  if (admission?.kind !== "loopback") return undefined;
+  const dedicated = req.headers.get("x-opencodex-api-key")?.trim();
+  const bearer = req.headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
+  const apiKey = req.headers.get("x-api-key")?.trim();
+  for (const [token, source] of [[dedicated, "dedicated"], [bearer, "bearer"], [apiKey, "x-api-key"]] as const) {
+    if (!token) continue;
+    const resolved = resolveDataPlaneAdmissionSecret(token, config, source);
+    const principal = contextPrincipalIdOf(resolved ?? undefined);
+    if (principal) return principal;
+  }
+  return undefined;
+}
+
 /** Whether `token` is a data-plane admission secret. */
 export function isDataPlaneAdmissionSecret(token: string, config: OcxConfig): boolean {
   return resolveDataPlaneAdmissionSecret(token, config) !== null;
@@ -712,6 +767,11 @@ export function providerManagementConfigError(name: unknown, provider: unknown):
     "noStructuredOutputModels",
   );
   if (structuredOutputOptOutError) return `provider ${name} ${structuredOutputOptOutError}`;
+  const jsonSchemaOptOutError = nonBlankStringArrayConfigError(
+    raw.noJsonSchemaModels,
+    "noJsonSchemaModels",
+  );
+  if (jsonSchemaOptOutError) return `provider ${name} ${jsonSchemaOptOutError}`;
   const retainModelsError = nonBlankStringArrayConfigError(raw.retainModels, "retainModels");
   if (retainModelsError) return `provider ${name} ${retainModelsError}`;
   const toolReasoningOptOutError = nonBlankStringArrayConfigError(
@@ -794,6 +854,7 @@ const PROVIDER_CONFIG_FIELD_POLICY = {
   fastWire: "editor",
   baseUrl: "editor",
   responsesPath: "editor",
+  chatCompletionsPath: "editor",
   commandCodeVersion: "editor",
   statelessResponses: "editor",
   requiresAdjacentResponsesToolResults: "editor",
@@ -812,6 +873,8 @@ const PROVIDER_CONFIG_FIELD_POLICY = {
   apiKey: "redacted",
   apiKeyTransport: "editor",
   apiKeyPool: "redacted",
+  // Ordering preference only; it names no key material, so an editor may read and set it.
+  apiKeyPoolStrategy: "editor",
   apiKeySelectionRevision: "runtime",
   _apiKeyAttempt: "runtime",
   defaultModel: "editor",
@@ -855,6 +918,7 @@ const PROVIDER_CONFIG_FIELD_POLICY = {
   supportsOpenAiWebSearchToolFields: "editor",
   xaiResponsesXSearch: "editor",
   xaiResponsesDefaultVersion: "runtime",
+  zaiResponsesDefaultVersion: "runtime",
   supportsResponsesCustomTools: "editor",
   responsesSnapshotRepair: "editor",
   webSearchBridge: "editor",
@@ -866,6 +930,7 @@ const PROVIDER_CONFIG_FIELD_POLICY = {
   noTopPModels: "editor",
   noPenaltyModels: "editor",
   noStructuredOutputModels: "editor",
+  noJsonSchemaModels: "editor",
   omitReasoningEffortWithToolsModels: "editor",
   parallelToolCalls: "editor",
   pinParallelToolCallsFalse: "editor",
diff --git a/src/server/chat-completions.ts b/src/server/chat-completions.ts
index 44409a660c..3234dfed00 100644
--- a/src/server/chat-completions.ts
+++ b/src/server/chat-completions.ts
@@ -260,9 +260,9 @@ async function handleChatCompletionsWithBudget(
     const value = req.headers.get(name);
     if (value) headers.set(name, value);
   }
-  // A noncanonical caller-auth route can use stored main auth only through a sidecar snapshot.
-  // Later shadow/thread rewrites strip primary credentials at the actual Responses boundary.
-  if (!callerAuthorizationRoute || (settledRoute && !isCanonicalOpenAiForwardProvider(settledRoute.provider))) {
+  // Existing primary enrichment stays on non-caller-auth routes. Caller-auth routes defer
+  // optional stored sidecar auth until the final helper plan actually needs it.
+  if (!callerAuthorizationRoute) {
     // This enrichment is optional for routed/non-main providers. If native main
     // is fenced, omit it and let auth-context reject only a final physical-main
     // selection while healthy pool/provider routes continue.
@@ -317,6 +317,8 @@ async function handleChatCompletionsWithBudget(
   };
   const upstream = await handleResponses(internalReq, config, logCtx, {
     openAiSidecarAuth,
+    allowStoredOpenAiSidecarAuth: !!(callerAuthorizationRoute && settledRoute
+      && !isCanonicalOpenAiForwardProvider(settledRoute.provider)),
     nativeCallerAuth,
     callerDirectAuth,
     ...(logIds?.turnAdmissionLease ? { turnAdmissionLease: logIds.turnAdmissionLease } : {}),
diff --git a/src/server/chat-native.ts b/src/server/chat-native.ts
index d08582249e..7f3c97c10e 100644
--- a/src/server/chat-native.ts
+++ b/src/server/chat-native.ts
@@ -33,6 +33,7 @@ import {
 } from "../lib/translator-budget";
 import {
   hasKeyPoolFailover,
+  selectProactiveApiKeyTransport,
   rateLimitRetryDelayMs,
   rateLimitRetryPolicyFor,
   rotateProviderTransportOn429,
@@ -235,6 +236,14 @@ export async function handleNativeChatCompletions(options: HandleNativeChatOptio
     unregisterTurn(upstream);
   };
   const connectMs = config.connectTimeoutMs ?? 200_000;
+  // Native chat is its own entry path -- chat-completions.ts routes here directly and never
+  // through the Responses core -- so the pre-dispatch key preference is applied again here
+  // rather than inherited. Assigned before the adapter binds below, for the same reason it is
+  // assigned before the transport pin in core.ts.
+  // Transport variant: the bare picker answers with the persisted row, which for a built-in
+  // provider carries no adapter id or base URL until routedProviderConfig backfills it.
+  const proactiveKeyProvider = selectProactiveApiKeyTransport(config, route.providerName, route.provider);
+  if (proactiveKeyProvider) route.provider = proactiveKeyProvider;
   let activeProvider: OcxProviderConfig = route.provider;
   let activeAdapter: ProviderAdapter = createOpenAIChatAdapter(activeProvider);
   let activeRequest: AdapterRequest;
diff --git a/src/server/claude-messages.ts b/src/server/claude-messages.ts
index ba4d4999d3..83b6eb5264 100644
--- a/src/server/claude-messages.ts
+++ b/src/server/claude-messages.ts
@@ -30,7 +30,6 @@ import {
 import { clearableDeadline, idleDeadline } from "../lib/abort";
 import { estimateTokens } from "../lib/token-estimate";
 import { NoEligiblePolicyCandidateError, UnknownRoutingPolicyError, routeModel } from "../router";
-import { registryEntryForProviderDestination } from "../providers/registry";
 import { evidenceFromBody } from "../routing/request-evidence";
 import { resolveWireProtocolOverride } from "./adapter-resolve";
 import type { OcxConfig } from "../types";
@@ -38,6 +37,7 @@ import { readJsonRequestBody, resolveInboundBodyLimitBytes } from "./request-dec
 import { addFinalRequestLog, httpStatusForRequestLogTerminal, recordFirstOutput, type RequestLogContext, type RequestLogEntry } from "./request-log";
 import {
   conversationIdFromClaudeMetadata,
+  getOrAllocateRequestSessionLane,
   linkRequestSessionLane,
   normalizeLogConversationId,
   sessionLaneIdFromRequest,
@@ -637,6 +637,12 @@ export async function handleClaudeMessages(
   }
 }
 
+/**
+ * Translate a Claude Messages request, route it through the Responses pipeline,
+ * and translate the reply back. Runs under a translator budget owned by the
+ * caller; Go session affinity is derived here and handed to the final Go
+ * transport out of band rather than through replay headers.
+ */
 async function handleClaudeMessagesWithBudget(
   req: Request,
   config: OcxConfig,
@@ -791,19 +797,13 @@ async function handleClaudeMessagesWithBudget(
   // Native ChatGPT passthrough (openai-responses forward) accepts only Codex-shaped
   // bodies: it 400s on sampling params ("Unsupported parameter: max_output_tokens",
   // verified live 2026-07-11). Strip them for that route; routed providers keep them.
-  let nativeRoute = false;
-  let opencodeGoRoute = false;
   try {
     const route = routeModel(config, internalBody.model as string, evidenceFromBody(internalBody));
-    // Match the fixed key-auth destination before per-model wire overrides, including
-    // renamed Go providers without treating custom or lookalike URLs as Go.
-    opencodeGoRoute = registryEntryForProviderDestination(route.provider)?.id === "opencode-go";
     // Settle the wire once so the sampling decision below reads the effective
     // adapter rather than the provider-wide default (#404).
     route.provider = resolveWireProtocolOverride(route.providerName, route.modelId, route.provider, "anthropic");
     logCtx.routeDecision = route.routeDecision;
     if (route.provider.adapter === "openai-responses") {
-      nativeRoute = true;
       delete internalBody.max_output_tokens;
       delete internalBody.temperature;
       delete internalBody.top_p;
@@ -867,30 +867,23 @@ async function handleClaudeMessagesWithBudget(
       };
     }
   }
-  if (opencodeGoRoute) {
-    const session = req.headers.get("x-opencode-session");
-    if (session) headers.set("x-opencode-session", session);
-  }
-  const hasExplicitGoSession = opencodeGoRoute
-    && (sessionLaneIdFromRequest(headers) !== undefined
-      || normalizeLogConversationId(headers.get("x-opencode-session")) !== undefined);
-  const synthesizeGoSession = opencodeGoRoute && !hasExplicitGoSession
+  // Carry Go identity out of band: a combo's preflight target may differ from its
+  // actual dispatch/fallback target. Never add Go-only identity to replay headers.
+  const claudeNativeSessionId = cacheKeySource === "metadata"
+    && typeof internalBody.prompt_cache_key === "string"
     && isRec(anthropicBody)
-    && conversationIdFromClaudeMetadata(isRec(anthropicBody.metadata) ? anthropicBody.metadata : undefined) !== undefined;
-  // Go can also use the Responses adapter; its eligibility gate must win on both wires.
-  if (opencodeGoRoute ? synthesizeGoSession : nativeRoute) {
-    // ChatGPT-backend prompt-cache affinity rides the session_id HEADER (codex
-    // clients always send their session uuid; devlog 090 follow-up: body-level
-    // prompt_cache_key alone still yielded cached_tokens:0). Claude Code never sends
-    // the header, so synthesize a stable per-session uuid from the same cache key.
-    // Routed Go requests need this lane too for their x-opencode-session affinity —
-    // but ONLY for a real per-session key (metadata.user_id). The system-hash fallback
-    // key is shared across Desktop conversations, and a shared session_id's backend
-    // semantics are unproven (audit 133 R2#3): body prompt_cache_key only there.
-    if (cacheKeySource === "metadata" && (synthesizeGoSession || !headers.has("session_id")) && typeof internalBody.prompt_cache_key === "string") {
-      headers.set("session_id", uuidFromHex(internalBody.prompt_cache_key));
-    }
-  }
+    && conversationIdFromClaudeMetadata(isRec(anthropicBody.metadata) ? anthropicBody.metadata : undefined) !== undefined
+    ? uuidFromHex(internalBody.prompt_cache_key)
+    : undefined;
+  const metadataGoLane = normalizeLogConversationId(claudeNativeSessionId);
+  // Without any valid conversation identity, fall back to the request-scoped lane
+  // allocated on the admitted client request (#4172): stable across retries and
+  // route reconstruction, distinct per request, and never derived from a shared
+  // system-prompt cache key or from a later synthesized native session_id header.
+  const claudeGoSessionLane = sessionLaneIdFromRequest(headers)
+    ?? normalizeLogConversationId(req.headers.get("x-opencode-session"))
+    ?? metadataGoLane
+    ?? getOrAllocateRequestSessionLane(req);
   let internalReq: Request;
   try {
     // The UTF-16 JSON string and the Request's UTF-8 body coexist until dispatch.
@@ -934,6 +927,8 @@ async function handleClaudeMessagesWithBudget(
     // Without this the replay would look native and a Responses-scoped wire default
     // would fire, disagreeing with the pre-flight decision above.
     inboundWire: "anthropic",
+    claudeGoAffinity: { sessionLane: claudeGoSessionLane },
+    claudeNativeSessionId,
     stripClaudeMainAuthForNoncanonicalForward: true,
     ...(trustedClaudeMainAuth ? { trustedClaudeMainAuth } : {}),
     // Claude's internal stored-main enrichment is not an original caller credential.
diff --git a/src/server/context-history.ts b/src/server/context-history.ts
new file mode 100644
index 0000000000..759157a406
--- /dev/null
+++ b/src/server/context-history.ts
@@ -0,0 +1,207 @@
+/** Native history/notes JSON relay. No interpretation of encrypted tool arguments or retries. */
+import { formatErrorResponse } from "../bridge";
+import {
+  CodexAccountCooldownError, CodexAuthContextError, CodexMainProfileDrainingError, CodexDirectAuthenticationError,
+  CodexPoolAuthenticationError, CodexThreadAffinityExpiredError, CodexMainSubstitutionUnavailableError,
+  codexMainProfileDrainingResponse, cooldownErrorResponse,
+  materializeCodexUpstreamAuth, isCodexAuthContextUsable, resolveCodexAuthContext, releaseCodexAuthContextProbeLease,
+} from "../codex/auth-context";
+import { getContextSessionOwner, contextSessionOwnerMatches } from "../codex/context-owner";
+import { contextEndpoint, contextRelayActivated } from "../codex/context-compat";
+import { formatCodexProviderForLog } from "../codex/routing";
+import { listOpenAiForwardSidecarCandidates } from "../providers/openai-sidecar";
+import { clearableDeadline, type ClearableDeadline } from "../lib/abort";
+import { readBoundedResponseBytes } from "../lib/bounded-body";
+import type { AdmissionLease } from "../lib/admission";
+import type { OcxConfig } from "../types";
+import { resolveContextPrincipal, ForwardAdmissionCredentialError, validateForwardAdmissionCredential, type DataPlaneAdmission } from "./auth-cors";
+import { readBoundedJsonRequestBody } from "./request-decompress";
+import { codexLogAccountId, decodeRequestErrorResponse } from "./responses";
+import { codexAccountSelectionForTurn } from "./lifecycle";
+import type { RequestLogContext } from "./request-log";
+
+const PROTOCOL_HEADERS = ["x-openai-encrypted-tool-arguments", "x-openai-tool-output-truncation-policy"];
+const RESPONSE_HEADERS = ["content-type", "retry-after", "x-request-id", "openai-processing-ms", ...PROTOCOL_HEADERS];
+const MAX_RESPONSE_BYTES = 16 * 1024 * 1024;
+const MAX_REQUEST_BYTES = 16 * 1024 * 1024;
+const RELAY_DEADLINE_MS = 35_000;
+
+export function contextSelectionHeaders(headers: Headers, sessionId: string): Headers {
+  const result = new Headers(headers);
+  // Codex history tools carry root session_id in JSON, unlike Responses' HTTP headers.
+  // Root model requests use (session-id=root, thread-id=root); don't fabricate a parent key.
+  if (!result.has("x-codex-parent-thread-id") && !result.has("session-id") && !result.has("thread-id")) {
+    result.set("session-id", sessionId);
+    result.set("thread-id", sessionId);
+  }
+  return result;
+}
+
+/**
+ * One deadline covers the whole operation, starting before the body is read.
+ *
+ * Reading the body and selecting a credential are both waits a caller controls, and this route
+ * holds an admitted turn slot for their duration. A deadline that started at dispatch would let
+ * an unfinished body or a stalled refresh hold that slot with no bound at all.
+ */
+export async function handleContextHistory(
+  req: Request, config: OcxConfig, logCtx: RequestLogContext,
+  endpoint: string, turnAdmissionLease?: AdmissionLease, admission?: DataPlaneAdmission,
+  revalidateAdmission?: () => DataPlaneAdmission | null,
+): Promise<Response> {
+  const deadline = clearableDeadline(RELAY_DEADLINE_MS, req.signal);
+  try {
+    return await relayContextHistory(req, config, logCtx, endpoint, deadline, turnAdmissionLease,
+      admission, revalidateAdmission);
+  } finally {
+    deadline.clear();
+  }
+}
+
+async function relayContextHistory(
+  req: Request, config: OcxConfig, logCtx: RequestLogContext,
+  endpoint: string, deadline: ClearableDeadline,
+  turnAdmissionLease?: AdmissionLease, admission?: DataPlaneAdmission,
+  revalidateAdmission?: () => DataPlaneAdmission | null,
+): Promise<Response> {
+  // The feature is opt-in, and the opt-in has to hold here rather than only where the injected
+  // base URL is rewritten: a caller that can reach the data plane can POST these paths directly.
+  // While it is off the endpoints do not exist, which is also what a disabled route should look
+  // like from outside.
+  if (!contextEndpoint("/v1/" + endpoint) || req.method !== "POST" || !contextRelayActivated()) {
+    return formatErrorResponse(404, "not_found", "Unknown context endpoint");
+  }
+  // Only a trusted listener admission authorizes replacing a proxy bearer with Codex auth.
+  const substituteMainCredential = admission?.source === "bearer";
+  try { if (!substituteMainCredential) validateForwardAdmissionCredential(req.headers, config); }
+  catch (err) {
+    if (err instanceof ForwardAdmissionCredentialError) return formatErrorResponse(401, "authentication_error", err.message);
+    throw err;
+  }
+  // A workspace is not a person and a local socket is not a caller. Ownership is keyed by the
+  // admission secret that was actually matched, so an admission that carries no principal —
+  // loopback — cannot own or reach a session.
+  const principalId = resolveContextPrincipal(req, config, admission);
+  if (!principalId) {
+    return formatErrorResponse(403, "context_principal_required",
+      "Context history requires an opencodex API key on the request; admission alone carries no caller identity");
+  }
+  let body: unknown;
+  try { body = await readBoundedJsonRequestBody(req, MAX_REQUEST_BYTES, undefined, { signal: deadline.signal }); }
+  catch (err) {
+    const cancelled = cancellationResponse(req, deadline);
+    if (cancelled) return cancelled;
+    return decodeRequestErrorResponse(err, "context_history");
+  }
+  const sessionId = (body as {context?: {session_id?: unknown}} | null)?.context?.session_id;
+  if (typeof sessionId !== "string" || !/^[A-Za-z0-9._:-]{1,512}$/.test(sessionId)) {
+    return formatErrorResponse(400, "invalid_request_error", "context.session_id must be a bounded nonempty string");
+  }
+  const candidate = listOpenAiForwardSidecarCandidates(config)[0];
+  if (!candidate) return formatErrorResponse(400, "invalid_request_error", "History and notes require the native ChatGPT forward provider");
+  const rootHeader = req.headers.get("x-codex-parent-thread-id")?.trim() || req.headers.get("session-id")?.trim();
+  if (rootHeader && rootHeader !== sessionId) {
+    return formatErrorResponse(409, "context_account_unavailable", "Context root does not match this request");
+  }
+  const owner = getContextSessionOwner(principalId, sessionId, candidate.provider.baseUrl);
+  if (!owner || owner.ambiguous || (owner.kind === "caller" && substituteMainCredential)) {
+    return formatErrorResponse(409, "context_account_unavailable",
+      "Context account ownership is unavailable; start a new session and preserve needed state before resetting context");
+  }
+  let authContext: Awaited<ReturnType<typeof resolveCodexAuthContext>>;
+  const headers = new Headers(candidate.provider.headers);
+  try {
+    authContext = await resolveCodexAuthContext(contextSelectionHeaders(req.headers, sessionId), config, owner.kind === "stored" ? "pool" : "direct", {
+      // The same deadline bounds credential selection and refresh waits.
+      signal: deadline.signal,
+      // Resolve the proven physical owner as an explicit account. Context operations
+      // never create affinity, rotate on quota, or inspect file-main for a caller owner.
+      modelId: "context_history",
+      ...(owner.kind === "stored" ? { accountId: owner.accountId } : { requestScopedMainCredential: true }),
+      admission,
+      substituteMainCredentialForDirect: substituteMainCredential,
+      beginCodexAccountSelection: codexAccountSelectionForTurn(turnAdmissionLease),
+    });
+    if (authContext.kind !== "main" && authContext.probeLeaseId) {
+      // History traffic must not occupy or settle the model's quota-recovery probe.
+      releaseCodexAuthContextProbeLease(authContext);
+      return formatErrorResponse(503, "upstream_error", "Model quota recovery is pending; retry context operation later");
+    }
+    if (!isCodexAuthContextUsable(authContext, config)) throw new CodexPoolAuthenticationError("Selected Codex account is unavailable");
+    logCtx.provider = formatCodexProviderForLog(candidate.providerName, codexLogAccountId(authContext), config);
+    // Materialization rechecks the current account policy after async selection.
+    // Synthetic lane IDs are local selection metadata, never upstream headers.
+    for (const [key, value] of materializeCodexUpstreamAuth(req.headers, authContext, {
+      config, modelId: "context_history", admission, substituteMainCredential,
+    })) {
+      headers.set(key, value);
+    }
+    // Check the assembled outbound headers, including configured provider headers.
+    validateForwardAdmissionCredential(headers, config);
+    // Recheck actual wire identity after async selection/materialization. A replaced
+    // account slot or login must not receive another physical account's history.
+    const currentOwner = getContextSessionOwner(principalId, sessionId, candidate.provider.baseUrl);
+    if (!currentOwner || currentOwner.kind !== owner.kind
+      || !contextSessionOwnerMatches(owner, headers) || !contextSessionOwnerMatches(currentOwner, headers)) {
+      return formatErrorResponse(409, "context_account_unavailable", "Context account identity changed; start a new session");
+    }
+  } catch (err) {
+    const cancelled = cancellationResponse(req, deadline);
+    if (cancelled) return cancelled;
+    if (err instanceof CodexAccountCooldownError) return cooldownErrorResponse(err);
+    if (err instanceof CodexMainProfileDrainingError) return codexMainProfileDrainingResponse();
+    if (err instanceof CodexThreadAffinityExpiredError) return formatErrorResponse(409, "invalid_request_error", "Codex thread account affinity expired; start a new session");
+    if (err instanceof CodexAuthContextError || err instanceof CodexPoolAuthenticationError || err instanceof CodexDirectAuthenticationError
+      || err instanceof CodexMainSubstitutionUnavailableError || err instanceof ForwardAdmissionCredentialError) {
+      return formatErrorResponse(401, "authentication_error", "Selected Codex account is unavailable or needs reauthentication");
+    }
+    throw err;
+  }
+  headers.set("content-type", "application/json");
+  for (const key of PROTOCOL_HEADERS) {
+    const value = req.headers.get(key); if (value !== null) headers.set(key, value);
+  }
+  // Nothing is dispatched after cancellation; a notes write is not replayable.
+  const cancelledBeforeDispatch = cancellationResponse(req, deadline);
+  if (cancelledBeforeDispatch) return cancelledBeforeDispatch;
+  // Body reading and credential selection are both waits, and a key can be revoked, rotated or
+  // replaced during them. Re-resolve admission against the receiving listener policy and require
+  // the same principal, so a withdrawn key cannot dispatch on a snapshot taken minutes earlier.
+  if (revalidateAdmission && resolveContextPrincipal(req, config, revalidateAdmission() ?? undefined) !== principalId) {
+    return formatErrorResponse(401, "authentication_error",
+      "opencodex API key changed during this request; retry with current credentials");
+  }
+  // The operator may disable the feature while body or credential IO is pending.
+  if (!contextRelayActivated()) return formatErrorResponse(404, "not_found", "Unknown context endpoint");
+  let response: Response | undefined;
+  try {
+    response = await fetch(`${candidate.provider.baseUrl}/${endpoint}`, {
+      method: "POST", headers, body: JSON.stringify(body), signal: deadline.signal, redirect: "manual",
+    });
+    const result = await readBoundedResponseBytes(response, {maxBytes: MAX_RESPONSE_BYTES, signal: deadline.signal});
+    if (result.oversized) return formatErrorResponse(502, "upstream_error", "Context response exceeded 16 MiB");
+    const outputHeaders = new Headers();
+    for (const key of RESPONSE_HEADERS) {
+      const value = response.headers.get(key); if (value !== null) outputHeaders.set(key, value);
+    }
+    // A context 403 is not evidence that the model credential is invalid. Don't mutate pool
+    // health/quota or retry writes; preserve the real upstream result for the caller.
+    return new Response([204,205,304].includes(response.status) ? null : result.bytes, {status:response.status, headers:outputHeaders});
+  } catch {
+    return cancellationResponse(req, deadline)
+      ?? formatErrorResponse(502, "upstream_error", "Context upstream connection failed");
+  } finally {
+    if (response?.body && !response.body.locked) void response.body.cancel().catch(() => undefined);
+  }
+}
+
+/** Client cancellation and deadline expiry are different outcomes and must not share a status. */
+function cancellationResponse(req: Request, deadline: ClearableDeadline): Response | undefined {
+  if (req.signal.aborted) {
+    return formatErrorResponse(499, "client_closed_request", "Context request canceled by client");
+  }
+  if (deadline.didExpire()) {
+    return formatErrorResponse(504, "upstream_error", "Context operation exceeded its deadline");
+  }
+  return undefined;
+}
diff --git a/src/server/images.ts b/src/server/images.ts
index 5642038474..25ff02f3d4 100644
--- a/src/server/images.ts
+++ b/src/server/images.ts
@@ -28,6 +28,7 @@ import { readBoundedResponseBytes, type BoundedBytesResult } from "../lib/bounde
 import { sidecarEnter } from "../lib/sidecar-tracker";
 import type { OcxConfig } from "../types";
 import { resolveFirstUsableOpenAiSidecar, selectImagesProvider } from "../providers/openai-sidecar";
+import { selectProactiveApiKeyTransport } from "../providers/key-failover";
 import { getProviderRegistryEntry } from "../providers/registry";
 import { readJsonRequestBody, resolveInboundBodyLimitBytes } from "./request-decompress";
 import { ForwardAdmissionCredentialError, validateForwardAdmissionCredential } from "./auth-cors";
@@ -698,7 +699,33 @@ export async function handleImages(
     // Do not hide a broken/expired pool behind separately billed API-key image generation.
     return forwardAuthError;
   } else if (candidates.keyed) {
-    const { provider, apiKey, providerName } = candidates.keyed;
+    const { providerName } = candidates.keyed;
+    // The keyed image path builds its own URL and Authorization header and never enters
+    // handleResponses, so the pre-dispatch key pick happens here.
+    //
+    // Two things about the placement. It stays INSIDE this branch because higher up it would
+    // also run for requests ChatGPT forward goes on to serve, spending a rotation on a path
+    // that never used the key. And the header is rebuilt from the returned route rather than
+    // from candidates.keyed.apiKey, which is a snapshot resolved earlier: reusing it would
+    // send the OLD key while the picker had already persisted the new one.
+    //
+    // Transport variant: this branch reads `provider.baseUrl` and `provider.headers` to build
+    // the URL and the request, and it comes back with the credential already resolved.
+    const warmKeyProvider = selectProactiveApiKeyTransport(config, providerName, candidates.keyed.provider);
+    const provider = warmKeyProvider ?? candidates.keyed.provider;
+    // No fall back to the earlier snapshot once a pick has happened. The picker COMMITS its
+    // choice before returning, so if the chosen reference will not resolve -- revoked keychain
+    // entry, unset env var -- sending the previous key would authenticate a non-idempotent
+    // POST with a credential the config no longer considers active, and the previous key is
+    // the one that was cooling. Fail loudly instead.
+    if (warmKeyProvider && !warmKeyProvider.apiKey?.trim()) {
+      return formatErrorResponse(
+        500,
+        "configuration_error",
+        `image generation selected an API key for "${providerName}" that cannot be resolved`,
+      );
+    }
+    const apiKey = warmKeyProvider?.apiKey ?? candidates.keyed.apiKey;
     if (provider.headers) Object.assign(headers, provider.headers);
     headers["authorization"] = `Bearer ${apiKey}`;
     logCtx.provider = providerName;
diff --git a/src/server/index.ts b/src/server/index.ts
index e1aa2be2bd..3e458a3fea 100644
--- a/src/server/index.ts
+++ b/src/server/index.ts
@@ -24,6 +24,7 @@ import { grokDefaultReasoningEffort } from "../grok/effort";
 import { flushConfigDirHardening } from "../config/paths";
 import { migrateStartupSubagentModels } from "./subagent-models-startup";
 import { migrateStartupXaiResponses } from "./xai-responses-startup";
+import { migrateStartupZaiResponses } from "./zai-responses-startup";
 import { reconcileOAuthProviders } from "../oauth";
 import { withCatalogWriteSerialization } from "../codex/catalog-write-serialization";
 import { invalidateCodexModelsCacheWithPermit } from "../codex/catalog/sync";
@@ -192,6 +193,7 @@ import { anthropicErrorResponse } from "../claude/outbound";
 import { buildDesktop3pRegistry, generateDesktop3pModels } from "../claude/desktop-3p";
 import { buildDesktopDiscoveryInputs } from "../claude/desktop-discovery-inputs";
 import { runClaudeAuthModeMigration } from "../claude/auth-mode-migration";
+import { runRetiredCodexModelMigration } from "../codex/retired-model-migration";
 import {
   bindNativeMainStartupLifecycle,
   blockNativeMainStartupForUnownedServiceHome,
@@ -203,6 +205,8 @@ import {
 import { handleImages } from "./images";
 import { handleLive, logLiveSidebandFrame, parseLiveSidebandTarget, resolveLiveSidebandUpgrade } from "./live";
 import { handleSearch } from "./search";
+import { handleContextHistory } from "./context-history";
+import { codexCompatibleUrl, contextEndpoint, contextRelayActivated } from "../codex/context-compat";
 import { fetchAllModels, handleManagementAPI, VERSION, type ManagementApiDeps } from "./management-api";
 import {
   createManagementSessionControl,
@@ -666,7 +670,7 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
   // Reconcile disk-backed presets first: it replaces provider rows and must not undo
   // an in-memory wire upgrade when that upgrade's persistence is temporarily unavailable.
   reconcileOAuthProviders(startupConfig);
-  const config = migrateStartupXaiResponses(startupConfig);
+  const config = migrateStartupZaiResponses(migrateStartupXaiResponses(startupConfig));
   warnAgentTaskRecoveryStartup(config);
   setLiveStateStoreConfig(config);
   applyProxyEnv(config);
@@ -682,24 +686,11 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
   // indistinguishable from "never chose". Pin those to subscription once so an upgrade
   // never silently moves a deliberate subscriber onto proxy.
   if (runClaudeAuthModeMigration(config)) saveConfig(config);
-  // Sidecar model migration (KST 2026-07-10 06:00 = UTC 2026-07-09 21:00): auto-migrate the old
-  // gpt-5.4-mini default to gpt-5.6-luna for both search and vision sidecars. Only touches configs
-  // still on the old default — explicit user choices are preserved.
-  {
-    const SIDECAR_MIGRATION_CUTOFF = Date.UTC(2026, 6, 9, 21, 0); // July 9 21:00 UTC = KST July 10 06:00
-    if (Date.now() >= SIDECAR_MIGRATION_CUTOFF) {
-      let migrated = false;
-      if (config.webSearchSidecar?.model === "gpt-5.4-mini") {
-        config.webSearchSidecar = { ...config.webSearchSidecar, model: "gpt-5.6-luna" };
-        migrated = true;
-      }
-      if (config.visionSidecar?.model === "gpt-5.4-mini") {
-        config.visionSidecar = { ...config.visionSidecar, model: "gpt-5.6-luna" };
-        migrated = true;
-      }
-      if (migrated) saveConfig(config);
-    }
-  }
+  // Retired Codex-login models: a stored gpt-5.4-mini is a guaranteed 404 for the search and
+  // vision sidecars and for pool warmup, so it moves to gpt-5.6-luna. Extracted so the rule is
+  // testable on its own; see src/codex/retired-model-migration.ts for why exact equality also
+  // rewrites an explicit choice.
+  if (runRetiredCodexModelMigration(config)) saveConfig(config);
   // Resolve unattended service-home authority before any Codex lock, cache, owner,
   // journal, or credential path. Both positive foreign evidence and an unprovable
   // ownership state are non-authority.
@@ -856,6 +847,7 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
     if (path === "/v1/messages" || path === "/v1/chat/completions") return req.method === "POST";
     if (path === "/v1/messages/count_tokens") return req.method === "POST";
     if (path === "/v1/alpha/search") return req.method === "POST";
+    if (contextEndpoint(path)) return req.method === "POST";
     if (path === "/v1/images/generations" || path === "/v1/images/edits") {
       return req.method === "POST";
     }
@@ -1102,7 +1094,7 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
       // The unauthenticated loopback listener (#1102) serves a fixed allowlist and nothing
       // else. Rejecting here, before any handler runs, is what keeps the surface from growing
       // silently when a route is added below.
-      if (ingress === "unauthenticated-loopback" && !loopbackRouteAllowed(new URL(req.url), req)) {
+      if (ingress === "unauthenticated-loopback" && !loopbackRouteAllowed(codexCompatibleUrl(req.url), req)) {
         return withCors(
           formatErrorResponse(404, "not_found", `Unknown endpoint: ${req.method} ${new URL(req.url).pathname}`),
           req,
@@ -1111,7 +1103,7 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
       }
       // Tailscale Serve terminates only on this separately bound loopback socket. Reject before
       // dispatch so no data, readiness, health, WebSocket, or unknown-static handler can run.
-      if (ingress === "hub-management" && !managementIngressRouteAllowed(new URL(req.url), req)) {
+      if (ingress === "hub-management" && !managementIngressRouteAllowed(codexCompatibleUrl(req.url), req)) {
         return withCors(
           formatErrorResponse(404, "not_found", `Unknown endpoint: ${req.method} ${new URL(req.url).pathname}`),
           req,
@@ -1124,7 +1116,7 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
       // same code path a plain loopback bind has always taken — Host-header check included.
       // Routing, provider selection and response bodies keep using `config`.
       const policy: RequestPolicyView = ingress === "unauthenticated-loopback" ? loopbackPolicy() : config;
-      const url = new URL(req.url);
+      const url = codexCompatibleUrl(req.url);
       markActivity(`${req.method} ${url.pathname}`);
 
       // Readiness is exact-GET on the literal /readyz path. Compare the DECODED
@@ -1966,6 +1958,34 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
         }), req, policy);
       }
 
+      if (contextEndpoint(url.pathname) !== undefined && req.method === "POST" && contextRelayActivated()) {
+        // No timeout disable here. The relay is a bounded JSON round trip that owns one deadline
+        // from entry; removing the idle timeout first would let an unfinished body hold an
+        // admitted turn slot indefinitely, before that deadline ever starts.
+        if (isDraining()) {
+          return drainingResponse(req, policy);
+        }
+        const admission = resolveApiAuth(req, policy);
+        if (!admission) return withCors(formatErrorResponse(401, "authentication_error", "opencodex API key required"), req, policy);
+        if (!isAllowedRequestOrigin(req, policy)) {
+          return withCors(formatErrorResponse(403, "origin_rejected", "cross-origin data-plane request blocked"), req, policy);
+        }
+        const start = Date.now();
+        const requestId = nextRequestLogId(start);
+        const logCtx: RequestLogContext = {
+          model: "context_history",
+          provider: "unknown",
+          ...admissionFields(admission),
+        };
+        return runAdmittedHttpTurn(req, policy, async turnAdmissionLease => {
+          const response = await handleContextHistory(req, config, logCtx, contextEndpoint(url.pathname)!,
+            turnAdmissionLease, admission, () => resolveApiAuth(req, policy));
+          addFinalRequestLog(requestId, start, logCtx, response.status,
+            response.status === 499 ? { closeReason: "client_cancel" } : undefined);
+          return withCors(response, req, policy);
+        });
+      }
+
       if (url.pathname === "/v1/alpha/search" && req.method === "POST") {
         disableResponsesRequestTimeout(req, requestServer);
         if (isDraining()) {
diff --git a/src/server/live.ts b/src/server/live.ts
index 6d983ce0aa..eab37d6bda 100644
--- a/src/server/live.ts
+++ b/src/server/live.ts
@@ -1,3 +1,4 @@
+import { codexCompatibleUrl } from "../codex/context-compat";
 /**
  * /v1/live and /v1/realtime/calls relay (issue #371).
  *
@@ -635,7 +636,7 @@ export async function handleLive(
     // Frameless API-shape call-create posts to `{base}/live` without the AVAS
     // query (openai/codex RealtimeCallClient, realtime_call.rs); only the
     // realtime/calls inbound shape keeps the legacy keyed AVAS endpoint.
-    url = new URL(req.url).pathname === "/v1/live"
+    url = codexCompatibleUrl(req.url).pathname === "/v1/live"
       ? forwardLiveUrl(relay.providerBaseUrl, /* usesBackendShape */ false)
       : keyedLiveUrl(relay.providerBaseUrl);
   }
diff --git a/src/server/management-api.ts b/src/server/management-api.ts
index 9cf9b424f2..19b6aeec25 100644
--- a/src/server/management-api.ts
+++ b/src/server/management-api.ts
@@ -143,6 +143,12 @@ async function handleQuotaResetRoutesOnDemand(ctx: ManagementContext): Promise<R
   return handleQuotaResetRoutes(ctx);
 }
 
+async function handleGrokCouponRoutesOnDemand(ctx: ManagementContext): Promise<Response | null> {
+  if (!pathInManagementNamespace(ctx.url.pathname, "/api/grok/reset-coupons", true)) return null;
+  const { handleGrokCouponRoutes } = await import("./management/grok-coupon-routes");
+  return handleGrokCouponRoutes(ctx);
+}
+
 export async function handleManagementAPI(
   req: Request,
   url: URL,
@@ -241,6 +247,7 @@ export async function handleManagementAPI(
     ??     (await handleLogsUsageRoutes(ctx))
     ??     (await handleRequestHistoryRoutes(ctx))
     ??     (await handleQuotaResetRoutesOnDemand(ctx))
+    ??     (await handleGrokCouponRoutesOnDemand(ctx))
     ??     (await handleRoutingAnalyticsRoutes(ctx))
     ??     (await handleRoutingProfileRoutesOnDemand(ctx))
     ??     (await handleProviderRoutes(ctx))
diff --git a/src/server/management/agent-settings-routes.ts b/src/server/management/agent-settings-routes.ts
index d7617c5884..d9757d5b11 100644
--- a/src/server/management/agent-settings-routes.ts
+++ b/src/server/management/agent-settings-routes.ts
@@ -948,10 +948,16 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       const { parseDesktopProfile, reconcileDesktopProfile } = await import("../../claude/desktop-profile");
       const parsed = parseDesktopProfile(body.profile);
       const current = await buildClaudeDesktopState(config);
+      const availableRoutes = new Set(current.models.filter(item => item.available).map(item => item.route));
+      for (const route of Object.keys(parsed.assignments)) {
+        if (!current.profile.assignments[route] && !availableRoutes.has(route)) {
+          throw new Error(`현재 사용할 수 없는 모델은 추가할 수 없습니다: ${route}`);
+        }
+      }
       for (const model of current.models.filter(item => !item.available)) {
         const before = current.profile.assignments[model.route];
         const after = parsed.assignments[model.route];
-        if (JSON.stringify(before) !== JSON.stringify(after)) {
+        if (after !== undefined && JSON.stringify(before) !== JSON.stringify(after)) {
           throw new Error(`현재 사용할 수 없는 모델은 옮길 수 없습니다: ${model.route}`);
         }
       }
diff --git a/src/server/management/config-routes.ts b/src/server/management/config-routes.ts
index 1faa056c8d..0390ea8d76 100644
--- a/src/server/management/config-routes.ts
+++ b/src/server/management/config-routes.ts
@@ -237,7 +237,7 @@ export async function syncEnabledClientIntegrations(
     },
     config,
     port,
-  }, ["mcode", "pi", "aside", "raycast"]));
+  }, ["mcode", "pi", "aside", "raycast", "omo", "cline"]));
 
   return out;
 }
@@ -820,8 +820,8 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
     if (body.vision && (body.vision.model !== undefined || body.vision.reasoning !== undefined)) {
       visionReasoningTouched = true;
       const model = typeof body.vision.model === "string"
-        ? (body.vision.model === "" ? "gpt-5.4-mini" : body.vision.model)
-        : (config.visionSidecar?.model || "gpt-5.4-mini");
+        ? (body.vision.model === "" ? "gpt-5.6-luna" : body.vision.model)
+        : (config.visionSidecar?.model || "gpt-5.6-luna");
       const sourceReasoning = body.vision.reasoning ?? config.visionSidecar?.reasoning;
       normalizedVisionReasoning = sourceReasoning === undefined
         ? undefined
diff --git a/src/server/management/grok-coupon-routes.ts b/src/server/management/grok-coupon-routes.ts
new file mode 100644
index 0000000000..ee75d7bbd6
--- /dev/null
+++ b/src/server/management/grok-coupon-routes.ts
@@ -0,0 +1,287 @@
+/**
+ * Management API handlers for Grok quota reset coupons.
+ *
+ * Exposes inspection and consumption of Grok billing reset coupons via gRPC-Web
+ * to Grok ConsumerUiSvc upstream endpoints.
+ *
+ * Inherits management authentication from requireManagementAuth in management-api.ts.
+ * Lazy-loaded by handleGrokCouponRoutesOnDemand to keep startup fast and honor the
+ * core-lab boundary contract.
+ */
+
+import { jsonResponse } from "../auth-cors";
+import type { ManagementContext } from "./context";
+import { isCodexResetCreditOperationId } from "../../codex/reset-credit-recovery";
+import { getValidAccessSnapshotForAccount } from "../../oauth";
+import { listAccounts, captureOAuthAccountSelection } from "../../oauth/store";
+import {
+  getGrokRemainingResets,
+  redeemGrokResetCoupon,
+  type GrokResetCoupon,
+} from "../../grok/reset-coupons";
+import {
+  openGrokResetCouponOperation,
+  recordGrokResetCouponSettlement,
+  type GrokResetCouponOperationRecord,
+} from "../../grok/reset-coupon-ledger";
+
+export interface GrokResetCouponsResponse {
+  accountId: string;
+  tokens: Array<{
+    tokenId: string;
+    validityStart: string;
+    validityEnd: string;
+  }>;
+  remaining: number;
+}
+
+export interface GrokConsumeCouponRequestBody {
+  accountId?: string;
+  tokenId?: string;
+  operationId?: string;
+}
+
+function resolveTargetAccountId(requestedAccountId?: string): string {
+  if (requestedAccountId && requestedAccountId.trim() !== "") {
+    return requestedAccountId.trim();
+  }
+  const selection = captureOAuthAccountSelection("xai");
+  if (selection?.accountId) {
+    return selection.accountId;
+  }
+  const accounts = listAccounts("xai");
+  if (accounts.length > 0) {
+    return accounts[0].id;
+  }
+  throw new Error("No xAI account found or active");
+}
+
+export async function handleGrokCouponRoutes(ctx: ManagementContext): Promise<Response | null> {
+  const { url, req, config } = ctx;
+  const { pathname } = url;
+
+  if (pathname === "/api/grok/reset-coupons") {
+    if (req.method !== "GET") {
+      return jsonResponse({ error: "Method not allowed" }, 405, req, config);
+    }
+
+    const queryAccountId = url.searchParams.get("accountId") ?? undefined;
+    let accountId: string;
+    try {
+      accountId = resolveTargetAccountId(queryAccountId);
+    } catch (err) {
+      return jsonResponse(
+        { error: { code: "no_account", message: err instanceof Error ? err.message : String(err) } },
+        400,
+        req,
+        config,
+      );
+    }
+
+    let tokenSnapshot;
+    try {
+      tokenSnapshot = await getValidAccessSnapshotForAccount("xai", accountId, { requireUsableAccount: true });
+    } catch (err) {
+      return jsonResponse(
+        { error: { code: "auth_failed", message: "Failed to resolve valid xAI credentials for account" } },
+        401,
+        req,
+        config,
+      );
+    }
+
+    try {
+      const remainingResult = await getGrokRemainingResets({
+        accessToken: tokenSnapshot.accessToken,
+      });
+
+      const payload: GrokResetCouponsResponse = {
+        accountId,
+        tokens: remainingResult.tokens.map((t) => ({
+          tokenId: t.tokenId,
+          validityStart: t.validityStart,
+          validityEnd: t.validityEnd,
+        })),
+        remaining: remainingResult.tokens.length,
+      };
+
+      return jsonResponse(payload, 200, req, config);
+    } catch (err) {
+      return jsonResponse(
+        { error: { code: "upstream_error", message: err instanceof Error ? err.message : String(err) } },
+        502,
+        req,
+        config,
+      );
+    }
+  }
+
+  if (pathname === "/api/grok/reset-coupons/consume") {
+    if (req.method !== "POST") {
+      return jsonResponse({ error: "Method not allowed" }, 405, req, config);
+    }
+
+    let body: GrokConsumeCouponRequestBody;
+    try {
+      body = (await req.json()) as GrokConsumeCouponRequestBody;
+    } catch {
+      return jsonResponse({ error: { code: "invalid_json", message: "Invalid JSON body" } }, 400, req, config);
+    }
+
+    const { accountId: rawAccountId, tokenId: requestedTokenId, operationId } = body;
+
+    if (operationId !== undefined && !isCodexResetCreditOperationId(operationId)) {
+      return jsonResponse(
+        { error: { code: "invalid_operation_id", message: "operationId must be a valid UUIDv4" } },
+        400,
+        req,
+        config,
+      );
+    }
+
+    let accountId: string;
+    try {
+      accountId = resolveTargetAccountId(rawAccountId);
+    } catch (err) {
+      return jsonResponse(
+        { error: { code: "no_account", message: err instanceof Error ? err.message : String(err) } },
+        400,
+        req,
+        config,
+      );
+    }
+
+    let tokenSnapshot;
+    try {
+      tokenSnapshot = await getValidAccessSnapshotForAccount("xai", accountId, { requireUsableAccount: true });
+    } catch (err) {
+      return jsonResponse(
+        { error: { code: "auth_failed", message: "Failed to resolve valid xAI credentials for account" } },
+        401,
+        req,
+        config,
+      );
+    }
+
+    // Journaling and Idempotency settlement check
+    const effectiveOpId = operationId ?? crypto.randomUUID();
+    const opRecord = openGrokResetCouponOperation({
+      accountId,
+      tokenId: requestedTokenId,
+      operationId: effectiveOpId,
+    });
+
+    if (opRecord.kind === "replay") {
+      return jsonResponse(
+        {
+          code: opRecord.code,
+          replayed: true,
+          tokenId: opRecord.tokenId,
+          settledAt: opRecord.settledAt,
+        },
+        200,
+        req,
+        config,
+      );
+    }
+
+    if (opRecord.kind === "identity-mismatch") {
+      return jsonResponse(
+        {
+          error: {
+            code: "operation_id_owned_by_another_account",
+            message: "Operation ID was previously registered with a different account or token",
+          },
+        },
+        409,
+        req,
+        config,
+      );
+    }
+
+    if (opRecord.kind !== "execute") {
+      return jsonResponse(
+        {
+          error: {
+            code: opRecord.kind,
+            message: "Coupon ledger capacity or unavailable failure",
+          },
+        },
+        503,
+        req,
+        config,
+      );
+    }
+
+    let resolvedTokenId = requestedTokenId;
+    if (!resolvedTokenId) {
+      try {
+        const remaining = await getGrokRemainingResets({ accessToken: tokenSnapshot.accessToken });
+        if (!remaining.tokens || remaining.tokens.length === 0) {
+          recordGrokResetCouponSettlement({
+            operationId: effectiveOpId,
+            code: "no_coupons_available",
+            status: "failed",
+          });
+          return jsonResponse(
+            { error: { code: "no_coupons_available", message: "No reset coupons available to redeem" } },
+            400,
+            req,
+            config,
+          );
+        }
+        resolvedTokenId = remaining.tokens[0].tokenId;
+      } catch (err) {
+        return jsonResponse(
+          { error: { code: "fetch_resets_failed", message: err instanceof Error ? err.message : String(err) } },
+          502,
+          req,
+          config,
+        );
+      }
+    }
+
+    try {
+      const redeemResult = await redeemGrokResetCoupon({
+        accessToken: tokenSnapshot.accessToken,
+        tokenId: resolvedTokenId,
+      });
+
+      recordGrokResetCouponSettlement({
+        operationId: effectiveOpId,
+        tokenId: resolvedTokenId,
+        code: "redeemed",
+        status: "success",
+      });
+
+      return jsonResponse(
+        {
+          success: true,
+          code: "redeemed",
+          replayed: false,
+          tokenId: resolvedTokenId,
+          accountId,
+          operationId: effectiveOpId,
+        },
+        200,
+        req,
+        config,
+      );
+    } catch (err) {
+      recordGrokResetCouponSettlement({
+        operationId: effectiveOpId,
+        tokenId: resolvedTokenId,
+        code: "redeem_failed",
+        status: "failed",
+      });
+      return jsonResponse(
+        { error: { code: "redeem_failed", message: err instanceof Error ? err.message : String(err) } },
+        502,
+        req,
+        config,
+      );
+    }
+  }
+
+  return null;
+}
diff --git a/src/server/management/integration-routes.ts b/src/server/management/integration-routes.ts
index 43c0e6a98c..2363e745d5 100644
--- a/src/server/management/integration-routes.ts
+++ b/src/server/management/integration-routes.ts
@@ -16,6 +16,7 @@ import {
   asideJournalDeleteResponse, type AsideProfileRouteOptions,
 } from "./aside-profile-routes";
 import type { IntegrationIO } from "../../integrations/config-io";
+import { createClineIO } from "../../integrations/cline-io";
 import { matchesOperationResult } from "../../integrations/journal";
 import {
   INTEGRATION_CLIENT_IDS,
@@ -534,7 +535,11 @@ export async function handleIntegrationRoutes(ctx: ManagementContext): Promise<R
           undoable: (() => {
             if (snapshot === "expired") return false;
             if (newestByClient.get(operation.clientId) !== operation.opId) return false;
-            const current = currentConfigText(operation.configPath);
+            const current = operation.clientId === "cline" ? (() => {
+              const io = createClineIO(integrationMutationTestHooks?.io ?? store.io(), operation.configPath, store);
+              const read = io.readText(operation.configPath);
+              return read.kind === "text" ? read.text : read.kind === "missing" ? null : undefined;
+            })() : currentConfigText(operation.configPath);
             return current === undefined ? false : matchesOperationResult(operation, current);
           })(),
           /*
diff --git a/src/server/management/oauth-account-routes.ts b/src/server/management/oauth-account-routes.ts
index e2ba5a2029..89f80e5f88 100644
--- a/src/server/management/oauth-account-routes.ts
+++ b/src/server/management/oauth-account-routes.ts
@@ -255,6 +255,14 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
     const { clearProviderQuotaCache, clearAccountQuotaCache } = await import("../../providers/quota");
     clearProviderQuotaCache();
     clearAccountQuotaCache(provider);
+    if (provider === "devin") {
+      // The cached user_jwt's payload contains the api_key, and the catalog is
+      // keyed by that key. Without this they outlive the credential in process
+      // memory until the JWT's own ~24 minute expiry.
+      const { clearCachedUserJwt, clearCachedCatalog } = await import("../../adapters/devin/cloud-direct");
+      clearCachedUserJwt();
+      clearCachedCatalog();
+    }
     return jsonResponse({ success: true });
   }
 
@@ -331,6 +339,12 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
     if (!(await setActiveAccount(provider, body.accountId))) return jsonResponse({ error: "account not found" }, 404);
     const { forgetGenericFailoverRoster } = await import("../../oauth/generic-account-failover");
     forgetGenericFailoverRoster(provider);
+    // Seed the rotation cursor on the operator's pick, or a sticky round-robin ring hands the
+    // very next dispatch back to whatever the pool had chosen. forgetGenericFailoverRoster
+    // only drops the presence count; it has never touched the cursor. Same defect the Codex
+    // side carries resetCodexRoutingForManualSelection for.
+    const { genericPoolKey, seedPoolRotationAccount } = await import("../../oauth/pool-kernel");
+    seedPoolRotationAccount(genericPoolKey(provider), body.accountId);
     if (provider === "anthropic") {
       const { resetAnthropicRoutingForManualSelection } = await import("../../oauth/anthropic-routing");
       resetAnthropicRoutingForManualSelection(body.accountId);
@@ -344,6 +358,91 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
     return jsonResponse({ ok: true, provider, activeAccountId: body.accountId });
   }
 
+  // The unified pool-settings contract (#695 wp5c). The three legacy paths keep working and
+  // keep their own shapes -- goldens pin them -- but this is the one an operator or a dashboard
+  // should read, because it answers with the same keys for every kind and DECLARES which of
+  // them that kind honours.
+  if (url.pathname === "/api/pool/settings" && (req.method === "GET" || req.method === "PUT" || req.method === "PATCH")) {
+    const {
+      poolSettingsCapability, parseGenericPoolStrategy, parseGenericAutoSwitchThreshold, parseGenericStickyLimit,
+      unifiedPoolSettingsDto,
+    } = await import("../../oauth/pool-settings-capability");
+    const rawBody = req.method === "GET" ? {} : await readManagementJsonBodyOr(req, {});
+    if (req.method !== "GET" && !isPlainRecord(rawBody)) {
+      return jsonResponse({ error: "body must be an object" }, 400);
+    }
+    const fields = rawBody as { provider?: unknown; enabled?: unknown; strategy?: unknown; stickyLimit?: unknown; autoSwitchThreshold?: unknown; quotaWindow?: unknown };
+    const provider = req.method === "GET"
+      ? (url.searchParams.get("provider") ?? "").trim().toLowerCase()
+      : (typeof fields.provider === "string" ? fields.provider.trim().toLowerCase() : "");
+    const kind = provider ? poolSettingsCapability(provider, config.providers?.[provider]) : null;
+    if (!provider || !kind) {
+      return jsonResponse({ error: "pool settings are only available for the codex, anthropic and generic OAuth pools" }, 400);
+    }
+    // Validated by the SHARED parsers before any kind-specific write, so a bad strategy or
+    // sticky limit is refused identically whichever pool is addressed.
+    let strategy: string | undefined;
+    if (fields.strategy !== undefined) {
+      const parsed = parseGenericPoolStrategy(fields.strategy);
+      if (parsed === null) return jsonResponse({ error: "strategy must be one of: quota, round-robin, fill-first" }, 400);
+      strategy = parsed;
+    }
+    let stickyLimit: number | undefined;
+    if (fields.stickyLimit !== undefined) {
+      const parsed = parseGenericStickyLimit(fields.stickyLimit);
+      if (parsed === null) return jsonResponse({ error: "stickyLimit must be an integer 1-100" }, 400);
+      stickyLimit = parsed;
+    }
+    let autoSwitchThreshold: number | undefined;
+    if (fields.autoSwitchThreshold !== undefined) {
+      const parsed = parseGenericAutoSwitchThreshold(fields.autoSwitchThreshold);
+      if (parsed === null) return jsonResponse({ error: "autoSwitchThreshold must be an integer 0-100" }, 400);
+      autoSwitchThreshold = parsed;
+    }
+    if (fields.quotaWindow !== undefined && kind !== "anthropic") {
+      return jsonResponse({ error: "quotaWindow is only part of the anthropic pool contract" }, 400);
+    }
+    let quotaWindow: string | undefined;
+    if (fields.quotaWindow !== undefined) {
+      const parsed = parseAccountPoolQuotaWindow(fields.quotaWindow);
+      if (parsed === null) return jsonResponse({ error: "quotaWindow must be one of: five-hour, weekly, max-utilization" }, 400);
+      quotaWindow = parsed;
+    }
+    if (fields.enabled !== undefined) {
+      if (kind === "codex") return jsonResponse({ error: "enabled is not part of the codex pool contract" }, 400);
+      if (typeof fields.enabled !== "boolean") return jsonResponse({ error: "enabled must be a boolean" }, 400);
+    }
+
+    if (req.method !== "GET") {
+      if (kind === "codex") {
+        if (strategy !== undefined) config.accountPoolStrategy = strategy as never;
+        if (stickyLimit !== undefined) config.accountPoolStickyLimit = stickyLimit;
+        if (autoSwitchThreshold !== undefined) config.autoSwitchThreshold = autoSwitchThreshold;
+      } else if (kind === "anthropic") {
+        const pool = { ...(config.anthropicAccountPool ?? {}) };
+        if (fields.enabled !== undefined) pool.enabled = fields.enabled as boolean;
+        if (strategy !== undefined) pool.strategy = strategy as never;
+        if (stickyLimit !== undefined) pool.stickyLimit = stickyLimit;
+        if (autoSwitchThreshold !== undefined) pool.autoSwitchThreshold = autoSwitchThreshold;
+        if (quotaWindow !== undefined) pool.quotaWindow = quotaWindow as never;
+        config.anthropicAccountPool = pool;
+      } else {
+        const prov = config.providers[provider]!;
+        const next = { ...(prov.oauthAccountFailover ?? {}) };
+        if (fields.enabled !== undefined) next.enabled = fields.enabled as boolean;
+        if (strategy !== undefined) next.strategy = strategy as never;
+        if (stickyLimit !== undefined) next.stickyLimit = stickyLimit;
+        if (autoSwitchThreshold !== undefined) next.autoSwitchThreshold = autoSwitchThreshold;
+        if (Object.keys(next).length > 0) prov.oauthAccountFailover = next;
+        else delete prov.oauthAccountFailover;
+      }
+      saveConfigPreservingClaudeCode(config);
+      reconcileLiveStateStores();
+    }
+    return jsonResponse(unifiedPoolSettingsDto(config, provider, kind));
+  }
+
+
   // Opt-in Anthropic OAuth account pool (#294): enable/threshold/strategy + clear cooldown.
   if (url.pathname === "/api/oauth/accounts/pool" && req.method === "GET") {
     const provider = (url.searchParams.get("provider") ?? "").trim().toLowerCase();
@@ -357,7 +456,7 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
       if (!provider || !prov || poolSettingsCapability(provider, prov) !== "generic") {
         return jsonResponse({ error: "pool config is only supported for anthropic and generic OAuth providers" }, 400);
       }
-      return jsonResponse(genericPoolSettingsDto(provider, prov));
+      return jsonResponse(genericPoolSettingsDto(provider, prov, config.pool?.kernel === true));
     }
     const pool = config.anthropicAccountPool ?? {};
     return jsonResponse({
@@ -387,13 +486,14 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
     if (provider !== "anthropic") {
       const {
         poolSettingsCapability, genericPoolSettingsDto, parseGenericPoolStrategy, parseGenericAutoSwitchThreshold,
+        parseGenericStickyLimit,
       } = await import("../../oauth/pool-settings-capability");
       const prov = config.providers[provider];
       if (!provider || !prov || poolSettingsCapability(provider, prov) !== "generic") {
         return jsonResponse({ error: "pool config is only supported for anthropic and generic OAuth providers" }, 400);
       }
-      if (body.stickyLimit !== undefined || body.quotaWindow !== undefined) {
-        return jsonResponse({ error: "stickyLimit and quotaWindow are not part of the generic pool contract yet" }, 400);
+      if (body.quotaWindow !== undefined) {
+        return jsonResponse({ error: "quotaWindow is not part of the generic pool contract yet" }, 400);
       }
       const next = { ...(prov.oauthAccountFailover ?? {}) };
       if (body.enabled !== undefined) {
@@ -416,10 +516,18 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
           next.autoSwitchThreshold = parsed;
         }
       }
+      if (body.stickyLimit !== undefined) {
+        if (body.stickyLimit === null) delete next.stickyLimit;
+        else {
+          const parsed = parseGenericStickyLimit(body.stickyLimit);
+          if (parsed === null) return jsonResponse({ error: "stickyLimit must be an integer 1-100" }, 400);
+          next.stickyLimit = parsed;
+        }
+      }
       if (Object.keys(next).length > 0) prov.oauthAccountFailover = next;
       else delete prov.oauthAccountFailover;
       saveConfigPreservingClaudeCode(config);
-      return jsonResponse({ ok: true, ...genericPoolSettingsDto(provider, prov) });
+      return jsonResponse({ ok: true, ...genericPoolSettingsDto(provider, prov, config.pool?.kernel === true) });
     }
     let enabled = config.anthropicAccountPool?.enabled === true;
     if (body.enabled !== undefined) {
@@ -623,8 +731,11 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
     clearModelCache(name);
     const { clearProviderQuotaCache } = await import("../../providers/quota");
     clearProviderQuotaCache();
-    const { clearKeyCooldowns } = await import("../../providers/key-failover");
+    const { clearKeyCooldowns, forgetApiKeyRotationCursor } = await import("../../providers/key-failover");
     clearKeyCooldowns(name); // manual key management resets 429 cooldown state
+    // ...and the rotation cursor with it. A cursor that predates the operator's choice would
+    // hand the next proactive pick straight back to whichever key the pool had reached.
+    forgetApiKeyRotationCursor(name);
     return jsonResponse({ ok: true, id: result.id }, 201);
   }
   // Opt-in OS keychain storage (#1221): move the active key and pool into the OS credential
@@ -667,8 +778,11 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
     clearModelCache(name);
     const { clearProviderQuotaCache } = await import("../../providers/quota");
     clearProviderQuotaCache();
-    const { clearKeyCooldowns } = await import("../../providers/key-failover");
+    const { clearKeyCooldowns, forgetApiKeyRotationCursor } = await import("../../providers/key-failover");
     clearKeyCooldowns(name); // manual key management resets 429 cooldown state
+    // ...and the rotation cursor with it. A cursor that predates the operator's choice would
+    // hand the next proactive pick straight back to whichever key the pool had reached.
+    forgetApiKeyRotationCursor(name);
     return jsonResponse({ ok: true, name, activeId: body.id });
   }
   if (url.pathname === "/api/providers/keys/alias" && req.method === "PUT") {
@@ -696,8 +810,11 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
     clearModelCache(name);
     const { clearProviderQuotaCache } = await import("../../providers/quota");
     clearProviderQuotaCache();
-    const { clearKeyCooldowns } = await import("../../providers/key-failover");
+    const { clearKeyCooldowns, forgetApiKeyRotationCursor } = await import("../../providers/key-failover");
     clearKeyCooldowns(name); // manual key management resets 429 cooldown state
+    // ...and the rotation cursor with it. A cursor that predates the operator's choice would
+    // hand the next proactive pick straight back to whichever key the pool had reached.
+    forgetApiKeyRotationCursor(name);
     return jsonResponse({ ok: true });
   }
 
diff --git a/src/server/management/provider-routes.ts b/src/server/management/provider-routes.ts
index 1439d7899c..6977a17783 100644
--- a/src/server/management/provider-routes.ts
+++ b/src/server/management/provider-routes.ts
@@ -57,7 +57,10 @@ import {
 import { extractGoogleAiStudioModelItems } from "../../providers/google-ai-studio-model-discovery";
 import { routedSlug, slugEquals } from "../../providers/slug-codec";
 import { clearAccountQuotaCache, clearProviderQuotaCache, fetchProviderQuotaReports } from "../../providers/quota";
-import { clearKeyCooldowns } from "../../providers/key-failover";
+import { getCachedProviderRoutingQuota } from "../../providers/quota-routing-cache";
+import { PROVIDER_QUOTA_MAX_AGE_MS, type ProviderRoutingQuota } from "../../providers/quota-types";
+import { cachedProviderQuotaIsExhausted } from "../../combos/resolve";
+import { clearKeyCooldowns, forgetApiKeyRotationCursor } from "../../providers/key-failover";
 import { providerRequestPacingStatus } from "../../providers/request-pacing";
 import { CODEX_FORWARD_BASE_URL, isCanonicalOpenAiForwardProvider } from "../../providers/openai-tiers";
 import { codexAccountNamespaceProviderCollisionError } from "../../codex/account-namespace-match";
@@ -112,6 +115,7 @@ import {
   XAI_RESPONSES_DEFAULT_VERSION,
   xaiResponsesOptInState,
 } from "../../providers/xai-responses-opt-in";
+import { ZAI_PROVIDER_ID } from "../../providers/zai-responses-migration";
 import { dropProviderCustomModels } from "../../providers/provider-id-rewrite";
 
 import { isPlainRecord, parseDebugLogQuery, tokPerSecondResult, unavailableCostReason, costResult, requestLogDto, stripRegistryOnlyStaticHeaders, fetchAllModels } from "./shared";
@@ -573,6 +577,19 @@ function applyProviderPatchFields(
     }
     touched = true;
   }
+  if (Object.hasOwn(rawBody, "noJsonSchemaModels")) {
+    const value = rawBody.noJsonSchemaModels;
+    if (value === null) {
+      delete next.noJsonSchemaModels;
+    } else {
+      const error = nonBlankStringArrayConfigError(value, "noJsonSchemaModels");
+      if (error) return { error };
+      const models = normalizeNonBlankStringArray(value as string[]);
+      if (models.length > 0) next.noJsonSchemaModels = models;
+      else delete next.noJsonSchemaModels;
+    }
+    touched = true;
+  }
   if (Object.hasOwn(rawBody, "retainModels")) {
     const value = rawBody.retainModels;
     if (value === null) {
@@ -689,12 +706,54 @@ function canonicalOpenAiBudgetPatchError(
     ?? providerEmptyToolOutputConfigError("openai", applied.next);
 }
 
+function providerRoutingQuota(config: OcxConfig, name: string, now: number): ProviderRoutingQuota {
+  const provider = hasOwnProvider(config.providers, name) ? config.providers[name] : undefined;
+  const quota = getCachedProviderRoutingQuota(name, provider, now);
+  if (!quota || !Number.isFinite(quota.updatedAt) || quota.updatedAt < 0 || quota.updatedAt > now
+    || now >= quota.updatedAt + PROVIDER_QUOTA_MAX_AGE_MS) return { state: "unknown" };
+
+  // Removing search/MCP windows may leave only a timestamp. That is not inference evidence.
+  const percentages = [quota.fiveHourPercent, quota.weeklyPercent, quota.monthlyPercent,
+    ...(quota.customWindows ?? []).map(window => window.percent)];
+  const hasPercentage = percentages.some(value => typeof value === "number" && Number.isFinite(value) && value >= 0);
+  const credits = quota.creditsUsd;
+  const hasCredits = credits !== undefined && Number.isFinite(credits.percent)
+    && credits.percent >= 0 && Number.isFinite(credits.remaining);
+  if (!hasPercentage && !hasCredits) return { state: "unknown" };
+
+  const state = cachedProviderQuotaIsExhausted(quota, now) ? "exhausted" : "available";
+  let validUntil = quota.updatedAt + PROVIDER_QUOTA_MAX_AGE_MS;
+  if (state === "exhausted") {
+    const resets = [quota.fiveHourResetAt, quota.weeklyResetAt, quota.monthlyResetAt,
+      ...(quota.customWindows ?? []).map(window => window.resetAt)]
+      .filter((reset): reset is number => typeof reset === "number" && Number.isFinite(reset)
+        && reset > now && reset < validUntil)
+      .sort((left, right) => left - right);
+    // Reuse dispatch's predicate: another exhausted window or USD cap may still block.
+    for (const reset of resets) {
+      if (!cachedProviderQuotaIsExhausted(quota, reset)) {
+        validUntil = reset;
+        break;
+      }
+    }
+  }
+  return { state, updatedAt: quota.updatedAt, validUntil };
+}
+
 export async function handleProviderRoutes(ctx: ManagementContext): Promise<Response | null> {
   const { req, url, config, deps, principal, convergeCodexCatalog, syncClaudeAgentDefsBestEffort } = ctx;
 
   if (url.pathname === "/api/provider-quotas" && req.method === "GET") {
     const forceRefresh = url.searchParams.get("refresh") === "1" || url.searchParams.get("refresh") === "true";
-    return jsonResponse(await fetchProviderQuotaReports(config, forceRefresh));
+    const snapshot = await fetchProviderQuotaReports(config, forceRefresh);
+    const now = Date.now();
+    return jsonResponse({
+      ...snapshot,
+      reports: snapshot.reports.map(report => ({
+        ...report,
+        routingQuota: providerRoutingQuota(config, report.provider, now),
+      })),
+    });
   }
 
   if (url.pathname === "/api/provider-request-pacing" && req.method === "GET") {
@@ -730,6 +789,7 @@ export async function handleProviderRoutes(ctx: ManagementContext): Promise<Resp
       modelAutoCompactTokenLimits: p.modelAutoCompactTokenLimits,
       modelSupportsServiceTier: p.modelSupportsServiceTier,
       noStructuredOutputModels: p.noStructuredOutputModels,
+      noJsonSchemaModels: p.noJsonSchemaModels,
       retainModels: p.retainModels,
       omitReasoningEffortWithToolsModels: p.omitReasoningEffortWithToolsModels,
       upstreamHttpVersion: p.upstreamHttpVersion,
@@ -816,6 +876,9 @@ export async function handleProviderRoutes(ctx: ManagementContext): Promise<Resp
     (deps.clearProviderQuotaCache ?? clearProviderQuotaCache)();
     clearAccountQuotaCache(name);
     clearKeyCooldowns(name);
+    // The rotation cursor describes a pool this edit just changed; keeping it would let a
+    // stale position steer the next proactive pick.
+    forgetApiKeyRotationCursor(name);
     clearModelCache(name);
     if (name === "openai") (deps.clearThreadAccountMap ?? clearThreadAccountMap)();
     const catalogRefresh = await convergeCodexCatalog();
@@ -915,6 +978,10 @@ export async function handleProviderRoutes(ctx: ManagementContext): Promise<Resp
     (deps.clearProviderQuotaCache ?? clearProviderQuotaCache)();
     clearAccountQuotaCache();
     clearKeyCooldowns();
+    // Cursors too, for the same reason the cooldown clear above takes no name: this PUT
+    // replaces the whole roster, and a cursor that outlives it still names a real id, so
+    // round-robin would resume after the pre-edit position instead of the new roster head.
+    forgetApiKeyRotationCursor();
     clearModelCache();
     (deps.clearThreadAccountMap ?? clearThreadAccountMap)();
     const catalogRefresh = await convergeCodexCatalog();
@@ -1061,6 +1128,14 @@ export async function handleProviderRoutes(ctx: ManagementContext): Promise<Resp
         prov.xaiResponsesDefaultVersion = latest.xaiResponsesDefaultVersion;
       }
     }
+    // Same reason for the Z.AI marker: the provider form never carries it, and losing it on an
+    // unrelated edit would let the one-time wire rewrite run a second time.
+    if (name === ZAI_PROVIDER_ID) {
+      const latest = config.providers[name];
+      if (latest?.zaiResponsesDefaultVersion !== undefined) {
+        prov.zaiResponsesDefaultVersion = latest.zaiResponsesDefaultVersion;
+      }
+    }
     // Reapply pins to the latest live row after DNS/import awaits, then validate the
     // complete draft before adopting any provider/default state.
     const latest = config.providers[name];
diff --git a/src/server/management/route-registry.ts b/src/server/management/route-registry.ts
index d8f81de5ec..9fb71e662c 100644
--- a/src/server/management/route-registry.ts
+++ b/src/server/management/route-registry.ts
@@ -107,7 +107,7 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   { method: "PUT", path: "/api/codex-auth/active", module: "codex/auth-api", mutates: true },
   { method: "PUT", path: "/api/codex-auth/auto-switch", module: "codex/auth-api", mutates: true },
   { method: "PUT", path: "/api/codex-auth/failover", module: "codex/auth-api", mutates: true },
-  { method: "PUT", path: "/api/codex-auth/pool-strategy", module: "codex/auth-api", mutates: true },
+  { method: "PUT", path: "/api/codex-auth/pool-strategy", module: "codex/auth-api", mutates: true, exempt: { reason: "compatibility-alias", why: "Superseded by PUT /api/pool/settings, which the CLI now drives. Kept working for existing clients and pinned by exact-body goldens in tests/server/account-pool-management-api.test.ts; no CLI verb targets it any more." } },
   // codex/native-profile-api
   { method: "GET", path: "/api/native-main-profiles", module: "codex/native-profile-api", mutates: false },
   { method: "GET", path: "/api/native-main-profiles/doctor", module: "codex/native-profile-api", mutates: false },
@@ -131,6 +131,8 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   { method: "GET", path: "/api/v2", module: "server/management/agent-settings-routes", mutates: false },
   { method: "POST", path: "/api/claude-desktop/apply", module: "server/management/agent-settings-routes", mutates: true },
   { method: "POST", path: "/api/grok/apply", module: "server/management/agent-settings-routes", mutates: true },
+  { method: "GET", path: "/api/grok/reset-coupons", module: "server/management/grok-coupon-routes", mutates: false },
+  { method: "POST", path: "/api/grok/reset-coupons/consume", module: "server/management/grok-coupon-routes", mutates: true },
   { method: "PUT", path: "/api/claude-code", module: "server/management/agent-settings-routes", mutates: true },
   { method: "PUT", path: "/api/claude-desktop", module: "server/management/agent-settings-routes", mutates: true },
   { method: "PUT", path: "/api/codex-auth/features/default-mode-request-user-input", module: "server/management/agent-settings-routes", mutates: true },
@@ -261,6 +263,9 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   { method: "GET", path: "/api/oauth/accounts", module: "server/management/oauth-account-routes", mutates: false },
   { method: "GET", path: "/api/accounts/events", module: "server/management/oauth-account-routes", mutates: false, exempt: { reason: "gui-invalidation", why: "Dashboard selection invalidation stream; CLI account commands read the authoritative account/key resources directly rather than subscribing to browser refresh notifications." } },
   { method: "GET", path: "/api/oauth/accounts/pool", module: "server/management/oauth-account-routes", mutates: false },
+  { method: "GET", path: "/api/pool/settings", module: "server/management/oauth-account-routes", mutates: false },
+  { method: "PUT", path: "/api/pool/settings", module: "server/management/oauth-account-routes", mutates: true },
+  { method: "PATCH", path: "/api/pool/settings", module: "server/management/oauth-account-routes", mutates: true },
   { method: "GET", path: "/api/oauth/providers", module: "server/management/oauth-account-routes", mutates: false },
   { method: "GET", path: "/api/oauth/status", module: "server/management/oauth-account-routes", mutates: false },
   { method: "GET", path: "/api/providers/keys", module: "server/management/oauth-account-routes", mutates: false },
diff --git a/src/server/request-log.ts b/src/server/request-log.ts
index 6c92aad3ae..c77db6cbc0 100644
--- a/src/server/request-log.ts
+++ b/src/server/request-log.ts
@@ -50,6 +50,7 @@ import { enforceAppOwnedMemoryBudget, type RetainedStoreSnapshot } from "../lib/
 import { capEstimateAtContextWindow } from "../lib/token-estimate";
 import { inferCursorContextWindow } from "../adapters/cursor/discovery";
 import { KIRO_MODEL_CONTEXT_WINDOWS, normalizeKiroModelId } from "../providers/kiro-models";
+import { DEVIN_MODEL_CONTEXT_WINDOWS } from "../adapters/devin/live-models";
 import { modelRecordValue } from "../reasoning-effort";
 
 export interface RequestLogContext {
@@ -1190,6 +1191,9 @@ function contextWindowForModel(adapter: string, modelId: string | undefined): nu
   if (adapter === "cursor" || adapter.startsWith("cursor-")) {
     return inferCursorContextWindow(modelId);
   }
+  if (adapter === "devin") {
+    return modelRecordValue(DEVIN_MODEL_CONTEXT_WINDOWS, modelId);
+  }
   return undefined;
 }
 
diff --git a/src/server/responses-undeclared-tool-guard.ts b/src/server/responses-undeclared-tool-guard.ts
index cad1b39011..69b445a713 100644
--- a/src/server/responses-undeclared-tool-guard.ts
+++ b/src/server/responses-undeclared-tool-guard.ts
@@ -5,7 +5,7 @@ import {
   namespacedToolName,
   normalizeDeclaredToolName,
 } from "../types";
-import { sseDataPayload, type SseBlockRewrite } from "./sse-payload-rewrite";
+import { replaceSseDataPayload, sseDataPayload, type SseBlockRewrite } from "./sse-payload-rewrite";
 
 /** Item types the client executes through a request-declared wire name. */
 const CLIENT_EXECUTED_CALL_TYPES = new Set(["function_call", "custom_tool_call"]);
@@ -171,6 +171,49 @@ export function collectDeclaredWireToolNames(body: unknown): Set<string> {
   return names;
 }
 
+/**
+ * Collects explicitly declared bare wire tool names from a Responses request body.
+ *
+ * Bare wire tools are top-level declarations (or grouped under the builtin `functions`
+ * namespace) that are not namespaced and do not carry a flattened namespace delimiter (`__`)
+ * or dotted namespace alias (`.`).
+ *
+ * @param body - The outbound or inbound request body.
+ * @returns A set of declared bare tool names.
+ */
+export function collectDeclaredBareWireToolNames(body: unknown): Set<string> {
+  const names = new Set<string>();
+  if (!isPlainObject(body)) return names;
+  const specGroups: unknown[] = [body.tools];
+  if (Array.isArray(body.input)) {
+    for (const item of body.input) {
+      if (
+        isPlainObject(item)
+        && (item.type === "additional_tools" || item.type === "tool_search_output")
+      ) specGroups.push(item.tools);
+    }
+  }
+  for (const specs of specGroups) {
+    if (!Array.isArray(specs)) continue;
+    for (const spec of specs) {
+      if (!isPlainObject(spec)) continue;
+      if (spec.type === "namespace" && Array.isArray(spec.tools)) {
+        if (spec.name === BUILTIN_FUNCTIONS_NAMESPACE) {
+          for (const inner of spec.tools) {
+            if (!isPlainObject(inner)) continue;
+            const name = wireToolInnerName(inner);
+            if (name && !name.includes("__") && !name.includes(".")) names.add(name);
+          }
+        }
+        continue;
+      }
+      const name = wireToolInnerName(spec);
+      if (name && !name.includes("__") && !name.includes(".")) names.add(name);
+    }
+  }
+  return names;
+}
+
 function addNamelessClientCallTypes(callTypes: Set<string>, specs: unknown): void {
   if (!Array.isArray(specs)) return;
   for (const spec of specs) {
@@ -286,11 +329,22 @@ export function hasExplicitWireToolCatalog(body: unknown): boolean {
   );
 }
 
+/**
+ * Evaluates whether an individual output item represents an undeclared tool call.
+ *
+ * @param item - The item to check.
+ * @param declared - All wire tool names declared in the request catalog.
+ * @param declaredNamelessClientCallTypes - Nameless client call types declared by the request.
+ * @param providerExecutedCallTypes - Call types executed by the provider.
+ * @param declaredBare - Explicitly declared bare tool names without namespace provenance.
+ * @returns The undeclared tool call name if unauthorized, or undefined if permitted.
+ */
 function undeclaredNameInItem(
   item: unknown,
   declared: ReadonlySet<string>,
   declaredNamelessClientCallTypes: ReadonlySet<string>,
   providerExecutedCallTypes: ProviderExecutedCallTypes = EMPTY_PROVIDER_EXECUTED_CALL_TYPES,
+  declaredBare?: ReadonlySet<string>,
 ): string | undefined {
   if (!isPlainObject(item)) return undefined;
   if (typeof item.type !== "string") return undefined;
@@ -319,51 +373,232 @@ function undeclaredNameInItem(
       dottedAliasIsUnambiguous(item.namespace, name)
       && declared.has(dottedToolName(item.namespace, name))
     ) return undefined;
+    const bareDeclared = declaredBare ?? declared;
+    const bare = name.startsWith("default.") ? name.slice("default.".length) : name;
+    if (
+      item.namespace === "default"
+      && bare.length > 0
+      && bareDeclared.has(bare)
+      && !declared.has(namespacedToolName(item.namespace, bare))
+      && !declared.has(dottedToolName(item.namespace, bare))
+    ) return undefined;
     return name;
   }
-  const effectiveName = normalizeDeclaredToolName(name, declared);
+  const effectiveName = normalizeDeclaredToolName(name, declared, declaredBare);
   if (declared.has(effectiveName)) return undefined;
   return name;
 }
 
-/** First undeclared client tool named by a Responses SSE payload, or undefined. */
+/**
+ * First undeclared client tool named by a Responses SSE payload, or undefined.
+ *
+ * @param payload - The parsed SSE event payload.
+ * @param declared - All wire tool names declared in the request catalog.
+ * @param declaredNamelessClientCallTypes - Nameless client call types declared by the request.
+ * @param providerExecutedCallTypes - Call types executed by the provider.
+ * @param declaredBare - Explicitly declared bare tool names without namespace provenance.
+ * @returns The name of the first undeclared tool call, or undefined.
+ */
 export function undeclaredToolCallName(
   payload: unknown,
   declared: ReadonlySet<string>,
   declaredNamelessClientCallTypes: ReadonlySet<string> = EMPTY_DECLARED_NAMELESS_CLIENT_CALL_TYPES,
   providerExecutedCallTypes: ProviderExecutedCallTypes = EMPTY_PROVIDER_EXECUTED_CALL_TYPES,
+  declaredBare?: ReadonlySet<string>,
 ): string | undefined {
   if (!isPlainObject(payload)) return undefined;
   if (payload.type === "response.output_item.added" || payload.type === "response.output_item.done") {
-    return undeclaredNameInItem(payload.item, declared, declaredNamelessClientCallTypes, providerExecutedCallTypes);
+    return undeclaredNameInItem(payload.item, declared, declaredNamelessClientCallTypes, providerExecutedCallTypes, declaredBare);
+  }
+  if (payload.type === "response.function_call_arguments.done" && typeof payload.name === "string") {
+    const fakeItem = { type: "function_call", name: payload.name, namespace: payload.namespace };
+    return undeclaredNameInItem(fakeItem, declared, declaredNamelessClientCallTypes, providerExecutedCallTypes, declaredBare);
   }
   // Sparse gateways skip incremental items and only ever ship the terminal snapshot.
   if (payload.type === "response.completed" || payload.type === "response.incomplete") {
-    return undeclaredToolCallNameInResponse(payload.response, declared, declaredNamelessClientCallTypes, providerExecutedCallTypes);
+    return undeclaredToolCallNameInResponse(payload.response, declared, declaredNamelessClientCallTypes, providerExecutedCallTypes, declaredBare);
   }
   return undefined;
 }
 
-/** First undeclared client tool in a Responses object's `output` array, or undefined. */
+/**
+ * First undeclared client tool in a Responses object's `output` array, or undefined.
+ *
+ * @param response - The Responses result object containing `output`.
+ * @param declared - All wire tool names declared in the request catalog.
+ * @param declaredNamelessClientCallTypes - Nameless client call types declared by the request.
+ * @param providerExecutedCallTypes - Call types executed by the provider.
+ * @param declaredBare - Explicitly declared bare tool names without namespace provenance.
+ * @returns The name of the first undeclared tool call, or undefined.
+ */
 export function undeclaredToolCallNameInResponse(
   response: unknown,
   declared: ReadonlySet<string>,
   declaredNamelessClientCallTypes: ReadonlySet<string> = EMPTY_DECLARED_NAMELESS_CLIENT_CALL_TYPES,
   providerExecutedCallTypes: ProviderExecutedCallTypes = EMPTY_PROVIDER_EXECUTED_CALL_TYPES,
+  declaredBare?: ReadonlySet<string>,
 ): string | undefined {
   if (!isPlainObject(response) || !Array.isArray(response.output)) return undefined;
   for (const item of response.output) {
-    const name = undeclaredNameInItem(item, declared, declaredNamelessClientCallTypes, providerExecutedCallTypes);
+    const name = undeclaredNameInItem(item, declared, declaredNamelessClientCallTypes, providerExecutedCallTypes, declaredBare);
     if (name !== undefined) return name;
   }
   return undefined;
 }
 
+/**
+ * Formats an error message indicating that a routed provider emitted an undeclared tool call.
+ *
+ * @param name - The undeclared tool name emitted by the provider.
+ * @returns A formatted error message string.
+ */
 export function undeclaredToolCallMessage(name: string): string {
   const reported = name.slice(0, MAX_REPORTED_NAME_CHARS);
   return `routed provider emitted undeclared client tool "${reported}"; only request-declared tools may be called`;
 }
 
+/**
+ * Normalizes a single output item's default-namespaced tool call back to declared bare tool.
+ *
+ * Strips invented `default.` prefixes or `namespace: "default"` from tool calls when the bare
+ * tool name was declared and neither dotted nor flattened namespaced forms were declared (#4176).
+ *
+ * @param item - The output item to normalize.
+ * @param declared - All wire tool names declared in the request catalog.
+ * @param declaredBare - Explicitly declared bare tool names without namespace provenance.
+ * @returns An object with the normalized value and a boolean indicating if changes occurred.
+ */
+export function normalizeDefaultNamespaceInItem(
+  item: unknown,
+  declared: ReadonlySet<string>,
+  declaredBare?: ReadonlySet<string>,
+): { value: unknown; changed: boolean } {
+  if (!isPlainObject(item)) return { value: item, changed: false };
+  if (!CLIENT_EXECUTED_CALL_TYPES.has(item.type as string)) {
+    return { value: item, changed: false };
+  }
+  const name = item.name;
+  if (typeof name !== "string" || name.length === 0) {
+    return { value: item, changed: false };
+  }
+  const bareDeclared = declaredBare ?? declared;
+  if (item.namespace === "default") {
+    const bare = name.startsWith("default.") ? name.slice("default.".length) : name;
+    if (
+      bare.length > 0
+      && bareDeclared.has(bare)
+      && !declared.has(namespacedToolName("default", bare))
+      && !declared.has(dottedToolName("default", bare))
+    ) {
+      const next: Record<string, unknown> = { ...(item as Record<string, unknown>), name: bare };
+      delete next.namespace;
+      return { value: next, changed: true };
+    }
+    return { value: item, changed: false };
+  }
+  if (item.namespace === undefined || item.namespace === BUILTIN_FUNCTIONS_NAMESPACE) {
+    if (name.startsWith("default.")) {
+      const bare = name.slice("default.".length);
+      if (
+        bare.length > 0
+        && bareDeclared.has(bare)
+        && !declared.has("default." + bare)
+        && !declared.has("default__" + bare)
+      ) {
+        return { value: { ...item, name: bare }, changed: true };
+      }
+    }
+  }
+  return { value: item, changed: false };
+}
+
+/**
+ * Normalizes default-namespaced tool calls in a Responses object's `output` array.
+ *
+ * @param response - The Responses result object containing `output`.
+ * @param declared - All wire tool names declared in the request catalog.
+ * @param declaredBare - Explicitly declared bare tool names without namespace provenance.
+ * @returns An object with the normalized response and a boolean indicating if changes occurred.
+ */
+export function normalizeDefaultNamespaceInResponse(
+  response: unknown,
+  declared: ReadonlySet<string>,
+  declaredBare?: ReadonlySet<string>,
+): { value: unknown; changed: boolean } {
+  if (!isPlainObject(response) || !Array.isArray(response.output)) {
+    return { value: response, changed: false };
+  }
+  let changed = false;
+  const newOutput = response.output.map(item => {
+    const res = normalizeDefaultNamespaceInItem(item, declared, declaredBare);
+    if (res.changed) changed = true;
+    return res.value;
+  });
+  if (!changed) return { value: response, changed: false };
+  return { value: { ...response, output: newOutput }, changed: true };
+}
+
+/**
+ * Normalizes default-namespaced tool calls in a Responses SSE payload object.
+ *
+ * @param payload - The parsed SSE event payload.
+ * @param declared - All wire tool names declared in the request catalog.
+ * @param declaredBare - Explicitly declared bare tool names without namespace provenance.
+ * @returns An object with the normalized payload and a boolean indicating if changes occurred.
+ */
+export function normalizeDefaultNamespaceInPayload(
+  payload: unknown,
+  declared: ReadonlySet<string>,
+  declaredBare?: ReadonlySet<string>,
+): { value: unknown; changed: boolean } {
+  if (!isPlainObject(payload)) return { value: payload, changed: false };
+  if (payload.type === "response.output_item.added" || payload.type === "response.output_item.done") {
+    const res = normalizeDefaultNamespaceInItem(payload.item, declared, declaredBare);
+    if (!res.changed) return { value: payload, changed: false };
+    return { value: { ...payload, item: res.value }, changed: true };
+  }
+  if (payload.type === "response.function_call_arguments.done" && typeof payload.name === "string") {
+    const fakeItem = { type: "function_call", name: payload.name, namespace: payload.namespace };
+    const res = normalizeDefaultNamespaceInItem(fakeItem, declared, declaredBare);
+    if (res.changed) {
+      const normalizedItem = res.value as Record<string, unknown>;
+      const next: Record<string, unknown> = { ...payload, name: normalizedItem.name };
+      if ("namespace" in next && !("namespace" in normalizedItem)) {
+        delete next.namespace;
+      }
+      return { value: next, changed: true };
+    }
+  }
+  if (payload.type === "response.completed" || payload.type === "response.incomplete") {
+    const res = normalizeDefaultNamespaceInResponse(payload.response, declared, declaredBare);
+    if (!res.changed) return { value: payload, changed: false };
+    return { value: { ...payload, response: res.value }, changed: true };
+  }
+  return { value: payload, changed: false };
+}
+
+/**
+ * Normalizes default-namespaced tool calls in a raw Responses JSON string.
+ *
+ * @param jsonText - Raw JSON string representing a Responses object.
+ * @param declared - All wire tool names declared in the request catalog.
+ * @param declaredBare - Explicitly declared bare tool names without namespace provenance.
+ * @returns The normalized JSON string, or original text if unchanged or invalid JSON.
+ */
+export function normalizeDefaultNamespaceInJson(
+  jsonText: string,
+  declared: ReadonlySet<string>,
+  declaredBare?: ReadonlySet<string>,
+): string {
+  try {
+    const parsed = JSON.parse(jsonText);
+    const normalized = normalizeDefaultNamespaceInResponse(parsed, declared, declaredBare);
+    return normalized.changed ? JSON.stringify(normalized.value) : jsonText;
+  } catch {
+    return jsonText;
+  }
+}
+
 function failedBlocks(name: string, newline: string): readonly string[] {
   const failure = {
     type: "upstream_error",
@@ -378,7 +613,8 @@ function failedBlocks(name: string, newline: string): readonly string[] {
 }
 
 /**
- * Fail closed when a routed provider calls a tool the request never declared (#1700).
+ * Fail closed when a routed provider calls a tool the request never declared (#1700),
+ * and normalize provider-invented default namespaces back to declared bare tools (#4176).
  *
  * The bridged paths already refuse such a call (`declaredToolNames` in src/bridge.ts), but the
  * native Responses passthrough relayed it verbatim: Codex received a `function_call` for a tool
@@ -389,11 +625,18 @@ function failedBlocks(name: string, newline: string): readonly string[] {
  *
  * Everything after the trip is dropped so a later `response.completed` cannot contradict the
  * terminal already sent. Non-JSON and non-item blocks pass through untouched.
+ *
+ * @param declared - All wire tool names declared in the request catalog.
+ * @param declaredNamelessClientCallTypes - Nameless client call types declared by the request.
+ * @param providerExecutedCallTypes - Call types executed by the provider.
+ * @param declaredBare - Explicitly declared bare tool names without namespace provenance.
+ * @returns An SSE block rewrite function.
  */
 export function createUndeclaredToolCallGuardBlockRewrite(
   declared: ReadonlySet<string>,
   declaredNamelessClientCallTypes: ReadonlySet<string> = EMPTY_DECLARED_NAMELESS_CLIENT_CALL_TYPES,
   providerExecutedCallTypes: ProviderExecutedCallTypes = EMPTY_PROVIDER_EXECUTED_CALL_TYPES,
+  declaredBare?: ReadonlySet<string>,
 ): SseBlockRewrite {
   let tripped = false;
   return (block: string) => {
@@ -406,9 +649,15 @@ export function createUndeclaredToolCallGuardBlockRewrite(
     } catch {
       return [block];
     }
-    const name = undeclaredToolCallName(parsed, declared, declaredNamelessClientCallTypes, providerExecutedCallTypes);
-    if (name === undefined) return [block];
-    tripped = true;
-    return failedBlocks(name, block.includes("\r\n") ? "\r\n" : "\n");
+    const name = undeclaredToolCallName(parsed, declared, declaredNamelessClientCallTypes, providerExecutedCallTypes, declaredBare);
+    if (name !== undefined) {
+      tripped = true;
+      return failedBlocks(name, block.includes("\r\n") ? "\r\n" : "\n");
+    }
+    const normalized = normalizeDefaultNamespaceInPayload(parsed, declared, declaredBare);
+    if (normalized.changed) {
+      return [replaceSseDataPayload(block, JSON.stringify(normalized.value))];
+    }
+    return [block];
   };
 }
diff --git a/src/server/responses/codex-ws-exchange.ts b/src/server/responses/codex-ws-exchange.ts
index 64a8e5aba4..698eb93340 100644
--- a/src/server/responses/codex-ws-exchange.ts
+++ b/src/server/responses/codex-ws-exchange.ts
@@ -4,9 +4,9 @@ import { CodexWsMetadata, type CodexWsQuotaObserver } from "./codex-ws-metadata"
 import { CODEX_RESPONSES_HTTP_URL, type PreparedCodexWsRequest } from "./codex-ws-request";
 import { CodexWsCorrelation } from "./codex-ws-correlation";
 import type { CodexWsSession } from "./codex-ws-session";
-import { UPGRADE_DEADLINE_MS, CODEX_WS_RESPONSE_PRELUDE_TIMEOUT_MS, MAX_CODEX_WS_FRAME_BYTES,
+import { UPGRADE_DEADLINE_MS, CODEX_WS_LIVENESS_PING_INTERVAL_MS, CODEX_WS_RESPONSE_PRELUDE_TIMEOUT_MS, MAX_CODEX_WS_FRAME_BYTES,
   MAX_CODEX_WS_QUEUE_BYTES, markCodexWsResponse, normalizeResponsesWsRelayEvent, closedBeforeTerminalMessage,
-  codexWsFailureDetail, type CodexWsFailureStage } from "./codex-ws-wire";
+  codexWsFailureDetail, codexWsPreResponseFailure, type CodexWsFailureStage } from "./codex-ws-wire";
 
 interface ExchangeOptions {
   session: CodexWsSession;
@@ -101,6 +101,8 @@ export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
     let upstreamFrames = 0;
     let controlFrames = 0;
     let relayedEvents = 0;
+    let pings = 0;
+    let pongs = 0;
     let sentAt: number | null = null;
     let firstFrameAt: number | null = null;
     let controller: ReadableStreamDefaultController<Uint8Array> | null = null;
@@ -108,7 +110,11 @@ export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
     const metadata = url === CODEX_RESPONSES_HTTP_URL ? new CodexWsMetadata(onQuota) : null;
     const correlation = session.retainable ? new CodexWsCorrelation(session.reused, id => session.hasCompleted(id)) : null;
     let detachOwner = () => {};
-    let preludeTimer: ReturnType<typeof setTimeout> | undefined;
+    // Liveness while waiting for the first response event (metadata path only): the
+    // silence timer is re-armed by every inbound frame or pong; the pinger runs on a fixed
+    // interval so a peer that answers pings can never trip the silence bound while alive.
+    let silenceTimer: ReturnType<typeof setTimeout> | undefined;
+    let pingTimer: ReturnType<typeof setTimeout> | undefined;
     const stream = new ReadableStream<Uint8Array>({
       start(c) { controller = c; },
       cancel() {
@@ -121,7 +127,8 @@ export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
 
     const cleanup = () => {
       clearTimeout(upgradeTimer);
-      clearTimeout(preludeTimer);
+      clearTimeout(silenceTimer);
+      clearTimeout(pingTimer);
       signal?.removeEventListener("abort", onAbort);
       metadata?.finish();
       correlation?.finish();
@@ -130,6 +137,7 @@ export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
       ws.removeEventListener("message", onMessage);
       ws.removeEventListener("close", onClose);
       ws.removeEventListener("error", onError);
+      ws.removeEventListener("pong", onPong);
     };
 
     /**
@@ -145,12 +153,15 @@ export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
       relayedEvents,
       firstFrameMs: sentAt !== null && firstFrameAt !== null ? Math.max(0, firstFrameAt - sentAt) : null,
       elapsedMs: sentAt !== null ? Math.max(0, Date.now() - sentAt) : null,
+      pings,
+      pongs,
     });
 
     const commitResponse = () => {
       if (responseCommitted) return;
       responseCommitted = true;
-      clearTimeout(preludeTimer);
+      clearTimeout(silenceTimer);
+      clearTimeout(pingTimer);
       const responseHeaders = metadata?.snapshot() ?? new Headers();
       responseHeaders.set("content-type", "text/event-stream; charset=utf-8");
       const response = new Response(stream, { status: 200, headers: responseHeaders });
@@ -159,17 +170,61 @@ export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
       resolve(response);
     };
 
-    const failStream = (error: unknown) => {
+    const failStream = (error: unknown, status: 502 | 504 = 502) => {
       if (terminal) return;
       terminal = true;
-      // A frame may already be executing upstream. Settle as a body failure,
-      // never a fetch rejection/5xx that the pre-stream wrapper could resend.
+      if (sent && !responseCommitted && metadata) {
+        // Nothing has been promised to the client yet, so the honest answer is a gateway
+        // status, not a 200 whose body then fails. The frame may already be executing
+        // upstream: the response is marked non-replayable so no layer of this process sends
+        // it again, and the client applies its own retry policy as it would on the direct
+        // path. Same settle order as a refused create: snapshot, detach, close, dispose.
+        const prelude = metadata.snapshot();
+        // Claim the commit slot so no later path can resolve a second, 200 Response.
+        responseCommitted = true;
+        cleanup();
+        try { controller?.close(); } catch { /* unused stream already closed */ }
+        session.dispose();
+        const message = error instanceof Error ? error.message : String(error);
+        resolve(codexWsPreResponseFailure(status, message, prelude));
+        return;
+      }
+      // A response is already flowing (or this transport has no metadata channel and
+      // committed at send). Settle as a body failure, never a fetch rejection/5xx that the
+      // pre-stream wrapper could resend.
       if (sent) commitResponse();
       cleanup();
       try { controller?.error(typeof error === "string" ? new Error(error) : error); } catch { /* stream already done */ }
       session.dispose();
     };
 
+    /** (Re)start the silence bound; every inbound frame or pong is proof of life. */
+    const armSilence = () => {
+      clearTimeout(silenceTimer);
+      if (responseCommitted || terminal) return;
+      silenceTimer = setTimeout(
+        () => failStream(`codex websocket response prelude timed out${codexWsFailureDetail(failureStage())}`, 504),
+        CODEX_WS_RESPONSE_PRELUDE_TIMEOUT_MS,
+      );
+    };
+    /** Ping on a fixed interval until the response starts; a socket without ping() is never pinged. */
+    const schedulePing = () => {
+      const ping = (ws as WebSocket & { ping?: (data?: string) => void }).ping;
+      if (typeof ping !== "function" || responseCommitted || terminal) return;
+      pingTimer = setTimeout(() => {
+        if (responseCommitted || terminal) return;
+        try { ping.call(ws); } catch { return; }
+        pings += 1;
+        // ping() may close the socket synchronously and settle the exchange; re-check.
+        if (!terminal) schedulePing();
+      }, CODEX_WS_LIVENESS_PING_INTERVAL_MS);
+    };
+    const onPong = () => {
+      if (terminal) return;
+      pongs += 1;
+      if (!responseCommitted) armSilence();
+    };
+
     const upgradeTimer = setTimeout(() => {
       if (opened || settledPreOpen) return;
       settledPreOpen = true;
@@ -188,6 +243,25 @@ export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
         reject(reason);
         return;
       }
+      if (!responseCommitted && metadata) {
+        // Sent, unacknowledged. The proxy's own connect deadline is an origin-silence
+        // verdict and settles like one; a caller abort is the caller's decision, so the
+        // exchange rejects with that reason and disposing the socket cancels the turn.
+        // Both arrive on the same composite signal (fetchWithHeaderTimeout joins the
+        // caller's controller with its own), so the reason is the only discriminator: the
+        // deadline aborts with a TimeoutError DOMException, and every caller abort in this
+        // process (upstream.abort() in core.ts) carries the default AbortError. A future
+        // proxy-side deadline that aborts with TimeoutError would still be honestly a 504.
+        if ((reason as { name?: unknown } | null)?.name === "TimeoutError") {
+          failStream(`codex websocket response did not start before the connect deadline${codexWsFailureDetail(failureStage())}`, 504);
+          return;
+        }
+        terminal = true;
+        cleanup();
+        session.dispose();
+        reject(reason);
+        return;
+      }
       failStream(reason);
     };
     const onAbort = () => cancelExchange(signal?.reason ?? new DOMException("The operation was aborted.", "AbortError"));
@@ -208,6 +282,7 @@ export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
         ws.removeEventListener("message", onMessage);
         ws.removeEventListener("close", onClose);
         ws.removeEventListener("error", onError);
+        ws.removeEventListener("pong", onPong);
         session.dispose();
         reject(error);
         return;
@@ -236,16 +311,15 @@ export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
       }
       if (!metadata) commitResponse();
       else if (!responseCommitted && !terminal) {
-        preludeTimer = setTimeout(
-          () => failStream(`codex websocket response prelude timed out${codexWsFailureDetail(failureStage())}`),
-          CODEX_WS_RESPONSE_PRELUDE_TIMEOUT_MS,
-        );
+        armSilence();
+        schedulePing();
       }
     };
 
     const onMessage = (event: MessageEvent) => {
       if (!controller || terminal) return;
       received = true;
+      if (!responseCommitted) armSilence();
       upstreamFrames += 1;
       if (firstFrameAt === null) firstFrameAt = Date.now();
       const text = typeof event.data === "string" ? event.data : "";
@@ -288,8 +362,9 @@ export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
       if (!controlFrame && !type.startsWith("response.") && type !== "error") return;
       if (!controlFrame) {
         try { correlation?.accept(normalized.payload); } catch (error) { failStream(error); return; }
-        // Correlation must run first: a reused socket's foreign-stream error
-        // must not become an HTTP refusal that could authorize account replay.
+        // Correlation must run first: a reused socket's foreign-stream error settles as a
+        // non-replayable 502 above, never as the refused-create 4xx projection below, which
+        // is the one status family that could authorize an account replay.
         if (metadata && sent && !responseCommitted && type === "error") {
           let rejection: Response | null;
           try { rejection = wrappedRejectionResponse(normalized.payload, metadata.snapshot()); }
@@ -366,6 +441,7 @@ export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
     ws.addEventListener("message", onMessage);
     ws.addEventListener("close", onClose);
     ws.addEventListener("error", onError);
+    ws.addEventListener("pong", onPong);
     if (signal?.aborted) onAbort();
     else if (session.opened) onOpen();
   });
diff --git a/src/server/responses/codex-ws-wire.ts b/src/server/responses/codex-ws-wire.ts
index 770ce21b54..6dc3a45c3b 100644
--- a/src/server/responses/codex-ws-wire.ts
+++ b/src/server/responses/codex-ws-wire.ts
@@ -1,7 +1,23 @@
 import { MAX_CLIENT_SSE_FRAME_BYTES } from "../sse-frame-buffer";
+import {
+  markResponseNonReplayable,
+  UPSTREAM_CLOSED_BEFORE_RESPONSE_CODE,
+  UPSTREAM_NO_RESPONSE_CODE,
+} from "../../lib/upstream-retry";
 // If the 101 never arrives (network black hole), give SSE a chance well before
 // the caller's connect timeout (default 200s) would fire.
 export const UPGRADE_DEADLINE_MS = 10_000;
+// Liveness while the exchange waits for its first response event. The proxy cannot know
+// how long the origin legitimately needs before `response.created` (a multi-image replay
+// spends that time in prefill; #4083 measured 30 s), and it is not the party that owns
+// the slowness policy — the client holds its own deadline and the operator holds
+// `connectTimeoutMs`. What the proxy can decide is whether the peer is still there, and
+// WebSocket has a native answer: ping. While waiting, the exchange pings every
+// CODEX_WS_LIVENESS_PING_INTERVAL_MS on sockets that expose `ping()`; any inbound frame
+// or pong resets the silence clock, and only CODEX_WS_RESPONSE_PRELUDE_TIMEOUT_MS of
+// nothing at all settles the exchange as an origin-silence 504. A peer that never pongs
+// keeps exactly the previous 90 s bound; a peer that does can never trip it while alive.
+export const CODEX_WS_LIVENESS_PING_INTERVAL_MS = 15_000;
 export const CODEX_WS_RESPONSE_PRELUDE_TIMEOUT_MS = 90_000;
 // Keep the push-based WS transport inside the same memory envelope as the
 // bounded SSE relays that consume this response. Unlike fetch response bodies,
@@ -48,6 +64,35 @@ export function markCodexWsResponse(response: Response, observed: boolean): void
   if (observed) quotaObservedResponses.add(response);
 }
 
+/**
+ * The honest settlement for an exchange that sent its create frame and never saw a
+ * response event.
+ *
+ * Before this existed the relay committed a 200 SSE Response and errored its body, on the
+ * reasoning that a 5xx could make the pre-stream retry wrapper resend the frame. That
+ * reasoning was right about the resend and wrong about the status: it turned "no response"
+ * into "a response that failed", removed the code a user agent uses for its own retry
+ * policy, and neutered the client's first-byte timeout with chunked headers. The client
+ * on the direct path receives a gateway status in this situation and retries under its own
+ * policy; this response restores that equivalence. The resend is forbidden by the
+ * non-replayable marker instead (see upstream-retry.ts), and the structured code lets the
+ * combo failover reach the same verdict after it re-parses the body.
+ *
+ * 504 is the origin's silence (nothing at all, or nothing but liveness, for the tolerated
+ * window); 502 is a transport that closed or misbehaved after the send. Both carry the
+ * content-free stage detail in the message and the metadata snapshot in the headers, the
+ * same way a refused create does, so quota captured during the prelude is not lost.
+ */
+export function codexWsPreResponseFailure(status: 502 | 504, message: string, prelude: Headers): Response {
+  const headers = new Headers(prelude);
+  headers.set("content-type", "application/json");
+  headers.set("cache-control", "no-store");
+  const code = status === 504 ? UPSTREAM_NO_RESPONSE_CODE : UPSTREAM_CLOSED_BEFORE_RESPONSE_CODE;
+  const response = new Response(JSON.stringify({ error: { type: "upstream_error", code, message } }), { status, headers });
+  markResponseNonReplayable(response);
+  return response;
+}
+
 const CLOSED_BEFORE_TERMINAL = "codex websocket closed before a Responses terminal event";
 
 /**
@@ -78,6 +123,10 @@ export type CodexWsFailureStage = {
   firstFrameMs: number | null;
   /** Milliseconds from send to this failure; null when the failure predates the send. */
   elapsedMs: number | null;
+  /** Liveness pings the exchange sent while waiting for the first response event. */
+  pings: number;
+  /** Pongs the peer answered with; zero on a peer that never answers pings. */
+  pongs: number;
 };
 
 /**
@@ -113,7 +162,8 @@ export function codexWsFailureDetail(stage: CodexWsFailureStage): string {
   return ` [cause=${classifyCodexWsFailure(stage)} request=${stage.requestBytes}B`
     + ` sent=${stage.sent ? "yes" : "no"} frames=${stage.upstreamFrames}`
     + ` control=${stage.controlFrames} relayed=${stage.relayedEvents}`
-    + ` first-frame=${duration(stage.firstFrameMs)} elapsed=${duration(stage.elapsedMs)}]`;
+    + ` first-frame=${duration(stage.firstFrameMs)} elapsed=${duration(stage.elapsedMs)}`
+    + ` pings=${stage.pings} pongs=${stage.pongs}]`;
 }
 
 export type ResponsesWsRelayEvent = {
diff --git a/src/server/responses/compact.ts b/src/server/responses/compact.ts
index 45bdb3fa3d..21958143db 100644
--- a/src/server/responses/compact.ts
+++ b/src/server/responses/compact.ts
@@ -111,7 +111,7 @@ import {
   UnsupportedContentEncodingError,
 } from "../request-decompress";
 import { resolveAdapter, resolveWireProtocolOverride } from "../adapter-resolve";
-import { hasKeyPoolFailover, rotateProviderTransportOn429 } from "../../providers/key-failover";
+import { hasKeyPoolFailover, rotateProviderTransportOn429, selectProactiveApiKeyTransport } from "../../providers/key-failover";
 import { shouldAttemptImageTierRetry } from "../image-retry";
 import { resolveProviderTransport } from "../../providers/xai-transport";
 import type { WsData } from "../ws-bridge";
@@ -743,6 +743,13 @@ export async function handleResponsesCompact(
       ? CODEX_FORWARD_BASE_URL
       : (compactProvider.baseUrl ?? "").replace(/\/+$/, "");
     if (compactProvider.authMode !== "forward" && compactProvider.apiKey) {
+      // Native compact never enters handleResponses, so it needs its own pre-dispatch key
+      // pick. Kept inside this branch on purpose: the overlay above owns the forward and
+      // codexAccountMode cases, and the picker returns null for them anyway.
+      // Transport variant, for the same reason as the Responses core: the persisted row has no
+      // registry backfills, and compactProvider is read for its transport fields below.
+      const warmKeyProvider = selectProactiveApiKeyTransport(config, route.providerName, compactProvider);
+      if (warmKeyProvider?.apiKey) compactProvider = warmKeyProvider;
       headers.set("authorization", `Bearer ${resolveProviderApiKey(compactProvider.apiKey)}`);
     }
     const { reasoning: _reasoning, ...compactBodyRaw } = raw as typeof raw & { reasoning?: unknown };
diff --git a/src/server/responses/core.ts b/src/server/responses/core.ts
index 3f4cfe4345..8b499d5111 100644
--- a/src/server/responses/core.ts
+++ b/src/server/responses/core.ts
@@ -1,4 +1,6 @@
 import type { Server } from "bun";
+import { recordContextSessionOwner } from "../../codex/context-owner";
+import { contextRelayActivated } from "../../codex/context-compat";
 import { randomUUID } from "node:crypto";
 import { bridgeToResponsesSSE, buildResponseJSON, formatErrorResponse, type ResponsesTerminalStatus } from "../../bridge";
 import { formatPassthroughUpstreamError } from "./passthrough-error";
@@ -145,6 +147,7 @@ import {
   GENERIC_OAUTH_MAX_FAILOVERS_PER_REQUEST,
   isGenericFailoverProvider,
   isGenericOAuthFailoverEnabled,
+  noteGenericPoolSelection,
   preferredInitialAccount,
   rotateGenericOAuthAccountOn429,
 } from "../../oauth/generic-account-failover";
@@ -210,6 +213,8 @@ import {
   applyUpstreamRecoveryInit,
   fetchWithResetRetry,
   fetchWithTransientRetry,
+  isNonReplayableResponse,
+  isTransientUpstreamStatus,
   prepareSameTarget429Wait,
 } from "../../lib/upstream-retry";
 import {
@@ -218,6 +223,7 @@ import {
   isProxyAdmissionSecret,
   validateForwardAdmissionCredential,
 } from "../auth-cors";
+import { resolveContextPrincipal } from "../auth-cors";
 import type { DataPlaneAdmission } from "../auth-cors";
 import { createTranslatorBudget, isTranslatorBudgetExceededError, type TranslatorBudget } from "../../lib/translator-budget";
 import { captureExplicitOpenAiCallerAuth, listOpenAiForwardSidecarCandidates, resolveFirstUsableOpenAiSidecar, type ExplicitOpenAiCallerAuth, type ResolvedOpenAiForwardSidecar } from "../../providers/openai-sidecar";
@@ -265,6 +271,7 @@ import type { AdapterRequest, ProviderAdapter } from "../../adapters/base";
 import { providerApiKeySelectionIsCurrent, resolveCurrentProviderApiKeyTransport } from "../../providers/api-key-selection";
 import {
   hasKeyPoolFailover,
+  selectProactiveApiKeyTransport,
   rateLimitRetryDelayMs,
   rateLimitRetryPolicyFor,
   rotateProviderTransportOn429,
@@ -290,6 +297,7 @@ import {
   upstreamErrorMessageFromPayload,
 } from "../../lib/errors";
 import type { AdmissionLease } from "../../lib/admission";
+import { tryClaimNativeMainProfileForTurn as tryClaimStoredSidecarMainProfile } from "../../codex/native-main-admission";
 import { prepareEffortNormalization, supportedLadderFor } from "../effort-policy";
 import { isThreadSpawnRequest } from "../effort-policy";
 import {
@@ -410,7 +418,7 @@ import {
   payloadRewriteAsBlockRewrite,
   relaySseWithBlockRewrite,
 } from "../sse-payload-rewrite";
-import { restoreRoutedCustomCalls, restoreRoutedCustomCallsInJson } from "../../responses/custom-tool-compat";
+import { hasUnmappedRoutedCustomToolOutput, restoreRoutedCustomCalls, restoreRoutedCustomCallsInJson } from "../../responses/custom-tool-compat";
 import { createRoutedCustomToolRestoreBlockRewrite } from "../responses-custom-tool-repair";
 import { collectFunctionCallRepairSchemas, repairFunctionCallsInJson } from "../../responses/function-call-compat";
 import { createResponsesFunctionToolRepairBlockRewrite } from "../responses-function-tool-repair";
@@ -424,10 +432,13 @@ import {
   type RoutedNamespaceToolAliases,
 } from "../../responses/namespace-tool-compat";
 import {
+  collectDeclaredBareWireToolNames,
   collectDeclaredNamelessClientCallTypes,
   collectDeclaredWireToolNames,
   collectProviderExecutedCallTypes,
   createUndeclaredToolCallGuardBlockRewrite,
+  normalizeDefaultNamespaceInJson,
+  normalizeDefaultNamespaceInResponse,
   currentTurnWireToolCatalogBody,
   hasExplicitWireToolCatalog,
   undeclaredToolCallMessage,
@@ -827,7 +838,8 @@ async function opaqueBlobRejectionBodyForRecovery(
   signal: AbortSignal,
 ): Promise<string | undefined> {
   if (
-    response.status < 400
+    isNonReplayableResponse(response)
+    || response.status < 400
     || (response.status >= 500 && response.status !== 502)
     || adapterName !== "openai-responses"
     || alreadyAttempted
@@ -1121,6 +1133,9 @@ export async function shouldRetryCodexPoolAccountQuota(
   response: Response,
   signal?: AbortSignal,
 ): Promise<boolean> {
+  // A post-send WebSocket gateway status must not become a second account's send; the
+  // body carries no quota evidence either, but the marker is the contract, not the prose.
+  if (isNonReplayableResponse(response)) return false;
   if (response.status === 402 || response.status === 429) return true;
   if (response.status < 500 || response.status >= 600) return false;
   try {
@@ -1136,6 +1151,28 @@ export async function shouldRetryCodexPoolAccountQuota(
   }
 }
 
+/**
+ * A pre-stream upstream 5xx another Codex account may still be able to serve.
+ *
+ * `server_is_overloaded` is the shape this exists for. The ChatGPT backend refuses in a few
+ * hundred milliseconds, the body carries no quota evidence, and nothing in that exchange is
+ * account health — so the pool keeps choosing the same account and every request fails on it
+ * while the other accounts sit idle. That is what an operator sees as the pool refusing to move.
+ *
+ * The status stays exactly as upstream sent it. `classifyCodexUpstreamOutcome` maps 5xx to the
+ * transient class, so the account earns an ordinary failure streak and `upstreamFailoverThreshold`
+ * decides when it is soft-avoided, rather than a quota cooldown it never earned.
+ *
+ * Deliberately narrow. {@link isNonReplayableResponse} still refuses: a post-send WebSocket
+ * gateway status means the body already reached the origin, so sending it from a second account
+ * could duplicate a turn the origin may still be running. A 5xx whose body confirms quota is not
+ * routed here either — {@link shouldRetryCodexPoolAccountQuota} classifies that one first and
+ * carries the cooldown with it.
+ */
+export function shouldRetryCodexPoolAccountTransient(response: Response): boolean {
+  return !isNonReplayableResponse(response) && isTransientUpstreamStatus(response.status);
+}
+
 interface CodexPoolAccountRetryArgs {
   /** Sanitized caller input, before any selected Pool credential was materialized. */
   callerAuthHeaders: Headers;
@@ -1310,6 +1347,21 @@ async function retryCodexPoolOnAlternateAccount(
   const inboundWire = options.inboundWire ?? "responses";
   const entitlementResolver = options.resolveCodexModelEntitlements ?? resolveCodexModelEntitlements;
   let retryAuthCtx: CodexAuthContext | undefined;
+  // A transient 5xx must record even when this request cannot move: the ordinary terminal
+  // recorder only fires for an OK event-stream body, so a pre-stream refusal would otherwise
+  // leave the account looking healthy no matter how many times it refused, and the pool would
+  // keep handing it the next request.
+  const recordUnmovedTransientOutcome = (): void => {
+    if (!isTransientUpstreamStatus(outcomeStatus)) return;
+    recordCodexUpstreamOutcome(config, firstAuthCtx.accountId, outcomeStatus, {
+      threadId: firstAuthCtx.affinityKey,
+      fixedAccount: firstAuthCtx.fixedAccount,
+      modelId: route.modelId,
+      probeLeaseId: codexProbeLeaseId(firstAuthCtx),
+      probeQuotaScope: codexProbeQuotaScope(firstAuthCtx),
+      writerGeneration: firstAuthCtx.writerGeneration,
+    });
+  };
   if (outcomeStatus === 400 && ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(route.modelId)) {
     invalidateCodexModelEntitlementsForAccount(firstAuthCtx.accountId);
     let refreshed;
@@ -1334,6 +1386,7 @@ async function retryCodexPoolOnAlternateAccount(
   // Exact account selectors may retry the same confirmed account above, but must never resolve
   // an alternate. Quota failures and a refreshed entitlement miss remain terminal.
   if (!retryAuthCtx && (firstAuthCtx.fixedAccount || args.sameAccountOnly === true)) {
+    recordUnmovedTransientOutcome();
     return { kind: "no-alternate" };
   }
   try {
@@ -1384,6 +1437,7 @@ async function retryCodexPoolOnAlternateAccount(
         writerGeneration: firstAuthCtx.writerGeneration,
       });
     }
+    recordUnmovedTransientOutcome();
     return { kind: "no-alternate" };
   }
 
@@ -1426,6 +1480,7 @@ async function retryCodexPoolOnAlternateAccount(
   const retryAdapter = resolveAdapter(
     resolveWireProtocolOverride(route.providerName, route.modelId, retryProvider, inboundWire),
     config.cacheRetention,
+    route.providerName,
   );
   bindRouteReasoningReplayScope({
     parsed,
@@ -1670,6 +1725,10 @@ export interface ConsumedComboFailure {
 
 
 export interface HandleResponsesOptions {
+  /** Internal Claude replay identity; consumed only by the final canonical Go transport. */
+  claudeGoAffinity?: { sessionLane?: string };
+  /** Validated Claude metadata identity; projected only into final canonical attempt headers. */
+  claudeNativeSessionId?: string;
   /** Original live policy owner; separate from caller-specific routing/sidecar snapshots. */
   codexAuthPolicy?: CodexAuthPolicyConfig;
   turnAdmissionLease?: AdmissionLease;
@@ -1728,6 +1787,8 @@ export interface HandleResponsesOptions {
   trustedClaudeMainAuth?: { authorization: string; chatgptAccountId?: string };
   /** Sidecar-only auth captured before route changes; null means no usable original pair. */
   openAiSidecarAuth?: ExplicitOpenAiCallerAuth | null;
+  /** Internal Chat bridge permission to obtain claimed stored auth only for a final Direct sidecar. */
+  allowStoredOpenAiSidecarAuth?: boolean;
   /** Original caller-owned native pair; separate from any claimed sidecar enrichment. */
   nativeCallerAuth?: ExplicitOpenAiCallerAuth | null;
   /** Caller Direct credential under Direct\'s own predicate; restored only for the canonical OpenAI final route. */
@@ -2037,6 +2098,15 @@ function canPassThroughEncryptedV2AgentTask(
   ).adapter === "openai-responses";
 }
 
+/** Keep synthesized Claude identity out of request headers reused by policy/combo fallback. */
+function withClaudeNativeSession(headers: Headers, provider: OcxProviderConfig, sessionId?: string): Headers {
+  if (!sessionId || !isCanonicalOpenAiForwardProvider(provider)
+    || headers.has("session_id") || headers.has("session-id") || headers.has("thread-id")) return headers;
+  const forwarded = new Headers(headers);
+  forwarded.set("session_id", sessionId);
+  return forwarded;
+}
+
 type ResponsesAuthResolution =
   | { ok: true; authCtx: CodexAuthContext; headers: Headers; callerAuthHeaders: Headers; substituteMainCredential: boolean }
   | { ok: false; response: Response };
@@ -2471,6 +2541,7 @@ async function applyFinalRouteRequestNormalization(args: {
   logCtx: RequestLogContext;
   inboundWire: InboundWire;
   inboundTransport?: "websocket";
+  claudeGoAffinity?: HandleResponsesOptions["claudeGoAffinity"];
 }): Promise<void> {
   const { parsed, route, config, req, logCtx, inboundWire, inboundTransport } = args;
   const effortSelector = prepareEffortNormalization(parsed, route);
@@ -2498,7 +2569,8 @@ async function applyFinalRouteRequestNormalization(args: {
 
   // Settle the wire once so logging, fast-mode, auth, and sidecars read the adapter
   // this request will actually use (#404).
-  route.provider = resolveOpenCodeGoTransport(route.provider, getOrAllocateRequestSessionLane(req));
+  route.provider = resolveOpenCodeGoTransport(route.provider,
+    args.claudeGoAffinity ? args.claudeGoAffinity.sessionLane : getOrAllocateRequestSessionLane(req));
   route.provider = resolveWireProtocolOverride(route.providerName, route.modelId, route.provider, inboundWire);
   if (preserveAnthropicResponseModel) parsed._responseModelId = responseModelId;
   logCtx.model = route.modelId;
@@ -3891,6 +3963,22 @@ async function handleResponsesInner(
     );
   }
 
+  if (hasUnexpandedPreviousResponse) {
+    const continuationProvider = resolveWireProtocolOverride(route.providerName, route.modelId, route.provider, inboundWire);
+    // Stateless destinations cannot resolve the omitted prefix. Stateful destinations may,
+    // but a lowered custom result still needs its call to recover the original wire type.
+    // Native function/custom continuations without lowering keep their upstream-owned state.
+    if (continuationProvider.adapter === "openai-responses"
+      && (continuationProvider.statelessResponses === true
+        || hasUnmappedRoutedCustomToolOutput(parsed._rawBody, continuationProvider.supportsResponsesCustomTools))) {
+      return formatErrorResponse(
+        400,
+        "previous_response_not_found",
+        "Routed continuation requires unavailable local history; resend the full conversation without previous_response_id.",
+      );
+    }
+  }
+
   // Captured before normalization: whether the CLIENT asked for SSE. The
   // transport-neutral upstream-streaming policy below may force a bounded JSON
   // upstream for reliability (#875); the answer must then be reframed to SSE
@@ -3904,6 +3992,7 @@ async function handleResponsesInner(
     logCtx,
     inboundWire,
     inboundTransport: options.inboundTransport,
+    claudeGoAffinity: options.claudeGoAffinity,
   });
   // Attribute local auth/cooldown failures to the public selector too; exact auth may fail before
   // the normal post-resolution provider label is assigned.
@@ -3965,8 +4054,8 @@ async function handleResponsesInner(
     const finalAuth = await resolveResponsesCodexAuth(req, config, route, options, credentialDomainWasRewritten);
     if (!finalAuth.ok) return finalAuth.response;
     authCtx = finalAuth.authCtx;
-    selectedForwardHeaders = finalAuth.headers;
-    callerAuthHeaders = finalAuth.callerAuthHeaders;
+    selectedForwardHeaders = withClaudeNativeSession(finalAuth.headers, route.provider, options.claudeNativeSessionId);
+    callerAuthHeaders = withClaudeNativeSession(finalAuth.callerAuthHeaders, route.provider, options.claudeNativeSessionId);
     substituteMainCredential = finalAuth.substituteMainCredential;
   }
 
@@ -4158,7 +4247,7 @@ async function handleResponsesInner(
       && credentialGeneration(row.credential) === binding.snapshot.generation;
   };
   const resolveSelectionAdapter = (provider: OcxProviderConfig, retention = config.cacheRetention): ProviderAdapter => {
-    const resolved = resolveAdapter(provider, retention);
+    const resolved = resolveAdapter(provider, retention, route.providerName);
     if (route.provider.authMode === "forward") return resolved;
     const binding: DispatchBinding | undefined = route.provider.authMode === "oauth"
       ? oauthSelection && servingOAuthSnapshot
@@ -4397,6 +4486,10 @@ async function handleResponsesInner(
         // whichever account is active by the time the response comes back (#2568).
         if (isGenericFailoverProvider(route.providerName, route.provider)) {
           genericFailoverAccountId = resolved.accountId;
+          // Advance the pool cursor only now that this account is actually admitted. The
+          // helper returns immediately unless the kernel is on AND the strategy is
+          // round-robin, so quota and fill-first pools reach it without being touched.
+          noteGenericPoolSelection(config, route.providerName, resolved.accountId);
         }
         // Anthropic is excluded from isGenericFailoverProvider -- its own pool owns affinity and
         // a fail-closed local-cli credential rule -- so without this stamp its identity is
@@ -4434,6 +4527,26 @@ async function handleResponsesInner(
       return formatErrorResponse(401, "authentication_error", publicOAuthAuthenticationErrorMessage(err));
     }
   }
+  // Key-auth twin of the OAuth preference above: pick a warm key BEFORE the first attempt when
+  // the committed one is already cooling, instead of spending the request earning a 429 the
+  // runtime could already predict. The picker refuses to override a healthy committed key and
+  // returns null without a configured strategy, so an ordinary install evaluates one predicate.
+  //
+  // It RETURNS a rebuilt route rather than mutating one, and the assignment has to land here --
+  // ahead of the transport pin below, the adapterProvider copy that follows it, and the request
+  // the HTTP path bakes later. The image bridge and web search read route.provider directly and
+  // have no stale-selection re-read to save them, so ordering is the whole correctness argument.
+  //
+  // The Transport variant, not the bare picker: the picker answers with the PERSISTED row, and
+  // a built-in provider stored in its valid minimal form would lose the adapter id, base URL
+  // and static headers registry backfill supplies, throwing `Unknown adapter: undefined`.
+  const proactiveKeyProvider = selectProactiveApiKeyTransport(
+    config,
+    route.providerName,
+    route.provider,
+    parsed.options.promptCacheKey,
+  );
+  if (proactiveKeyProvider) route.provider = proactiveKeyProvider;
   route.provider = resolveProviderTransport(
     route.providerName,
     route.provider,
@@ -4530,21 +4643,42 @@ async function handleResponsesInner(
   }
 
   let openAiSidecar: ResolvedOpenAiForwardSidecar | undefined;
-  const needsOpenAiVision = shouldResolveOpenAiVisionSidecar(config, route.provider, route.modelId, parsed);
-  const needsOpenAiSearch = shouldResolveOpenAiWebSearchSidecar(config, parsed, isPassthrough);
+  const visionDescribeTerminal = options.visionDescribeTerminal === true;
+  const routedCompaction = parsed._compactionRequest === true
+    && !isCanonicalOpenAiForwardProvider(route.provider);
+  const needsOpenAiVision = !visionDescribeTerminal
+    && shouldResolveOpenAiVisionSidecar(config, route.provider, route.modelId, parsed);
+  const needsOpenAiSearch = !routedCompaction && !adapter.runTurn
+    && shouldResolveOpenAiWebSearchSidecar(config, parsed, isPassthrough);
   if (needsOpenAiVision || needsOpenAiSearch) {
     try {
+      const candidates = listOpenAiForwardSidecarCandidates(config);
+      let sidecarAuth = options.openAiSidecarAuth;
+      if (!sidecarAuth && options.allowStoredOpenAiSidecarAuth === true
+        && route.codexAccountId === undefined
+        && candidates.some(candidate => candidate.accountMode === "direct")
+        && tryClaimStoredSidecarMainProfile(options.turnAdmissionLease)) {
+        // Request-local helper authority only: never promote this pair to caller, primary,
+        // or retry credentials. Claim before reading so profile switches remain fenced.
+        try {
+          const { getMainAccountToken } = await import("../../codex/main-account");
+          const token = getMainAccountToken();
+          if (token) sidecarAuth = captureExplicitOpenAiCallerAuth(new Headers({
+            authorization: `Bearer ${token.accessToken}`, "chatgpt-account-id": token.chatgptAccountId,
+          }), config);
+        } catch { /* stored enrichment is optional */ }
+      }
       // Preserve explicit OpenAI helper auth across route changes without returning it to
       // primary-provider headers or alternate-main retry. The resolver revalidates scope.
       const sidecarHeaders = new Headers(req.headers);
       sidecarHeaders.delete("authorization");
       sidecarHeaders.delete("chatgpt-account-id");
-      if (options.openAiSidecarAuth) {
-        sidecarHeaders.set("authorization", options.openAiSidecarAuth.authorization);
-        sidecarHeaders.set("chatgpt-account-id", options.openAiSidecarAuth.chatgptAccountId);
+      if (sidecarAuth) {
+        sidecarHeaders.set("authorization", sidecarAuth.authorization);
+        sidecarHeaders.set("chatgpt-account-id", sidecarAuth.chatgptAccountId);
       }
       openAiSidecar = await resolveFirstUsableOpenAiSidecar(
-        listOpenAiForwardSidecarCandidates(config),
+        candidates,
         sidecarHeaders,
         config,
         {
@@ -4579,7 +4713,6 @@ async function handleResponsesInner(
   // call must never plan another describe. The flag arrives from the Chat
   // surface (whose bridge rebuilds headers) or as the raw header for native
   // Responses callers. Marked + text-only routed model → strip, depth cap 1.
-  const visionDescribeTerminal = options.visionDescribeTerminal === true;
   const visionPlan = visionDescribeTerminal
     ? undefined
     : planVisionSidecar(config, route.provider, route.modelId, parsed, openAiSidecar, {
@@ -4641,10 +4774,16 @@ async function handleResponsesInner(
   // `compaction_trigger` item — only the canonical ChatGPT backend speaks that
   // contract. An API-key gateway would receive the trigger, answer with an ordinary
   // message, and leave Codex fataling on a missing compaction item (#422).
-  const routedCompaction = parsed._compactionRequest === true
-    && !isCanonicalOpenAiForwardProvider(route.provider);
-  const commitReasoningReplayServingRoute = (): void => {
+  const commitReasoningReplayServingRoute = (outboundHeaders?: HeadersInit): void => {
     commitReasoningReplayServingIdentity(parsed._reasoningReplayScope);
+    // History has no model namespace. Record the account that actually accepted this
+    // final attempt, after refresh/failover, rather than guessing from mutable affinity.
+    // Recording is relay state. With the feature off there is no relay, so building an owner
+    // registry for it is out of scope for this request.
+    if (outboundHeaders && isCanonicalOpenAiForwardProvider(route.provider) && contextRelayActivated()) {
+      recordContextSessionOwner(resolveContextPrincipal(req, config, options.admission), req.headers,
+        route.provider.baseUrl, authCtx, new Headers(outboundHeaders), substituteMainCredential);
+    }
   };
   if (routedCompaction) {
     delete parsed.context.tools;
@@ -4714,6 +4853,7 @@ async function handleResponsesInner(
     );
     const clientExplicitWireToolCatalog = hasExplicitWireToolCatalog(clientToolAuthorizationBody);
     const clientDeclaredWireToolNames = collectDeclaredWireToolNames(clientToolAuthorizationBody);
+    const clientDeclaredBareWireToolNames = collectDeclaredBareWireToolNames(clientToolAuthorizationBody);
     const clientDeclaredNamelessCallTypes = collectDeclaredNamelessClientCallTypes(
       clientToolAuthorizationBody,
     );
@@ -4789,6 +4929,7 @@ async function handleResponsesInner(
     };
     let outboundRequestBody: Record<string, unknown> | undefined;
     const declaredWireToolNames = new Set<string>();
+    const declaredBareWireToolNames = new Set<string>();
     const declaredNamelessClientCallTypes = new Set<string>();
     // `buildToolBridgeMaps` creates a bare alias only when the caller selected exactly one
     // namespaced tool through a bare tool_choice. Restore that request-bounded identity before
@@ -4838,12 +4979,17 @@ async function handleResponsesInner(
       // aliases are authoritative. A continuation's outbound body still contains historical
       // catalogs (and may promote historical tool-search definitions), so it can never widen the
       // current caller snapshot captured above.
+      declaredBareWireToolNames.clear();
       if (replayedInputPrefixLength === 0) {
         for (const name of collectDeclaredWireToolNames(outboundRequestBody)) {
           declaredWireToolNames.add(name);
         }
+        for (const name of collectDeclaredBareWireToolNames(outboundRequestBody)) {
+          declaredBareWireToolNames.add(name);
+        }
       }
       for (const name of clientDeclaredWireToolNames) declaredWireToolNames.add(name);
+      for (const name of clientDeclaredBareWireToolNames) declaredBareWireToolNames.add(name);
       declaredNamelessClientCallTypes.clear();
       if (replayedInputPrefixLength === 0) {
         for (const callType of collectDeclaredNamelessClientCallTypes(outboundRequestBody)) {
@@ -4936,6 +5082,7 @@ async function handleResponsesInner(
         declaredWireToolNames,
         declaredNamelessClientCallTypes,
         providerExecutedCallTypes,
+        declaredBareWireToolNames,
       ) !== undefined) {
         inspectionSawUndeclaredTool = true;
       }
@@ -4973,11 +5120,19 @@ async function handleResponsesInner(
           declaredWireToolNames,
           declaredNamelessClientCallTypes,
           providerExecutedCallTypes,
+          declaredBareWireToolNames,
         ) !== undefined
       ) {
         return;
       }
-      rememberPassthroughResponse?.(replayResponse);
+      const normalizedReplayResponse = (undeclaredToolGuardActive
+        ? normalizeDefaultNamespaceInResponse(
+            replayResponse,
+            declaredWireToolNames,
+            declaredBareWireToolNames,
+          ).value
+        : replayResponse) as typeof replayResponse;
+      rememberPassthroughResponse?.(normalizedReplayResponse);
       const firstCompletion = !inspectedCompletionSeen;
       inspectedCompletionSeen = true;
       if (firstCompletion && (inspectedTerminal === null || firstTerminalAllowsRecall)) {
@@ -5291,7 +5446,7 @@ async function handleResponsesInner(
       }
       authCtx = replay.authCtx;
       route.provider = replay.provider;
-      selectedForwardHeaders = replay.headers;
+      selectedForwardHeaders = withClaudeNativeSession(replay.headers, replay.provider, options.claudeNativeSessionId);
       const replayAdapter = resolveSelectionAdapter(
         resolveWireProtocolOverride(route.providerName, route.modelId, replay.provider, inboundWire),
         config.cacheRetention,
@@ -5618,6 +5773,10 @@ async function handleResponsesInner(
         // ChatGPT sometimes wraps quota exhaustion in a generic 5xx. Normalize only
         // body-confirmed cases to quota evidence so cooldown and rotation both apply.
         poolRetryOutcome = upstreamResponse.status >= 500 ? 429 : upstreamResponse.status;
+      } else if (!authCtx.fixedAccount && shouldRetryCodexPoolAccountTransient(upstreamResponse)) {
+        // A plain transient 5xx the same-account retry layer could not absorb. Keep the real
+        // status so it records as transient rather than quota.
+        poolRetryOutcome = upstreamResponse.status;
       }
 
       if (poolRetryOutcome !== undefined) {
@@ -5863,7 +6022,7 @@ async function handleResponsesInner(
       // For streamed passthrough, a successful terminal response means non-error upstream status
       // before relay starts. Waiting for SSE completion would retain request state across the whole
       // stream; a later body failure does not undo that this destination accepted and served the turn.
-      commitReasoningReplayServingRoute();
+      commitReasoningReplayServingRoute(request.headers);
       const terminalRepairPolicy = providerModelResponsesTerminalRepair(
         route.providerName,
         route.provider,
@@ -5998,6 +6157,7 @@ async function handleResponsesInner(
             declaredWireToolNames,
             declaredNamelessClientCallTypes,
             providerExecutedCallTypes,
+            declaredBareWireToolNames,
           )
           : undefined,
       ].filter((rewrite): rewrite is NonNullable<typeof rewrite> => rewrite !== undefined);
@@ -6198,7 +6358,7 @@ async function handleResponsesInner(
       }
       const text = bounded.text;
       inspectResponseLogJson(logCtx, text);
-      const clientJson = (() => {
+      let clientJson = (() => {
         const restoredNamespace = restoreRoutedNamespaceCallsInJson(
           scrubSelfNamedToolCallNamespaceInJson(
             restoreImageGenCallsInJson(text, imageGenCallAliases),
@@ -6244,6 +6404,7 @@ async function handleResponsesInner(
               declaredWireToolNames,
               declaredNamelessClientCallTypes,
               providerExecutedCallTypes,
+              declaredBareWireToolNames,
             );
           } catch {
             return undefined;
@@ -6252,8 +6413,13 @@ async function handleResponsesInner(
         if (undeclared !== undefined) {
           return formatErrorResponse(502, "upstream_error", undeclaredToolCallMessage(undeclared));
         }
+        clientJson = normalizeDefaultNamespaceInJson(
+          clientJson,
+          declaredWireToolNames,
+          declaredBareWireToolNames,
+        );
       }
-      commitReasoningReplayServingRoute();
+      commitReasoningReplayServingRoute(request.headers);
       try {
         rememberPassthroughResponseChecked(
           JSON.parse(text) as { id?: unknown; output?: unknown; status?: unknown; model?: unknown },
@@ -6335,7 +6501,7 @@ async function handleResponsesInner(
     }
     // An unclassified passthrough body is relayed directly and has no bounded completion observer;
     // use the same non-error-status success boundary as SSE instead of retaining per-stream state.
-    commitReasoningReplayServingRoute();
+    commitReasoningReplayServingRoute(request.headers);
     const body = relayWithAbort(upstreamResponse.body, upstream);
     const turnAc = new AbortController();
     const tracked = body ? trackStreamLifetime(body, turnAc, undefined, options.turnAdmissionLease) : null;
diff --git a/src/server/responses/ws-upstream.ts b/src/server/responses/ws-upstream.ts
index 87b3767d2b..b6799267d6 100644
--- a/src/server/responses/ws-upstream.ts
+++ b/src/server/responses/ws-upstream.ts
@@ -20,7 +20,7 @@ import { codexWsExchange } from "./codex-ws-exchange";
 import { CodexWsSession } from "./codex-ws-session";
 import { codexWsPool, codexWsReuseIdentity } from "./codex-ws-pool";
 import { codexWsCreateFrameExceedsLimit } from "./codex-ws-wire";
-export { CODEX_WS_RESPONSE_PRELUDE_TIMEOUT_MS, MAX_CODEX_WS_FRAME_BYTES, MAX_CODEX_WS_QUEUE_BYTES,
+export { CODEX_WS_LIVENESS_PING_INTERVAL_MS, CODEX_WS_RESPONSE_PRELUDE_TIMEOUT_MS, MAX_CODEX_WS_FRAME_BYTES, MAX_CODEX_WS_QUEUE_BYTES,
   MAX_CODEX_WS_CREATE_FRAME_BYTES, CODEX_WS_CREATE_FRAME_LIMIT_BYTES, codexWsCreateFrameExceedsLimit,
   isCodexWsQuotaObservedResponse, isCodexWsUpstreamResponse } from "./codex-ws-wire";
 export const MIN_BOUNDED_CODEX_WS_BUN_VERSION = "1.4.0";
diff --git a/src/server/zai-responses-startup.ts b/src/server/zai-responses-startup.ts
new file mode 100644
index 0000000000..e41ba06f5d
--- /dev/null
+++ b/src/server/zai-responses-startup.ts
@@ -0,0 +1,21 @@
+import { mutatePersistedConfig } from "../config";
+import { migrateZaiResponsesDefault } from "../providers/zai-responses-migration";
+import type { OcxConfig } from "../types";
+
+/** Rebase the one-time Z.AI wire upgrade before initializing any live config consumers. */
+export function migrateStartupZaiResponses(config: OcxConfig): OcxConfig {
+  const projection = { ...config };
+  if (!migrateZaiResponsesDefault(projection)) return config;
+  try {
+    const outcome = mutatePersistedConfig(fresh => ({
+      changed: migrateZaiResponsesDefault(fresh),
+      value: fresh,
+    }));
+    if (outcome.status !== "unavailable") return outcome.value;
+    console.warn(`[zai-responses-migration] Persistence unavailable (${outcome.reason}); using Responses in memory only.`);
+  } catch {
+    // Filesystem errors can carry private paths. Startup must still remain available.
+    console.warn("[zai-responses-migration] Persistence failed; using Responses in memory only.");
+  }
+  return projection;
+}
diff --git a/src/types/config.ts b/src/types/config.ts
index 499ca59eb1..52c4ed8b0e 100644
--- a/src/types/config.ts
+++ b/src/types/config.ts
@@ -6,6 +6,12 @@ import type { CodexAccount } from "./accounts";
  * /v1/messages surface, the `ocx claude` launcher, and the GUI Claude page.
  */
 export interface OcxClaudeCodeConfig {
+  /**
+   * Opt-in relocation of supported trailing Claude harness notices from system instructions
+   * to a user input message on translated routes. Changes the Desktop cache-key prefix.
+   * Default: false; only literal true enables it. Native passthrough is unchanged.
+   */
+  stabilizePromptCache?: boolean;
   /** Opt-in translated Messages admission; unset keeps legacy behavior. Native passthrough is exempt. */
   compatibility?: "shadow" | "enforce";
   /** Kill switch for the /v1/messages inbound (GUI "Claude ON" toggle). Default: enabled. */
@@ -601,7 +607,9 @@ export interface OcxConfig {
   /**
   * Shadow call intercept: redirect Codex's hard-coded helper calls (title generation,
   * commit messages, skill orchestration) to a user-chosen model. Default intercepted
-  * source models: gpt-5.4-mini (older clients) and gpt-5.6-luna (Codex 0.145.0+).
+  * source model: gpt-5.6-luna (Codex 0.145.0+). Clients through 0.144.x emitted
+  * gpt-5.4-mini instead; that model is retired upstream, but it stays available as an
+  * opt-in `sourceModels` prefix so an old client's helper calls can still be intercepted.
   * Opt-in; disabled by default. Matching requests preserve their configured reasoning effort.
   * All requests for configured shadow source models are intercepted regardless of request kind,
   * except when the replacement intersects the same provider+model source set.
@@ -611,7 +619,7 @@ export interface OcxConfig {
    enabled?: boolean;
    /** Replacement model id (e.g. "gpt-5.5"). */
    model?: string;
-   /** Optional override of intercepted source-model prefixes (default: gpt-5.4-mini, gpt-5.6-luna). */
+   /** Optional override of intercepted source-model prefixes (default: gpt-5.6-luna). */
    sourceModels?: string[];
  };
   /**
@@ -831,6 +839,28 @@ export interface OcxConfig {
    * spends a second credit. A malformed value reads as off.
    */
   resetCreditAutoRedeem?: { enabled?: boolean; leadTimeMinutes?: number };
+  /**
+   * Shared account-pool kernel, opt-in and off by default.
+   *
+   * `kernel: true` is what makes a generic OAuth provider's stored `strategy` and
+   * `autoSwitchThreshold` actually select an account instead of merely being persisted.
+   * Off restores the pre-kernel path exactly, which is why the DTO keeps reporting
+   * `inert: true` until this is on. A malformed value reads as off.
+   */
+  pool?: {
+    kernel?: boolean;
+    /**
+     * Opt-in cache-affinity ordering, off by default.
+     *
+     * With it on, a bound Codex thread keeps its account until that account genuinely cannot
+     * serve, instead of moving the moment usage crosses `autoSwitchThreshold`. Moving a live
+     * conversation throws away the prompt cache warmed on that account, and a threshold
+     * crossing is a hint rather than evidence the account is spent. Separate from `kernel`
+     * on purpose: that one governs the generic OAuth strategy consumer, and one switch
+     * carrying two unrelated meanings cannot be turned on alone.
+     */
+    cacheAffinity?: boolean;
+  };
   /** Active pool account id for next session. undefined = main (passthrough as-is). */
   activeCodexAccountId?: string;
   /** Auto-switch threshold (0-100). Default 80. 0 = disabled. */
@@ -1100,7 +1130,7 @@ export interface OcxTokenGuardianConfig {
   codexWarmupEnabled?: boolean;
   /** Max age before a Codex pool account is revalidated via `/codex/responses`. Default 691200 (8d). */
   codexWarmupMaxAgeSeconds?: number;
-  /** Model used for optional Codex pool warmup. Default gpt-5.4-mini. */
+  /** Model used for optional Codex pool warmup. Default gpt-5.6-luna. */
   codexWarmupModel?: string;
 }
 
diff --git a/src/types/provider.ts b/src/types/provider.ts
index 0beb5d3371..d559ffef8f 100644
--- a/src/types/provider.ts
+++ b/src/types/provider.ts
@@ -272,6 +272,17 @@ export interface OcxProviderConfig {
    * the legacy `/v1/responses` construction.
    */
   responsesPath?: string;
+  /**
+   * Optional relative send path for the `openai-chat` wire, mirroring `responsesPath`.
+   * Same shape rules: must start with `/`, no URL scheme, query string, or fragment.
+   * When omitted the adapter keeps `openaiChatCompletionsUrl(baseUrl)`.
+   *
+   * This exists because a per-model wire override swaps `adapter` and leaves `baseUrl`
+   * alone, so an upstream that serves Chat Completions and Responses under different
+   * path prefixes cannot be reached by the adapter swap by itself. Z.AI is that case:
+   * `/api/v1/responses` and `/api/coding/paas/v4/chat/completions` on one host and one key.
+   */
+  chatCompletionsPath?: string;
   /**
    * Command Code protocol version sent as `x-command-code-version` on /alpha/generate requests.
    * The internal endpoint's schema drifts with the CLI version; operators can pin a known-good
@@ -281,8 +292,8 @@ export interface OcxProviderConfig {
   /**
    * Responses upstream that stores nothing server-side (DeepSeek documents "the API
    * is stateless"). Stateful request parameters are dropped, `store` is pinned false,
-   * and orphaned tool results left by a replay miss are repaired rather than
-   * forwarded to an upstream that cannot resolve their pair.
+   * and missing local continuation history returns previous_response_not_found so
+   * clients can resend full input. Explicit input still receives orphan-item repair.
    */
   statelessResponses?: boolean;
   /**
@@ -387,6 +398,16 @@ export interface OcxProviderConfig {
    * `apiKey` seeds a one-entry pool on first management touch.
    */
   apiKeyPool?: Array<{ id: string; key: string; label?: string; addedAt?: number }>;
+  /**
+   * Optional proactive ordering for `apiKeyPool` when the committed key is already
+   * cooling. Deliberately NOT named like the OAuth `accountPoolStrategy`: an API key
+   * is a different identity from an OAuth account set, and key rotation is a
+   * rate-limit scheduling problem rather than a prompt-cache one.
+   *
+   * Absent means today's behaviour: no pre-dispatch pick at all, only the reactive
+   * 429/401 walk in `key-failover`.
+   */
+  apiKeyPoolStrategy?: "round-robin" | "fill-first" | "quota";
   /** Changes on manual selection (including re-selection) and committed automatic allocation. */
   apiKeySelectionRevision?: string;
   /** Runtime only. Never expose in management responses or persist a routed provider. */
@@ -511,11 +532,21 @@ export interface OcxProviderConfig {
     enabled?: boolean;
     /**
      * Generic OAuth pool selection strategy (#695). Persisted through the pool-settings
-     * contract; the selector does not consume it yet, so omitted keeps today's behavior.
+     * contract. Consumed by the selector only while `pool.kernel` is on; with the flag off
+     * it is still merely persisted, so omitted and set behave the same.
      */
     strategy?: "quota" | "round-robin" | "fill-first";
-    /** 0-100 usage percent at which a proactive switch may be considered (#695); inert today. */
+    /**
+     * 0-100 usage percent at which fill-first advances off the active account (#695).
+     * Read only under `pool.kernel` with `strategy: "fill-first"`; 80 when unset, matching
+     * the Codex and Anthropic pools.
+     */
     autoSwitchThreshold?: number;
+    /**
+     * Successful dispatches retained on one round-robin selection. Default 1; range 1..100.
+     * Read only under `pool.kernel` with `strategy: "round-robin"`.
+     */
+    stickyLimit?: number;
   };
   /** Allow an explicitly key/oauth provider to run without a credential (for keyless local proxies). */
   keyOptional?: boolean;
@@ -589,6 +620,12 @@ export interface OcxProviderConfig {
   xaiResponsesXSearch?: boolean;
   /** One-time Grok subscription wire upgrade; later explicit Chat choices remain authoritative. */
   xaiResponsesDefaultVersion?: number;
+  /**
+   * One-time Z.AI coding-plan wire upgrade. The router already canonicalizes the `zai` row onto the
+   * Responses destination at request time; the marker records that the saved row was rewritten to
+   * match, so a later explicit Chat choice is not re-migrated on the next boot.
+   */
+  zaiResponsesDefaultVersion?: number;
   /**
    * Whether the Responses upstream accepts native custom tools and custom_tool_call items.
    * Set false only for a provider whose native contract rejects them; absence preserves
@@ -641,6 +678,19 @@ export interface OcxProviderConfig {
    * per-model compatibility escape hatch for mixed-capability gateways.
    */
   noStructuredOutputModels?: string[];
+  /**
+   * Model ids whose Chat Completions endpoint rejects `response_format` of type
+   * `json_schema` specifically. Such a request is downgraded to
+   * `{ type: "json_object" }` instead of being dropped, so a client that asked for
+   * JSON still gets JSON rather than prose — at the cost of the schema itself, which
+   * the upstream would have rejected anyway.
+   *
+   * Deliberately narrower than `noStructuredOutputModels`: that field claims the
+   * endpoint rejects the whole `response_format` field, which is a strictly stronger
+   * claim than any reported upstream error supports for these gateways. When a model
+   * appears in both lists the stronger opt-out wins and the field is omitted entirely.
+   */
+  noJsonSchemaModels?: string[];
   /**
    * Model ids that accept a reasoning-effort field on an ordinary turn but reject it
    * once function tools are present. The model keeps its advertised effort ladder;
diff --git a/src/types/request.ts b/src/types/request.ts
index 1c6a5294da..480a0509ad 100644
--- a/src/types/request.ts
+++ b/src/types/request.ts
@@ -100,7 +100,7 @@ export interface OcxParsedRequest {
   /**
    * The hosted `{type:"web_search", ...}` tool config, stashed when Codex enables web search. Routed
    * (non-OpenAI) providers can't run it server-side, so the proxy re-exposes it as a function tool and
-   * executes searches via the gpt-5.4-mini sidecar (see src/web-search). Absent when not requested.
+   * executes searches via the gpt-5.6-luna sidecar (see src/web-search). Absent when not requested.
    */
   _webSearch?: Record<string, unknown>;
   /** Hosted image_generation tool config stashed for the image bridge sidecar (see src/images). */
diff --git a/src/types/tools.ts b/src/types/tools.ts
index bb91ebe63f..7a4cdc4ebb 100644
--- a/src/types/tools.ts
+++ b/src/types/tools.ts
@@ -13,7 +13,7 @@ export interface OcxTool {
   loadedFromToolSearch?: boolean;
   /** Cursor-only synthetic exact-match edit tool; never inferred from the wire name. */
   cursorStructuredEdit?: true;
-  /** Synthetic web_search tool: the model's call is executed by the gpt-5.4-mini sidecar, not relayed to Codex. */
+  /** Synthetic web_search tool: the model's call is executed by the gpt-5.6-luna sidecar, not relayed to Codex. */
   webSearch?: boolean;
   /** Synthetic image_gen tool: the model's call is executed by the xAI image bridge sidecar, not relayed to Codex. */
   imageGeneration?: boolean;
@@ -66,22 +66,52 @@ const CODE_MODE_HELPER_TOOL_NAMES = [
  */
 export const CODE_MODE_EXEC_TOOL_NAME = "exec";
 
+/**
+ * Normalizes provider-emitted tool names against declared tool catalogs.
+ *
+ * Rewrites invented `default.<name>` prefixes back to a declared bare tool when that bare tool
+ * is declared and neither `default.<name>` nor `default__<name>` was explicitly declared (#4176).
+ * Also normalizes legacy helper names (`exec_command`, `shell_command`, `apply_patch`) to
+ * `exec` when code-mode `exec` is declared in the request catalog.
+ *
+ * @param name - The tool name emitted on the wire by the provider.
+ * @param declared - All wire tool names declared in the request catalog, including aliases.
+ * @param declaredBare - Explicitly declared bare tool names without namespace provenance.
+ *                       When omitted, falls back to `declared`.
+ * @returns The normalized tool name to expose downstream.
+ */
 export function normalizeDeclaredToolName(
   name: string,
   declared: ReadonlySet<string> | undefined,
+  declaredBare?: ReadonlySet<string>,
 ): string {
-  if (!declared || !declared.has(CODE_MODE_EXEC_TOOL_NAME)) return name;
+  if (!declared) return name;
   if (declared.has(name)) return name;
-  if (name === "apply_patch") return CODE_MODE_EXEC_TOOL_NAME;
+  let candidate = name;
+  if (name.startsWith("default.")) {
+    const bare = name.slice("default.".length);
+    const bareDeclared = declaredBare ?? declared;
+    if (
+      bare.length > 0
+      && bareDeclared.has(bare)
+      && !declared.has("default." + bare)
+      && !declared.has("default__" + bare)
+    ) {
+      candidate = bare;
+    }
+  }
+  if (!declared.has(CODE_MODE_EXEC_TOOL_NAME)) return candidate;
+  if (declared.has(candidate)) return candidate;
+  if (candidate === "apply_patch") return CODE_MODE_EXEC_TOOL_NAME;
   // When the catalog explicitly declares any legacy shell bridge name, the environment
   // genuinely exposes that tool — turn normalization off so a call is never mis-routed
   // to `exec`.
   if ((LEGACY_SHELL_BRIDGE_TOOL_NAMES as readonly string[]).some(legacy => declared.has(legacy))) {
-    return name;
+    return candidate;
   }
-  return (CODE_MODE_HELPER_TOOL_NAMES as readonly string[]).includes(name)
+  return (CODE_MODE_HELPER_TOOL_NAMES as readonly string[]).includes(candidate)
     ? CODE_MODE_EXEC_TOOL_NAME
-    : name;
+    : candidate;
 }
 
 /**
diff --git a/src/update/job.ts b/src/update/job.ts
index b7e51ff8c5..16310cad82 100644
--- a/src/update/job.ts
+++ b/src/update/job.ts
@@ -983,6 +983,11 @@ export interface RestartIo {
   spawnStart?: (job: UpdateJobState, installer: Installer, port?: number, launcher?: string) => void;
   /** The package launcher verified after a pnpm group switch or rollback. */
   packageLauncherPathFn?: () => string;
+  /** Exercise pinned-start retries without spawning, reclaiming, or killing real processes. */
+  spawnDetachedStartFn?: typeof spawnDetachedStart;
+  preparePortForPinnedStartFn?: typeof preparePortForPinnedStart;
+  waitForGhostListenClearFn?: typeof waitForGhostListenClear;
+  killProxyFn?: typeof killProxy;
   serviceInstalledFn?: () => boolean;
   /**
    * After a service reinstall exits 0, only trust the service path when this is true.
@@ -1332,9 +1337,20 @@ async function restartAfterUpdate(
     }
   }
   const attempts = 3;
+  const now = io.now ?? (() => Date.now());
+  const spawnPinnedStart = io.spawnDetachedStartFn ?? spawnDetachedStart;
+  const preparePort = io.preparePortForPinnedStartFn ?? preparePortForPinnedStart;
+  const waitForGhost = io.waitForGhostListenClearFn ?? waitForGhostListenClear;
   // Longer than published hard-pin reclaim (30s) so a slow start can still report healthy.
   const perAttemptHealthMs = 70_000;
   let lastChild: ChildProcess | null = null;
+  const killSpawnAttempt = (child: ChildProcess | null): void => {
+    // A numeric PID can be reused once this particular child has exited.
+    if (!child?.pid || child.exitCode !== null || child.signalCode !== null) return;
+    if (aliveFn(child.pid)) {
+      try { (io.killProxyFn ?? killProxy)(child.pid); } catch { /* best-effort */ }
+    }
+  };
   for (let attempt = 1; attempt <= attempts; attempt++) {
     if (attempt > 1) {
       updateJob(
@@ -1343,13 +1359,11 @@ async function restartAfterUpdate(
         `Pinned start attempt ${attempt - 1} did not become healthy on port ${port}; `
           + `retrying (${attempt}/${attempts}).`,
       );
-      if (lastChild?.pid && aliveFn(lastChild.pid)) {
-        try { killProxy(lastChild.pid); } catch { /* best-effort */ }
-      }
+      killSpawnAttempt(lastChild);
       lastChild = null;
     }
-    preparePortForPinnedStart(job, port, listPids, aliveFn, verifyOcx);
-    const ready = await waitForGhostListenClear(
+    preparePort(job, port, listPids, aliveFn, verifyOcx);
+    const ready = await waitForGhost(
       port,
       hostname,
       listPids,
@@ -1365,17 +1379,25 @@ async function restartAfterUpdate(
       );
       continue;
     }
-    lastChild = spawnDetachedStart(job, job.installer, port, launcher);
-    const healthDeadline = Date.now() + perAttemptHealthMs;
-    while (Date.now() < healthDeadline) {
+    const child = spawnPinnedStart(job, job.installer, port, launcher);
+    lastChild = child;
+    const retireChild = () => {
+      if (lastChild === child) lastChild = null;
+      child.removeListener("exit", retireChild);
+      child.removeListener("error", retireChild);
+      child.removeListener("close", retireChild);
+    };
+    child.once("exit", retireChild);
+    child.once("error", retireChild);
+    child.once("close", retireChild);
+    const healthDeadline = now() + perAttemptHealthMs;
+    while (now() < healthDeadline) {
       if (await probe(port, hostname)) return;
       await sleep(500);
     }
   }
   // Exhausted retries: do not leave a hung pinned-start child owning the port.
-  if (lastChild?.pid && aliveFn(lastChild.pid)) {
-    try { killProxy(lastChild.pid); } catch { /* best-effort */ }
-  }
+  killSpawnAttempt(lastChild);
 }
 
 /** Compact listen-holder summary for update-job logs when reclaim fails. */
diff --git a/src/vision/plan.ts b/src/vision/plan.ts
index 3cb0b2f3e2..fb2aae6d49 100644
--- a/src/vision/plan.ts
+++ b/src/vision/plan.ts
@@ -11,7 +11,7 @@ import { resolveSidecarAuth } from "../sidecar/auth";
 import { DEFAULT_VISION_TIMEOUT_MS, MAX_VISION_TIMEOUT_MS, MIN_VISION_TIMEOUT_MS } from "./timeout-bounds";
 import { carriesImages } from "./image-rewrite";
 
-const DEFAULT_VISION_MODEL = "gpt-5.4-mini";
+const DEFAULT_VISION_MODEL = "gpt-5.6-luna";
 const DEFAULT_ANTHROPIC_VISION_MODEL = "claude-sonnet-5";
 const DEFAULT_REASONING: VisionReasoningEffort = "low";
 export const DEFAULT_MAX_DESCRIPTIONS_PER_TURN = 8;
@@ -92,6 +92,20 @@ function messagesHaveImage(parsed: OcxParsedRequest): boolean {
     carriesImages(m.role) && Array.isArray(m.content) && (m.content as OcxContentPart[]).some(p => p.type === "image"));
 }
 
+/** Shared by auth admission and planning so a routed describer never borrows OpenAI auth. */
+function usableRoutedVisionModel(config: OcxConfig): string | undefined {
+  const cfg = config.visionSidecar;
+  if (cfg?.backend !== "routed") return undefined;
+  const routedModel = cfg.model;
+  const sep = routedModel ? routedModel.indexOf("/") : -1;
+  if (!routedModel || sep <= 0) return undefined;
+  const targetProvider = routedModel.slice(0, sep);
+  const targetId = routedModel.slice(sep + 1);
+  const targetProviderConfig = config.providers?.[targetProvider];
+  return modelAcceptsImageInput(config, { provider: targetProvider, id: targetId }) !== false
+    && !(targetProviderConfig && isModelTextOnly(targetProviderConfig, targetId)) ? routedModel : undefined;
+}
+
 export function shouldResolveOpenAiVisionSidecar(
   config: OcxConfig,
   provider: OcxProviderConfig,
@@ -101,6 +115,7 @@ export function shouldResolveOpenAiVisionSidecar(
   if (!isModelTextOnly(provider, modelId) || !messagesHaveImage(parsed)) return false;
   const cfg = config.visionSidecar ?? {};
   if (cfg.enabled === false) return false;
+  if (usableRoutedVisionModel(config)) return false;
   return resolveVisionBackend(cfg.backend, findAnthropicVisionProvider(config)) === "openai";
 }
 
@@ -140,43 +155,31 @@ export function planVisionSidecar(
   // fence: the target must not be provably blind, and must not itself be a
   // model this planner would re-enter for (belt; the terminal marker on the
   // loopback request is the braces).
-  if (cfg.backend === "routed") {
-    const routedModel = cfg.model;
-    const sep = routedModel ? routedModel.indexOf("/") : -1;
-    if (routedModel && sep > 0) {
-      const targetProvider = routedModel.slice(0, sep);
-      const targetId = routedModel.slice(sep + 1);
-      const targetProviderConfig = config.providers?.[targetProvider];
-      const targetVisible = modelAcceptsImageInput(config, { provider: targetProvider, id: targetId }) !== false
-        && !(targetProviderConfig && isModelTextOnly(targetProviderConfig, targetId));
-      if (targetVisible) {
-        return {
-          backend: "routed",
-          routedModel,
-          routedConfig: {
-            port: config.port,
-            ...(config.apiKeys ? { apiKeys: config.apiKeys } : {}),
-            // The self-fetch has to honor the unauthenticated loopback listener AND, with no
-            // listener, the bind address — so BOTH fields the destination resolver reads have to
-            // survive the narrowing or it silently resolves to the wrong local socket (#4236).
-            ...(config.hostname ? { hostname: config.hostname } : {}),
-            ...(config.unauthenticatedLoopbackListener
-              ? { unauthenticatedLoopbackListener: config.unauthenticatedLoopbackListener }
-              : {}),
-          },
-          settings: {
-            model: routedModel,
-            reasoning: DEFAULT_REASONING,
-            timeoutMs: resolveVisionTimeoutMs(cfg.timeoutMs),
-          },
-          maxDescriptionsPerTurn: resolveMaxDescriptionsPerTurn(cfg.maxDescriptionsPerTurn),
-        };
-      }
-    }
-    // Misconfigured routed backend (bare id, unknown provider, or provably
-    // blind target): fall through to the legacy default order below rather
-    // than dispatching a describe that cannot work.
+  const routedModel = usableRoutedVisionModel(config);
+  if (routedModel) {
+    return {
+      backend: "routed",
+      routedModel,
+      routedConfig: {
+        port: config.port,
+        ...(config.apiKeys ? { apiKeys: config.apiKeys } : {}),
+        // The self-fetch has to honor the unauthenticated loopback listener AND, with no
+        // listener, the bind address — so BOTH fields the destination resolver reads have to
+        // survive the narrowing or it silently resolves to the wrong local socket (#4236).
+        ...(config.hostname ? { hostname: config.hostname } : {}),
+        ...(config.unauthenticatedLoopbackListener
+          ? { unauthenticatedLoopbackListener: config.unauthenticatedLoopbackListener }
+          : {}),
+      },
+      settings: {
+        model: routedModel,
+        reasoning: DEFAULT_REASONING,
+        timeoutMs: resolveVisionTimeoutMs(cfg.timeoutMs),
+      },
+      maxDescriptionsPerTurn: resolveMaxDescriptionsPerTurn(cfg.maxDescriptionsPerTurn),
+    };
   }
+  // A non-dispatchable routed configuration keeps the legacy backend fallback below.
 
   const anthropicSidecar = findAnthropicVisionProvider(config);
   const backend = resolveVisionBackend(cfg.backend, anthropicSidecar);
diff --git a/src/web-search/index.ts b/src/web-search/index.ts
index e6bb7e3dbe..8b73b95645 100644
--- a/src/web-search/index.ts
+++ b/src/web-search/index.ts
@@ -201,6 +201,7 @@ export function shouldResolveOpenAiWebSearchSidecar(
   isPassthrough: boolean,
 ): boolean {
   if (!parsed._webSearch || isPassthrough) return false;
+  if (!toolChoiceToolPredicate(parsed.options.toolChoice)(buildWebSearchTool())) return false;
   const cfg = config.webSearchSidecar ?? {};
   return cfg.enabled !== false && resolveSidecarBackend(cfg.backend) === "openai";
 }
diff --git a/structure/02_config-and-codex-home.md b/structure/02_config-and-codex-home.md
deleted file mode 100644
index d7aa214a43..0000000000
--- a/structure/02_config-and-codex-home.md
+++ /dev/null
@@ -1,514 +0,0 @@
-# Config And Codex Home SOT
-
-## Codex home
-
-`src/codex/paths.ts` resolves Codex state from `CODEX_HOME` when set and valid, otherwise from
-`~/.codex`. An unset `CODEX_HOME` falls back to `~/.codex`, including WSL discovery. An explicitly
-set path that is unreadable or not a directory is an error, not a fallback: silently using a
-different home than the operator named would write provider state where nobody is looking for it.
-The managed files are:
-
-```text
-$CODEX_HOME/config.toml
-$CODEX_HOME/opencodex.config.toml
-$CODEX_HOME/opencodex-catalog.json
-$CODEX_HOME/opencodex-journal.json
-$CODEX_HOME/models_cache.json
-$CODEX_HOME/.opencodex-native-main-profiles/
-```
-
-Never assume macOS-only paths. Windows, service installs, and app-launched Codex can all depend on
-the resolved `CODEX_HOME`.
-
-Journal restoration compares config and profile independently against their saved originals and
-recorded injected hashes. If either changed artifact lacks its injected hash, the config/profile
-pair and journal remain untouched and the result is explicitly unverified; callers must not
-convert that refusal into successful fallback cleanup. Already-original bytes need no rewrite,
-and absence is distinct from an empty file. The injector checks a retained hashless journal against
-the same `baselineContent` it snapshots, plus the current profile, before writing or assigning a new
-injected hash. Native content can establish a fresh snapshot; routed content cannot promote an
-unverified older original. Existing hash-backed edit preservation and external-provider opt-out
-remain separate paths.
-
-The source-built Docker image explicitly keeps `CODEX_HOME=/home/bun/.codex` separate
-from `OPENCODEX_HOME=/home/bun/.opencodex`. Compose persists them in `codex-state` and
-`ocx-state` respectively, retaining a read-only root. The image creates owner-only
-writable homes for `bun`; existing volume ownership and permissions are not repaired.
-The catalog resolver is unchanged; a writable empty home is not a materialized catalog.
-
-[Decision Log]
-- 목적과 의도: Make the container's catalog location persistent and writable without changing native home semantics.
-- 기존 구현 및 제약 조건: Compose persisted only the OCX home, leaving Codex state on a read-only root; both products use incompatible auth.json formats.
-- 검토한 주요 대안: Merge the homes, nest Codex under an existing volume with a new startup initializer, or persist the existing separate Codex home.
-- 선택한 방식: Add a separate codex-state volume and create both owner-only directories in the image.
-- 다른 대안 대신 이 방식을 선택한 이유: It preserves existing paths, avoids credential-file collisions, and works when an older ocx-state volume hides the image's seeded directory tree.
-- 장점, 단점 및 영향: Two volumes must be backed up, but no automatic credential migration or runtime resolver change is needed. Catalog import/materialization remains an explicit prerequisite.
-
-`docker compose down` retains both volumes. `docker compose down --volumes` deletes
-both `ocx-state` and `codex-state`, including their credentials and catalog/state;
-treat it as destructive, not as an upgrade or restart command.
-
-Service install-state ownership uses this same resolver. In WSL, an unset `CODEX_HOME` may resolve
-to the single discoverable Windows Desktop home; recording Linux `~/.codex` instead would make a
-later repair or uninstall look foreign even though the service and runtime were started from the
-same environment. An explicit `CODEX_HOME` remains authoritative, and existing foreign ownership
-records are never migrated implicitly.
-
-[Decision Log]
-- 목적과 의도: Keep service ownership metadata aligned with the Codex home the proxy actually uses.
-- 기존 구현 및 제약 조건: The runtime performed narrow WSL Windows-home discovery, while service state used `CODEX_HOME || ~/.codex`.
-- 검토한 주요 대안: Bake `CODEX_HOME` into every service, migrate old state automatically, or reuse the runtime resolver.
-- 선택한 방식: Resolve service install and comparison state through the existing runtime Codex-home resolver.
-- 다른 대안 대신 이 방식을 선택한 이유: It preserves explicit overrides and the existing WSL ambiguity rules without rewriting user environment or foreign state.
-- 장점, 단점 및 영향: New installs and same-environment repairs agree with runtime targeting; genuinely foreign or ambiguous state remains fail-closed.
-
-SQLite-backed thread state may live outside `CODEX_HOME`. The one resolver in `src/codex/paths.ts`
-uses Codex's precedence: root `sqlite_home` in the effective `config.toml`, then
-`CODEX_SQLITE_HOME`, then the effective `CODEX_HOME`; relative SQLite homes resolve from the current
-working directory. History jobs resolve the database and its hashed backup identity together at
-call time, and admission/residue checks consume the same database path. Storage retention still
-owns the Codex-home tree separately and does not gain deletion authority over an external SQLite
-root from this resolver alone. Durable service launchers preserve an explicitly supplied
-`CODEX_SQLITE_HOME` so a background service resolves the same split state as the installing shell.
-An absent `config.toml` or absent root `sqlite_home` permits the environment/home fallback. Any
-other read failure, malformed TOML, wrong-typed or blank `sqlite_home` is indeterminate and fails
-closed so history code cannot select a different database by accident. This strict parse is scoped
-to SQLite ownership; the tolerant root-string helper used by injection and catalog reads is unchanged.
-
-[Decision Log]
-- 목적과 의도: Make every history safety check and mutation address the SQLite database Codex actually opened.
-- 기존 구현 및 제약 조건: History code rebuilt `CODEX_HOME/state_5.sqlite`, while Codex supports a config or environment-selected SQLite root for split Windows/WSL layouts.
-- 검토한 주요 대안: Copy the database into CODEX_HOME, teach only the writer about the override, or centralize the call-time target.
-- 선택한 방식: Add one Codex-compatible SQLite resolver, fail closed when its authoritative config is unreadable or its present `sqlite_home` cannot be parsed as a non-empty string, and share it across history jobs, provider defaults, admission, and residue classification.
-- 다른 대안 대신 이 방식을 선택한 이유: A writer-only override would let ownership checks authorize one database while the mutation touched another.
-- 장점, 단점 및 영향: Split-home history remains correct and backup identities stay database-specific; storage cleanup of an external root remains out of scope.
-
-Native-main profile ownership is bound to the real `CODEX_HOME`, not to an OpenCodex instance.
-Its encrypted vault, transaction journal, recovery marker, and referenced quarantine files live in
-the owner-only `.opencodex-native-main-profiles` directory. The unchanged
-`.opencodex-native-profile.lock.sqlite` beside that directory serializes every process sharing the
-home. Only plaintext login staging is instance-local under
-`$OPENCODEX_HOME/native-main-profile-staging`; a stage from one instance is invalid in another.
-These paths and the OS keyring are owner-only: the operating-system account that owns them is the
-trust boundary and already has direct access to active native credentials. OpenCodex detects and
-fails closed on file identities that change during an operation, but it does not claim isolation
-from a malicious process already running as that same trusted OS account.
-
-Startup and the periodic stage cleaner do not acquire the profile transaction lock when both the
-stage registry and this instance's staging tree are proven absent. This keeps an unused profile
-subsystem from fencing native traffic or creating lock contention. Presence, an unsafe entry type,
-or any observation error still takes the locked sweep and fails closed; the fast path is based only
-on proven absence, never on an unreadable path.
-
-[Decision Log]
-- 목적과 의도: Keep zero-profile and zero-stage installations out of the native-profile transaction path without weakening staged-credential cleanup.
-- 기존 구현 및 제약 조건: Every live server swept stages at startup and every minute, and a failed sweep closed the global native-main gate even when no stage artifact existed.
-- 검토한 주요 대안: Disable native-main ownership entirely when the vault is empty, add a stale-lock deletion command, or skip only the stage sweep when both artifact paths are absent.
-- 선택한 방식: Preserve owner and claim protection, but bypass `sweepStages()` only after proving the registry and staging tree are both absent.
-- 다른 대안 대신 이 방식을 선택한 이유: Physical credential ownership remains cross-process safe, while an inert optional subsystem can no longer create the reported lock/recovery catch-22.
-- 장점, 단점 및 영향: Fresh installs avoid the SQLite profile lock; any present or uncertain stage state retains the existing locked fail-closed cleanup and recovery behavior.
-
-The native-write coordinator is keyed by the canonical `CODEX_HOME` in the effective-user runtime
-namespace. A pathname alone is not authority: SQLite can expose a zero-byte file before its first
-schema write, and a terminated process can leave that remnant behind. Eligibility treats the file
-as non-authoritative only after an immutable SQLite read proves version zero with no tables, the
-filesystem identity remains unchanged, and the file has been settled for at least one second; a
-fresh zero-byte creator stays on the coordinated path so its lock cannot be bypassed. `ocx doctor` inspects the
-coordinator with immutable read-only SQLite flags so diagnosis never creates WAL/SHM sidecars. It
-distinguishes absent, zero-byte, unversioned, rowless, valid, unsupported, changed, unsafe, and
-unreadable states and prints the exact path. Explicit recovery is available only after the proxy is
-stopped and only for a proven zero-byte state. The command revalidates the same private
-regular-file identity under a non-blocking SQLite write lock and moves it to a same-directory
-backup; it never deletes or auto-adopts legacy routed residue.
-
-[Decision Log]
-- 목적과 의도: Recover a crashed zero-byte coordinator without mistaking SQLite's normal creation window for stale authority.
-- 기존 구현 및 제약 조건: Eligibility treated every existing pathname as coordinated, while initialization correctly refused a missing row over routed residue; catalog sync could therefore succeed before config injection failed permanently.
-- 검토한 주요 대안: Delete zero-byte files automatically, initialize a new row over residue, require a manual filesystem command, or add observe-only classification plus explicit guarded quarantine.
-- 선택한 방식: Treat only a settled, identity-stable, immutably verified zero-byte database like the existing legacy-uncoordinated boundary; keep fresh creators coordinated, diagnose all other database states immutably, and expose an opt-in zero-byte-only same-directory backup move with identity, ownership, sidecar, liveness, and SQLite-lock checks.
-- 다른 대안 대신 이 방식을 선택한 이유: Automatic deletion or adoption can race a live creator or erase transition evidence; a guarded backup preserves evidence and makes the operator action reproducible.
-- 장점, 단점 및 영향: A stale zero-byte file no longer wedges sync, valid/unrecognized databases remain fail-closed, and recovery requires the proxy to be stopped before `ocx sync` retries injection.
-
-OpenCodex never overrides an explicit `CODEX_HOME`. On Windows, `ocx doctor` and `ocx status`
-nevertheless diagnose the high-confidence Orca dual-home case: both `CODEX_HOME` and
-`ORCA_CODEX_HOME` select Orca's `orca/codex-runtime-home/home`, while the ChatGPT/Codex app uses the
-default `%USERPROFILE%\\.codex`. Sync and restore output always prints the exact target Codex home;
-display and JSON paths redact the OS username. The diagnostic tells users to invoke OpenCodex with
-the app home explicitly rather than silently claiming that an unrelated app was configured. If a
-service was installed under the Orca home, it must first be uninstalled from that original Orca
-environment and then reinstalled under the app home; changing only the current shell cannot migrate
-the recorded service ownership.
-
-[Decision Log]
-- 목적과 의도: Make multi-home injection truthful without taking ownership of user environment variables.
-- 기존 구현 및 제약 조건: CODEX_HOME is an intentional override, but Orca exports it for its own bundled runtime and the Windows app reads a different home.
-- 검토한 주요 대안: Rewrite CODEX_HOME automatically, warn for every custom home, or detect only the Orca-owned signature and report the target path.
-- 선택한 방식: Preserve the override, add a narrow Windows/Orca diagnostic, and qualify sync/restore success output with the effective home.
-- 다른 대안 대신 이 방식을 선택한 이유: It fixes the silent failure while avoiding destructive or noisy behavior for intentional custom homes.
-- 장점, 단점 및 영향: Orca users get an actionable warning; other multi-home products remain unchanged until they have an equally reliable signature.
-
-`atomicWriteFile` uses a temp file named `{path}.ocx.{pid}.{seq}.tmp` (process ID + incrementing
-sequence number) to avoid collisions when concurrent writers (e.g. `ocx stop` and the proxy's own
-shutdown handler) both restore Codex config simultaneously. The temp is renamed atomically into place.
-Storage cleanup run metadata uses the field-scoped persisted-config mutation path, so a background
-Worker cannot restore unrelated API keys or provider settings from a snapshot read before the lock.
-If that metadata write is unavailable after cleanup has already completed, the job retains the
-cleanup outcome and exposes a bounded persistence error instead of relabeling the run as a Worker failure.
-
-Cleanup manifests and satellite backups share the stage-local atomic publisher: an exclusive
-private temporary file is fully written and file-synced before the existing Windows-tolerant
-rename replaces the destination. Handled publication failures retain the previous record;
-directory syncing remains best-effort. This does not make a partial permanent purge reversible:
-restore still fails closed when a recorded logical entry has no surviving file.
-
-Windows secret-file hardening resolves the effective token SID through an absolute, trusted
-PowerShell path before granting the owner and removing inherited broad ACL entries. The normal
-path obtains System32 from `GetSystemDirectoryW`. Windows ARM64 Bun builds that cannot execute
-`bun:ffi` use a narrower ACL-only fallback to the fixed protected default installation path
-`C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe`. The fallback never applies to UAC or
-Task Scheduler launch, never consults environment variables or `PATH`, and fails closed when the
-fixed executable is absent.
-
-Direct PowerShell children rely on the process launcher's `windowsHide`/hidden-host mechanism and
-must not also receive the PowerShell CLI pair `-WindowStyle Hidden`. On affected Windows 11 systems,
-Bun 1.3.14 exits that direct invocation before the command runs, which turns a valid SID or process
-lookup into `EACLIDENTITY` or a failed sync. This does not apply to `Start-Process -WindowStyle
-Hidden` inside an already-running PowerShell script, nor to .NET/VBS process-window settings.
-
-[Decision Log]
-- 목적과 의도: keep trusted Windows identity and process probes console-less without triggering Bun's direct PowerShell `-WindowStyle Hidden` failure.
-- 기존 구현 및 제약 조건: the calls already used `windowsHide: true` or a hidden VBS host, but redundantly passed PowerShell's window-style CLI option; the same option remains valid inside `Start-Process` and must not be removed there.
-- 검토한 주요 대안: decode the generic failure specially, retry after failure, remove all hidden-window controls, or remove only the redundant direct CLI pair.
-- 선택한 방식: retain trusted executable resolution, non-interactive flags, timeouts, and process-level hiding; remove `-WindowStyle Hidden` only from direct PowerShell argv.
-- 다른 대안 대신 이 방식을 선택한 이유: the command executes on affected Bun/Windows combinations, no console window is introduced, and working elevated/detached child-process behavior stays unchanged.
-- 장점, 단점 및 영향: SID, process-owner, tray, update, and sync probes share the compatible launch contract; a future call must use launcher-level hiding rather than reintroducing the PowerShell CLI pair.
-
-[Decision Log]
-- 목적과 의도: Preserve required Windows ACL hardening on the bundled Windows ARM64 runtime without weakening executable trust.
-- 기존 구현 및 제약 조건: The effective-SID query depended on the shared `GetSystemDirectoryW` FFI resolver; Bun 1.3.14 Windows ARM64 has no working `bun:ffi`, so config mutation reached `EACLIDENTITY` before PowerShell could start.
-- 검토한 주요 대안: Restore `USERDOMAIN\\USERNAME`; trust `SystemRoot`, `WINDIR`, or `PATH`; weaken required ACL writes; broaden the shared elevation resolver; or add a fixed-path fallback only for the non-elevated SID query.
-- 선택한 방식: Keep FFI authoritative, then allow only Windows ARM64 to use the existing default `C:\Windows\System32` PowerShell binary for the SID query when that exact file exists.
-- 다른 대안 대신 이 방식을 선택한 이유: Names and environment paths are caller-controlled, required secret writes must not silently skip ACLs, and elevation has a larger authority boundary that should remain FFI-only.
-- 장점, 단점 및 영향: Default Windows ARM64 installations can start and harden secrets; non-default Windows roots continue to fail closed until Bun exposes a trustworthy native system-directory API without FFI.
-
-The durable response-spill directory `~/.opencodex/responses-state-spill/` is bounded in
-aggregate, not only per file. Continuation state demoted out of the in-memory cap
-(`MAX_STORED_RESPONSE_BYTES`) is written there, and eviction past
-`MAX_SPILLED_RESPONSE_BYTES` removes oldest-first through the same deletion point that serves
-TTL and count eviction, so an evicted entry unlinks its file. One function owns that ceiling and
-three callers drive it: mutation pruning, the lazy load that follows a restart, and the periodic
-sweep. The periodic caller is not redundant — the mutation path runs only when traffic arrives, so a
-process that comes up over budget from a snapshot written under a larger ceiling would otherwise
-stay over it while idle.
-
-The ceiling bounds what the store can account for, which is every entry in the map plus the
-superseded generations queued for unlink, and deliberately not the directory as a whole. Spill files
-orphaned by a crash are absent from the map, so this accounting can neither see nor price them; they
-remain with the `recoverOrphanedResponseSpills` grace sweep described below, which is the only
-mechanism that reclaims them. A host that crashes repeatedly can therefore hold spill bytes above
-this ceiling for up to `RESPONSE_SPILL_ORPHAN_GRACE_MS` past each crash. Without that aggregate bound the
-directory was limited only per file (256 MiB) and per entry (1000) — a 250 GiB product — which
-left `RESPONSE_TTL_MS` as the only effective limit and made disk use a function of client
-request rate rather than of anything the process controls.
-
-[Decision Log]
-- 목적과 의도: Bound the durable spill directory in aggregate so demoted continuation state cannot consume the host disk.
-- 기존 구현 및 제약 조건: The resident map has an unconditional byte cap and demotes past it, but the disk it demotes onto had only a per-file ceiling and the shared 1000-entry count cap. Retention itself worked — the hour-long TTL did evict — so the gap was a missing budget, not a leak.
-- 검토한 주요 대안: Lower the per-file ceiling; shorten the TTL; sweep the directory on a timer; add a configurable budget key; carry a running byte counter.
-- 선택한 방식: A constant aggregate ceiling checked at the end of the existing prune, evicting oldest-first, with the total recomputed per prune rather than carried as a counter.
-- 다른 대안 대신 이 방식을 선택한 이유: Per-file or TTL changes alter retention semantics other bounds depend on; a timer adds a second owner for eviction; a config key would surface a knob the sibling bounds (count, TTL, per-file) do not have; and a running counter could silently disable the cap if any of the several insertion paths missed an increment, where a walk over at most 1000 entries cannot drift.
-- 장점, 단점 및 영향: Disk use stops tracking client request rate. Ordinary traffic is unaffected because the count cap binds at a comparable point for median-sized payloads; a workload of unusually large continuations loses its oldest spills earlier than the TTL would, surfacing as the existing `previous_response_not_found` continuation miss.
-
-Response-state loading performs a bounded recovery pass for interrupted snapshot writes. It only
-matches regular files named `responses-state.json.ocx.<pid>.<sequence>.tmp`, waits at least 15
-minutes, and skips the current or any live PID. Eligible files are truncated before unlinking so a
-matching stale path is unlinked without following it. Path-based truncation is intentionally avoided:
-a same-user replacement could otherwise turn cleanup into a write through a symlink. Unrelated
-temporary files, symlinks, directories, and young/active writes are never touched; directory entries
-are consumed incrementally and at most 512 stale files are attempted per process start.
-
-[Decision Log]
-- 목적과 의도: Bound disk and conversation-state retention after abrupt process termination.
-- 기존 구현 및 제약 조건: Ordinary write failures clean up immediately, but a killed process cannot run that path and Windows may temporarily lock files.
-- 검토한 주요 대안: Delete every `.tmp`, rely on manual cleanup, or recover only exact response-state remnants with age and PID guards.
-- 선택한 방식: Run a capped, best-effort, unlink-only sweep on lazy response-state startup.
-- 다른 대안 대신 이 방식을 선택한 이유: It repairs known remnants without broad authority over unrelated temp files or active writers.
-- 장점, 단점 및 영향: Old dead-PID files are reclaimed automatically; locked or conservatively classified files remain for a later retry.
-
-Windows runtime response spills never wait on `icacls` through `Bun.spawnSync`. Linux and macOS
-retain the immediate synchronous publication path. On Windows, the resident continuation enters one
-serialized publication queue and remains replayable while `hardenSecretDirAsync` and
-`hardenSecretPathAsync` run. Publication installs a spill stub only when the map still contains the
-same resident object; a superseded job deletes its newly published file instead of overwriting newer
-state. Pending payloads are pinned and capped at 256 MiB, so an ACL outage cannot grow an unbounded
-queue or be misreported as evictable memory. One caller-owned retry is allowed after a real
-`ETIMEDOUT`; the first timeout does not install a `spill-failed` tombstone. Required ACL failures
-remain fail-closed after that bounded recovery. Optional config-directory hardening uses a separate
-per-directory async single-flight, while required config mutation writers retain their existing
-awaited or synchronous fail-closed boundary.
-
-Each ordinary async spill write attempt owns one 30-second ACL budget shared across directory, temp,
-and exclusive-copy destination hardening; the single timeout retry receives one fresh whole-attempt
-budget. No harden step may reopen an independent 30-second window inside either attempt.
-Both icacls and effective-principal subprocess waits are settlement-bounded: at deadline the child is
-killed, unref'd, and abandoned without awaiting `proc.exited`. The caller-level deadline also bounds
-injected/shared runners, so a child that ignores termination cannot pin the serialized spill queue.
-
-Graceful shutdown drains that serialized publication queue to a stable fixed point before snapshot
-serialization. The drain has a wall-clock cap with a reserved synchronous fallback budget; expiry
-supersedes the async writer, claims and removes any temp or destination it still owns, and only then
-starts fallback publication. The writer rechecks supersession before no-replace publication, while
-the fallback splits its reserve across the directory and file ACL hardens. This ordering is
-load-bearing because resident entries over 2 MiB are deliberately excluded from
-`responses-state.json`: serializing first could omit the resident before its durable spill stub
-exists, losing the continuation on restart. Cleanup is attempted for every abandoned writer; any
-failure is retained while fallback and snapshot persistence continue, then returned through the
-shutdown status so process exit is non-zero without sacrificing unrelated replay state.
-If the fallback reserve expires, every remaining resident candidate is terminalized as a bounded
-`spill-failed` tombstone before pruning, so no payload remains eligible for shutdown requeue and the
-snapshot flush always regains control.
-The terminalization pass itself is hard-capped at `MAX_STORED_RESPONSES + 1`; exceeding that
-structural bound records a bounded failure, fail-closes every remaining resident, and returns control
-to snapshot persistence instead of relying on the progress argument alone.
-
-[Decision Log]
-- 목적과 의도: Keep `/healthz` and unrelated requests responsive during intermittent Windows ACL stalls without publishing an unhardened continuation.
-- 기존 구현 및 제약 조건: Response demotion called the synchronous spill writer from request-time state mutations; `Bun.spawnSync(icacls)` could block the only Bun event loop for the full timeout and immediately replace replayable state with a tombstone.
-- 검토한 주요 대안: Increase the ACL timeout, weaken required ACL checks, publish before hardening, move every platform to async state mutation, or isolate only the Windows ACL-dependent publication boundary.
-- 선택한 방식: Preserve non-Windows behavior; serialize Windows publications through async ACL APIs, retain the exact resident generation until compare-before-swap succeeds, cap pending bytes, and retry one proven timeout.
-- 다른 대안 대신 이 방식을 선택한 이유: Longer waits worsen liveness, early publication weakens secret-file ACLs, and a cross-platform async rewrite would disturb mature immediate memory and crash-ordering contracts that do not cause this incident.
-- 장점, 단점 및 영향: Windows health stays schedulable and transient ACL stalls retain continuation replay; pending payloads can temporarily exceed the 64 MiB resident target but are pinned under a 256 MiB local ceiling and remain inside the documented 512 MiB process-owned worst case.
-
-## Config surface
-
-### OpenCodex home and live process state
-
-`initializePersistedConfigIfMissing` in `src/config.ts` is the create-only path consumed by
-`src/cli/init.ts`. It rechecks absence under the existing config-mutation lock and publishes through
-`src/config/initialize.ts`: a private descriptor is hardened before secret bytes are written, then
-linked without replacing an occupied destination. Existing invalid or unsafe entries are preserved.
-The initializer never truncates a staged inode or rolls back by unlinking the destination; cleanup
-only removes its own temporary name. Unsupported/denied links and incomplete cleanup fail explicitly,
-and publication followed by a later failure can leave a complete config or private residue. Ordinary
-`saveConfig` replacement behavior remains unchanged. This protects init-time config bytes, not a
-foreign winner's ownership under future uninstall; the existing ownership manifest and global CLI
-shim preflight keep their separate contracts.
-
-Initial publication diagnostics distinguish required permission-hardening failures from denied
-hard-link publication without exposing raw filesystem causes. Both identify `OPENCODEX_HOME`
-as the supported-location recovery path; uncertain publication and cleanup warnings remain in
-the CLI. The quickstart documents inspection before retry, private-permission requirements,
-and fresh-location examples. Diagnostics do not introduce a fallback or alter file I/O ordering.
-
-`src/config/paths.ts` is the single owner of `OPENCODEX_HOME` expansion and resolution. It exposes
-the config directory and `config.json` path and retains the existing cache rule: a relative home is
-resolved once for each distinct raw environment value, so a later working-directory change cannot
-silently move the active installation.
-
-`src/config/process-state.ts` derives `ocx.pid` and `runtime-port.json` from that resolved directory.
-It owns their byte-compatible writes, parsing, expected-PID filters, cheap liveness, full OCX command
-identity, and snapshot-guarded removal. `RuntimePortState.attestationSecret` remains optional,
-owner-only state and is validated before a record is returned. `src/config.ts` re-exports the same
-symbols for compatibility, but new lifecycle-only callers import the process-state leaf directly.
-
-Replacing config and process-state writes use `src/config/atomic-write.ts`. The leaf preserves the shared
-process-wide temp sequence, symlink target resolution, real-home test guard, owner manifest,
-Windows ACL hardening, scrub-before-unlink failure path, and explicit residual-temp errors. A caller
-must not replace it with a local temp-and-rename shortcut.
-
-[Decision Log]
-- 목적과 의도: Make persisted config, path resolution, atomic file publication, and live process state distinct ownership boundaries.
-- 기존 구현 및 제약 조건: All four concerns lived in `src/config.ts`; process-state extraction could not safely import the facade without a cycle and could not copy the atomic writer without creating two security/correctness contracts.
-- 검토한 주요 대안: Keep one file, tolerate the cycle, duplicate only PID/runtime writes, or extract the minimal dependency leaves.
-- 선택한 방식: Preserve one implementation per concern under `src/config/` and keep facade re-exports for downstream compatibility.
-- 다른 대안 대신 이 방식을 선택한 이유: The dependency graph stays acyclic and every existing path, serialized shape, error, identity probe, and cleanup guard remains reusable from one owner.
-- 장점, 단점 및 영향: Internal lifecycle imports become narrow and testable; review must still treat changes to `atomic-write.ts` and `process-state.ts` as shared cross-platform runtime changes.
-
-`src/types.ts` is the shape and `src/config.ts` is the loader; neither is reproduced here. What
-matters for maintainers is which groups exist and who resolves them:
-
-| Group | Keys | Resolution rule |
-| --- | --- | --- |
-| Listener | `port`, `hostname` | The listener owns the port; `runtime-port.json` reports where it actually landed. |
-| Routing | `defaultProvider`, `providers`, per-provider `selectedModels` | Explicit `provider/model` wins over `defaultProvider`. |
-| Catalog | `disabledModels`, `customModels`, `modelCacheTtlMs`, `providerContextCaps`, `contextCapValue`, per-provider `modelDisplayNames`, `codexAccountNamespaces`, `codexAccountPickerEnabled` | Catalog state is derived; config only records intent. Exact provider model display names are durable display only overlays. The picker flag is an explicit visibility override, while selector mappings remain the durable exact-routing contract. |
-| Retained state | `appOwnedMemoryBudgetMb` | Process-wide eviction target for app-owned logs, caches, blobs, and continuation payloads. Default 256 MiB, valid 64..4096; pinned state may temporarily exceed the target, but every pin-capable store has a finite local cap and their documented aggregate stays below `APP_OWNED_WORST_CASE_PINNED_BYTES` (512 MiB). Neither value caps RSS or native runtime memory. |
-| Transport | stream mode, timeouts, proxy settings, `websockets`, `emptyCompletionRetry` | `streamMode` persists in config.json; Windows services need a persisted input, and macOS uses it for explicit eager-relay opt-in. Empty-completion replay is an explicit top-level opt-in because its second upstream request may be billable. |
-| Credentials | `apiKeys` | Data-plane only; never admitted to `/api/*`. |
-| Lifecycle | `codexAutoStart`, shim/start behavior, resume-history sync, storage cleanup | Startup safety reads these; see [`05_gui-and-management-api.md`](05_gui-and-management-api.md). |
-
-Env values are resolved through `src/config.ts`, so a config value naming an env var never persists
-the secret itself.
-
-## Config injection
-
-`src/codex/inject.ts` writes one of two forms. The choice is not cosmetic: it decides whether Codex
-keeps its native provider id, which decides whether existing thread history still resolves.
-
-**Loopback (default).** A single marker-owned root override, no provider table:
-
-```toml
-model_catalog_json = "/absolute/path/to/opencodex-catalog.json"
-openai_base_url = "http://127.0.0.1:10100/v1"
-```
-
-Codex keeps the native `openai` provider id, so new threads stay under that identity instead of
-being re-tagged. History restore is manifest-authoritative: only rows whose original provider,
-source, and event marker were backed up for the same state database are restored exactly. A bare
-`opencodex` row is never assumed to have originated at OpenAI; it stays unchanged unless the user
-explicitly runs legacy OpenAI recovery. A user-owned root `openai_base_url` is preserved instead of
-overwritten, and that case also blocks managed sub-agent defaults rather than fighting the user for
-ownership.
-
-Client-compaction mode can retain that user-owned root URL alongside an injected provider table.
-Its status must distinguish ownership from destination: an unmarked user-owned line may already
-point to this proxy. Report that existing `openai` threads follow the configured root URL and new
-threads use the injected table, without inferring a foreign endpoint or prescribing URL removal.
-This diagnostic distinction does not change URL ownership, journal entries, or session history.
-
-**API auth header (non-loopback).** The built-in `openai` provider cannot carry the
-`x-opencodex-api-key` env header, so this form re-tags the root provider and appends the table:
-
-```toml
-model_provider = "opencodex"
-model_catalog_json = "/absolute/path/to/opencodex-catalog.json"
-
-[model_providers.opencodex]
-name = "OpenCodex Proxy"
-base_url = "http://<host>:<port>/v1"
-wire_api = "responses"
-requires_openai_auth = true
-env_key = "OPENCODEX_API_AUTH_TOKEN"
-```
-
-Root TOML keys must be written before the first `[table]`. Re-injection strips the stale form of
-both shapes — opencodex blocks, injected root base-url overrides, stale root context-window
-overrides, and stale catalog paths — before rewriting, so switching between forms leaves no residue.
-
-Read-only doctor and project-routing diagnostics use a lightweight root/table TOML reader rather
-than mutating or normalizing the user's file. That reader must lexically skip both basic and literal
-multiline string bodies: instruction prose can contain key-shaped examples and `[table]` snippets,
-which are data rather than configuration. Diagnostic result objects may retain the real path for
-local correlation, but every formatted doctor line must pass it through the shared user-path
-redaction boundary before display.
-
-[Decision Log]
-- 목적과 의도: Keep strict-config diagnostics useful without interpreting instruction prose as TOML or exposing OS account names in shareable output.
-- 기존 구현 및 제약 조건: The diagnostic reader intentionally covers only Codex root keys and tables; a full TOML dependency is not otherwise required.
-- 검토한 주요 대안: Add a full TOML parser, scan raw lines for one legacy key, or preserve the lightweight parser with multiline lexical state.
-- 선택한 방식: Preserve the bounded reader, skip multiline string bodies before key/table matching, and redact paths only at the formatting boundary.
-- 다른 대안 대신 이 방식을 선택한 이유: All consumers keep one root/table interpretation while internal diagnostics retain actionable local paths.
-- 장점, 단점 및 영향: False positives and username disclosure are removed; unsupported exotic TOML syntax remains outside this diagnostic reader's contract.
-
-Native Codex sub-agent defaults are a separate, explicit opt-in. When
-`syncCodexSubagentDefaults` is true and `injectionModel` is set, injection writes marker-owned
-`agents.default_subagent_model` and, when configured,
-`agents.default_subagent_reasoning_effort`. Unmarked values are user-owned and must never be
-overwritten. Disabling the option and fallback restore remove only marker-owned values; journal
-restore must preserve later user edits while stripping those managed values.
-
-### History backup manifest contract
-
-`src/codex/history-manifest.ts` is the pure schema-and-identity leaf for the versioned history
-backup manifest. It owns the accepted provider/source provenance tuples, platform-aware database
-path identity, backup filename id, and validation from unknown JSON to a typed manifest. It does
-not read files, inspect rollouts, open SQLite, retry, fingerprint, write, or delete anything.
-
-`history-provider.ts` remains the strict mutation owner and maps shared validation failures to its
-restore/no-op integrity states. `native-residue.ts` remains a read-only observer and maps the same
-result to clean, residue, or indeterminate before inspecting referenced rollout files.
-
-[Decision Log]
-- 목적과 의도: Make restore and native-residue inspection accept and reject exactly the same versioned history provenance contract.
-- 기존 구현 및 제약 조건: Both modules independently checked version, database identity, entry ids, absolute rollout paths, provider/source tuples, and event markers; drift could make one module restore a manifest that the other refused to classify.
-- 검토한 주요 대안: Keep duplicate validators synchronized through review, import the mutation-heavy history provider into residue inspection, or extract a pure shared leaf.
-- 선택한 방식: Extract only types, path identity, filename id, provenance, and unknown-data validation; keep all filesystem, rollout, SQLite, retry, and mutation policy in the existing callers.
-- 다른 대안 대신 이 방식을 선택한 이유: A pure leaf removes schema drift without pulling write-side effects or database ownership into the read-only startup inspection graph.
-- 장점, 단점 및 영향: Format changes now have one validator and shared invalid fixtures; callers still intentionally own different user-facing failure mappings, so contract changes require updating both mappings and this document.
-
-If the root config selects a provider other than `openai` or `opencodex`, injection must leave the
-config byte-for-byte unchanged and skip profile creation/updates and history metadata restoration. External
-provider managers own that routing configuration, and replacing their provider id can hide
-otherwise intact Codex sessions. This ownership check must run before catalog/cache refresh,
-journal creation, and the background history restoration guardian.
-
-`ocx sync` and `ocx restore back` run the injector's non-writing preflight before provider
-discovery or catalog/cache replacement. Deterministic config and ownership refusals therefore
-leave the existing catalog and cache untouched, and their concrete messages are emitted on stderr.
-The real injection still revalidates under its normal write boundary after catalog convergence;
-the preflight is an early no-write guard, not an authorization token for a later write.
-
-[Decision Log]
-- 목적과 의도: Prevent a refused Codex config injection from degrading a previously usable model catalog and make the refusal actionable from the CLI.
-- 기존 구현 및 제약 조건: Catalog discovery and replacement ran before injection, while the injector alone owned the authoritative TOML transforms and write-coordination eligibility checks.
-- 검토한 주요 대안: Roll back catalog and cache bytes after a later refusal, duplicate a partial TOML validator in the CLI, or run the injector's existing planning path without committing before discovery.
-- 선택한 방식: Add a non-writing mode to the injector and call it before catalog work; keep the normal injector call as the final under-lock authority check.
-- 다른 대안 대신 이 방식을 선택한 이유: Post-hoc rollback can overwrite a concurrent catalog writer, and a second validator would drift from the real refusal rules. Reusing the injector keeps one policy path and avoids compensating writes.
-- 장점, 단점 및 영향: Deterministic refusals preserve catalog/cache bytes and print their reason on stderr. A concurrent state change can still make the final injection refuse, but catalog and injection retain their existing independent revalidation and serialization boundaries.
-
-`supports_websockets = true` is appended to the provider table only when `websocketsEnabled(config)`
-returns true.
-
-## Codex-home diagnostics
-
-Some Codex-home conditions are reported rather than repaired, because repairing them would overwrite
-a deliberate user choice:
-
-- Bundled-plugin marketplace state on Windows (`src/codex/plugins-doctor.ts`), surfaced by
-  `ocx status`.
-- Project-level Codex config that bypasses managed routing
-  (`src/codex/project-config-warnings.ts`), surfaced by `ocx doctor` as a warning rather than an
-  override.
-
-## Profile and fast tier
-
-When opencodex owns routing, it also writes `$CODEX_HOME/opencodex.config.toml` as an explicit profile
-target. Codex config uses `service_tier = "fast"` and `[features].fast_mode = true`;
-catalog/request tier metadata may use `priority`. Do not collapse these spellings into one value.
-
-## Provider output defaults
-
-`OcxProviderConfig.defaultMaxOutputTokens` and `modelMaxOutputTokens` are OpenAI Chat wire defaults,
-not context-window metadata. They are applied only when a Responses request omits
-`max_output_tokens`; an explicit request value wins, then a model-specific configured value, then
-the provider default, then the adapter omits `max_tokens`.
-
-Both fields must stay positive finite integers at disk-config and management validation boundaries.
-Registry entries may seed them through `providerConfigSeed`, key-login derivation, OAuth reconcile,
-and `routeModel`, but user config overrides registry defaults per field/key.
-
-## Provider validation ownership
-
-`src/config/provider-validation.ts` owns the pure provider payload checks shared by persisted config,
-CLI writes, and management DTO validation. `src/config.ts` imports those checks for Zod refinement
-and re-exports them as a compatibility facade; it must not grow a second copy. Validation error text,
-ordering, and cross-field rules are part of the write/load contract because management requests and
-hand-edited `config.json` must accept and reject the same provider shapes.
-
-[Decision Log]
-- 목적과 의도: Separate reusable provider payload validation from config file persistence without changing accepted configuration or error behavior.
-- 기존 구현 및 제약 조건: The Zod schema, CLI, and management API shared helpers defined inside `src/config.ts`, so callers needing one pure check depended on the full persistence module.
-- 검토한 주요 대안: Keep validation in the persistence module; duplicate checks per caller; extract one leaf and retain compatibility re-exports.
-- 선택한 방식: Use one pure validation leaf, consume it from config refinement and direct DTO callers, and keep `src/config.ts` re-exports during migration.
-- 다른 대안 대신 이 방식을 선택한 이유: One implementation preserves load/write parity while reducing dependency breadth and avoiding a flag-day import rewrite.
-- 장점, 단점 및 영향: Validation can be characterized independently and config persistence becomes smaller; a temporary facade remains until all internal callers migrate.
-
-## Restore
-
-`ocx stop`, `ocx restore` / `ocx eject`, `ocx service stop`, and `ocx service uninstall` must strip
-opencodex config and routed catalog entries without damaging native Codex state.
-
-Full `ocx uninstall` config cleanup is ownership-manifest based. A fresh config directory receives a
-root-bound owner marker and an uninstall manifest before its first atomic config write. Uninstall
-validates both bounded metadata files, rejects path traversal and a symlink/junction config root,
-and removes only normalized manifest entries. Manifest-owned directory links are unlinked without
-traversing their targets. Unknown files remain in place and make the command report a partial
-uninstall with their exact paths.
-
-Legacy nonempty config directories are deliberately not retroactively claimed. If either ownership
-file is missing, malformed, or bound to another root, uninstall refuses config deletion and reports
-the residual directory for manual review; there is no recursive-delete fallback.
-
-## Remote client key files
-
-Client connection metadata stores a stable `apiKeyId` and a non-secret rotation `pendingOperation`. The current data secret remains only in `service-api-token`; a bounded rotation temporarily keeps the old secret in owner-only `service-api-token.prev`. Commit or recovery clears the marker before orphan cleanup. `ocx disconnect` is local-only and leaves remote revocation to the hub's **Integrations → API Keys** page. Hub and local usage stores are not mirrored.
diff --git a/structure/03_catalog-and-subagents.md b/structure/03_catalog-and-subagents.md
deleted file mode 100644
index 9769012e1d..0000000000
--- a/structure/03_catalog-and-subagents.md
+++ /dev/null
@@ -1,543 +0,0 @@
-# Catalog And Subagents SOT
-
-## Shared catalog
-
-`src/codex/catalog.ts` builds a shared Codex-shaped catalog for CLI, TUI, App, and SDK. It:
-
-- preserves native OpenAI entries from the live catalog or static fallback, and emits
-  gpt-5.6 natives from the pinned upstream models.json snapshot
-  (`src/codex/data/upstream-models.json` — exact per-slug ladders: luna has no ultra);
-- upgrades either an observed selector-qualified `*/gpt-daybreak-blue-latest` account row or an
-  explicitly configured canonical `openai/gpt-daybreak-blue-latest` Codex-forward row from the
-  pinned Sol capability metadata while preserving its selector and Daybreak wire identity;
-  this never expands the bare/API-key model lists or rewrites the wire model to `gpt-5.6-sol`;
-- clones a native template for routed `provider/model` entries;
-- forces strict Codex catalog fields required by the current parser;
-- hides `disabledModels` without blocking direct routing (routed provider ids are excluded;
-  account-qualified native ids hide only that selector row; BARE native slugs hide the bare row
-  and all account-selector clones and drop that model family from raw `/v1/models`);
-- applies exact provider/model compatibility exclusions after live discovery and metadata
-  augmentation, so upstream-advertised but uncallable rows never enter dashboard or Codex pickers;
-- strips native-only service tier and WebSocket metadata unless the final routed provider/model
-  explicitly enables the verified OpenAI-compatible service tier;
-- backs up the pristine catalog once per catalog: the copy is keyed by a hash of the catalog path
-  (`catalog-backup-<id>.json`), and the legacy unsuffixed `catalog-backup.json` is retained in
-  addition for the default catalog, so a restore resolves the backup for the catalog it is restoring
-  rather than assuming a single file;
-- invalidates `$CODEX_HOME/models_cache.json` when model visibility changes.
-
-On the default `opencodex-catalog.json` path, sync deliberately uses two catalog sources: Codex's
-bundled catalog supplies a current native entry template, while the actual on-disk catalog supplies
-the rows being merged. This split is required because empty or partial provider discovery must
-preserve routed entries and genuine user-native rows from the file that will be overwritten; a
-bundled catalog never contains those rows. Retained sync and evidence-bound convergence share an
-explicit observed-state merge policy and restore native priorities from the once-only pristine
-backup rather than from a catalog whose priorities may already have been rewritten. A configured
-custom catalog remains the native metadata/template authority even when a bundled-catalog memo is
-warm. Both paths may use an admitted matching bundled memo only as installed-runtime capability
-evidence to remove unsupported reasoning efforts; convergence never probes Codex itself.
-
-Custom Astra and Daybreak rows acquire native reasoning capability only through the existing
-canonical `openai` forward destination and explicit capability-source predicate. The shared
-custom-row producer bounds their merged effort lists against pinned per-model Codex metadata,
-preserves an explicit empty list without a default, and recovers an incompatible nonempty list
-to the native default singleton. A default must belong to the projected list. Other custom rows
-keep their declaration precedence; a GPT model name, display alias, or arbitrary gateway is not
-native provenance. Stored configuration and native capability maps are unchanged.
-
-The observed-state merge tracks the current invocation's freshly generated custom row objects
-after detaching its inputs. Those rows already own their complete reasoning projection, so the
-merge does not append `max` again. This also keeps a generic none-only custom row none-only;
-ordinary retained provider rows still receive the existing mock-tier policy. A persisted custom
-marker alone never grants this exemption. Both gather entry points, retained sync, management
-convergence and direct Codex model discovery use the same producer. The legacy runtime effort
-union clamp remains separate; it is not a per-model or per-client-version grammar oracle.
-Existing thread settings and the reported Desktop 0.153.4 gateway rejection require separate
-runtime evidence. Codex's native `ultra` mode is preserved and is not a literal API wire promise.
-
-When account selectors are enabled, the sync path may also observe exact, visible, API-supported
-OpenAI-family ids from Codex's user-owned catalog/cache. Only rows with native catalog provenance
-are trusted; unknown ids are carried through startup cache invalidation as hidden observations and
-are emitted only as selector-qualified rows whose account provenance matches. They never expand
-the bare native or API-key model list. This keeps account-scoped upstream ids such as
-`gpt-daybreak-blue-latest` callable without treating them as a static release allowlist.
-
-Account-gated native ids are a stricter subset. Their authenticated ChatGPT `/models` roster is
-cached per credential generation with a bounded timeout. A bare gated row is emitted only when at
-least one confirmed eligible account reports it; a selector-qualified row is emitted only when the
-mapped account reports it. A failed or malformed discovery is not positive evidence and therefore
-hides the gated row until a later refresh. The same snapshot gates Pool selection, so the catalog
-and runtime cannot disagree by advertising through one account and dispatching through another.
-
-The app-server's model list comes from this shared catalog, not from patching the App. Codex Desktop
-may still apply its remote native-only allowlist after `model/list`; an explicitly configured combo
-`nativeAlias` is the bounded compatibility path. It replaces one supported bare native row with a
-routed, labeled row, routes the bare id before canonical OpenAI, and keeps account-qualified native
-selectors genuine. Missing target discovery capabilities inherit the replaced native row's metadata,
-while explicit target limits remain authoritative. Because the affected renderer ignores `visibility: "hide"`, the presence of any
-native alias also omits disabled bare native rows from the effective catalog. Dashboard rows remain
-derived from the static native set, and sync retains bundled/pristine native recovery sources so a
-later re-enable or alias removal restores native metadata.
-
-Provider live-model lists are cached with a configured TTL (`src/codex/model-cache.ts`). Adding,
-deleting, or editing a provider's shape clears that per-provider cache; a disabled-only change
-deliberately does not, because a disabled provider is already excluded from the catalog gather
-instead. Codex's own `models_cache.json` is a different cache, invalidated by catalog refresh.
-
-For `liveModels: false`, a static provider publishes the ordered union of `models` and
-`retainModels`. When `models` is absent or empty, its configured `defaultModel` seeds that
-union before retained ids; a nonempty explicit list does not import a different default.
-Without any default or configured/retained ids, the static result stays empty. The existing
-forward-auth native path remains separate. Static gathering does not refresh OAuth or call
-the provider's model endpoint, and normal selection and visibility filters still apply.
-
-The provider workspace uses the existing `/api/models` projection for displayed rows,
-model identity and inventory counts. Counts cover distinct non-disabled selectors within
-each provider, before search or the render cap; they are not selected-model or live-discovery
-counts. The full available list and discovery provenance remain separate inputs.
-
-Deleting a custom definition uses its stable record id and does not also hide the underlying
-model. Native or discovered metadata can therefore reappear without changing the inventory
-count. Hide uses the represented row's native/routed identity and changes visibility only.
-The Models page can restore existing hidden rows; adding a definition does not implicitly
-clear a previous hide or provider allowlist. Actions wait for current row and custom-ownership
-observations, and mutations reconcile those observations instead of retaining browser-only
-removal markers. These presentation operations do not grant routing or account entitlement.
-
-### Windows request-path catalog-state discovery
-
-[Decision Log]
-- 목적과 의도: Prevent Windows PowerShell/CIM process discovery from blocking Bun's event loop while v2 sub-agent guidance is assembled.
-- 기존 구현 및 제약 조건: The stale-catalog check is advisory on the request path, but CLI/service lifecycle operations use the same process evidence before warning or terminating narrowly matched app-servers.
-- 검토한 주요 대안: Remove stale-catalog guidance, move every platform collector into workers, or isolate only the Windows request path behind asynchronous child processes.
-- 선택한 방식: Keep the synchronous fail-closed collector for explicit lifecycle operations; v2 requests use asynchronous trusted-System32 PowerShell, one identity-scoped in-flight refresh, and the existing short cache. Cache invalidation advances a generation so a pre-write CIM result cannot repopulate post-write state.
-- 다른 대안 대신 이 방식을 선택한 이유: This preserves process ownership and matching invariants while preventing a slow CIM query from starving `/healthz` and unrelated proxy traffic.
-- 장점, 단점 및 영향: Concurrent v2 turns do not multiply CIM walks and the event loop remains responsive. A cold request can still await the bounded advisory check, and collection failure suppresses OpenCodex-authored model guidance as `unknown`.
-
-## Startup readiness
-
-Each `startServer` invocation owns a private, one-shot readiness gate created before the listener
-binds. `handleStart` supplies its gate and transitions it only after the shared catalog sync and
-best-effort Claude Code roster reconciliation have both settled. The catalog sync remains the
-authority for ready versus failed; a roster warning does not make an otherwise healthy proxy fail.
-Calls without a supplied gate receive a fresh private gate that intentionally remains pending. Only
-`ok: true` with no nonempty warning becomes ready; `null`, a throw, `ok !== true`, or a nonempty
-warning becomes failed. State is isolated per server instance.
-
-Exact unauthenticated `GET /readyz` returns sanitized identity fields plus pending, ready, or failed:
-`200` for ready, or `503` with `Retry-After: 1` for pending and terminal failed. The full CLI syntax
-is `ocx ready [--json] [--wait [--timeout <seconds>]]`. The probe validates the service, version,
-uptime, PID, port, status, and HTTP/status pairing. The default is one probe. With `--wait`, it
-applies one absolute deadline (45 seconds by default) across discovery, readiness probes, polling,
-and sleeps, but exits immediately on terminal failed. `--timeout <seconds>` requires `--wait` and
-accepts positive integer seconds from 1–300. CLI `--json` emits
-`{ready, status, pid, port}`, with status in `ready|pending|failed|unreachable`. Exit 0 means ready;
-exit 1 covers not-ready, pending, failed, timeout, and unreachable; exit 64 means invalid arguments.
-Older proxies without `/readyz` fail closed as unreachable. `/healthz` remains the separate
-liveness contract.
-
-## Entry shape
-
-Routed entries keep Codex-required metadata such as reasoning levels, shell type, API support flags,
-base instructions, modalities, auto-compact fields, and strict parser booleans. The public slug uses
-the canonical `provider/model`. Its display name uses the provider's exact `modelDisplayNames` override first,
-then trusted catalog metadata such as a configured qualified provider/model alias, then the public slug.
-This overlay never changes route identity or the upstream wire model, and its catalog fingerprint makes
-a label edit refresh Codex output.
-
-Supported bare native GPT rows also consume `providers.openai.modelDisplayNames`. Retained sync
-and convergence pass the same map to the observed-state merge. After native normalization and
-ordering, the merge applies the exact nonblank trimmed label and saves
-`opencodex_native_display_name: { slug, original, applied }` in the local catalog only. The next
-merge detaches its inputs, removes that marker, and restores `original` only if the native slug
-still matches and the current name equals `applied`. Removing or blanking the override therefore
-restores the owned name before normal native metadata upgrades. Divergent external names remain
-subject to those upgrades: Astra still replaces non-pinned names with its pinned native name.
-Template-derived rows discard the marker. The overlay leaves model IDs, metadata (including
-capabilities), ordering, routed combo aliases, custom rows and account-qualified rows unchanged;
-it does not relabel HTTP model listings or virtual `*-pro` rows.
-
-## Native passthrough
-
-Astra has its own pinned native row: 272,000 default context, 872,000 opt-in ceiling,
-low-through-ultra effort, low default, and native multi-agent effort `xhigh`. The native-alias
-fallback passes the same configured limits to context, max input and compaction. Unrelated routed
-templates clear the native multi-agent effort; canonical Astra-forward custom rows retain it and
-the pinned Fast speed description. Sync repairs only the exact old built-in Astra Fast description,
-preserving custom descriptions and other stored row fields.
-
-The API registry separately owns Astra's 1,050,000 context / 922,000 input / 128,000 output and
-five API effort levels. Trusted discovery snapshots carry the output ceiling as well as input
-and context, so reconstruction cannot drop it. User output limits may only lower that ceiling.
-Pricing remains provider-scoped and API-referenced for every built-in dollar estimate, including
-Codex-login routes. Both OpenAI identities use the same Astra/Sol API base and cache prices,
-API Fast multipliers and published long-context bands; Fast stacks with long context for Astra,
-GPT-5.6 and the Daybreak Blue selectors. No subscription-specific exception or credit multiplier
-enters the estimate. Explicit user price overrides remain authoritative. See the public provider
-reference for the dated source table.
-
-Native bare OpenAI entries form one `openai` group. The provider's Pool(default)/Direct option
-changes account selection without changing those ids; `openai-apikey/<model>` creates the separate
-API-key identity. The API GPT-5.6 rows use 1,050,000 context / 922,000 max input; their `*-pro` virtual rows
-rewrite to the base upstream model with `reasoning.mode: "pro"` while public state keeps the virtual
-slug. Routed non-OpenAI models must not
-inherit native-only service tier or WebSocket metadata unless the user explicitly enables that
-capability. Detailed invariants live in [`08_openai-provider-tiers.md`](08_openai-provider-tiers.md).
-
-Native passthrough entries depend on the enabled provider set. With at least one enabled provider,
-they appear only while an enabled canonical OpenAI forward provider exists — disabling every such
-provider removes the native rows rather than leaving entries that resolve to no credential. With no
-enabled provider at all, the native rows remain as bootstrap so a fresh install still has something
-to route.
-
-## Accounts, namespaces, and pool rotation
-
-Pool mode routes across main plus added Codex credentials. Key rules:
-
-- **A namespace is a public selector mapped to an internal target.** Generated selectors are how a
-  caller names an account — the main login's selector is `main` (collision-suffixed if taken),
-  which maps to the config-only sentinel `@main`; the sentinel deliberately sits outside the
-  pool-account id grammar. Selector initialization requires an explicit opt-in and fills only an
-  absent or empty map; a non-empty user map keeps its object identity and insertion order. Generated
-  selectors avoid provider, combo, routing-policy, and slash-qualified routing-profile namespaces.
-  Collision checks normalize provider and reserved namespace keys, while account and
-  routing-profile selector prefixes are exact-case (`src/codex/account-namespaces.ts`,
-  `src/codex/account-namespace-match.ts`, `src/routing/profile-namespace.ts`).
-- **Selector labels carry no account-role semantics.** When at least one selector is advertisable,
-  the Codex catalog clones each supported native row per selector and hides the bare picker rows;
-  bare ids remain routable and stay in raw `/v1/models` unless explicitly disabled. Missing stored
-  account targets are not advertised, and private account ids never become catalog labels.
-  `codexAccountPickerEnabled: false` hides generated rows without deleting exact routing bindings;
-  an omitted flag preserves the established behavior of a nonempty hand-written selector map.
-- **Rotation is sticky.** A conversation stays on its selected account while that account is
-  usable; failure moves it, success does not (`src/codex/pool-rotation.ts`).
-- **The credential store is generation-guarded.** A refresh takes a lock and persists only if the
-  generation it started from still holds; a lost race raises a generation-conflict error rather
-  than overwriting the newer credential (`src/codex/account-store.ts`). Callers handle that error;
-  they do not assume a silent retry.
-
-Warmup issues a bounded request with a fallback model so a cold account reports usability before a
-real turn depends on it (`src/codex/warmup.ts`).
-
-## Multi-agent surface mode (3-state)
-
-`OcxConfig.multiAgentMode` controls the `multi_agent_version` field stamped on catalog entries:
-
-| Mode | Behavior |
-| --- | --- |
-| `"v1"` | Force ALL entries to `multi_agent_version = "v1"` — overrides upstream pins (sol/terra included). |
-| `"default"` (install default) | Respect upstream model pins (sol/terra=v2, luna=v1, others=null → codex feature flag decides). On sync, stale forced values are cleared and upstream pins restored. |
-| `"v2"` | Force ALL entries to `multi_agent_version = "v2"` — overrides upstream pins (luna included). |
-
-The override is applied as a final pass in both `buildCatalogEntries` (live `/v1/models` path) and
-`mergeCatalogEntriesForSync` (on-disk sync), AFTER all normalization and visibility processing. This
-ensures `normalizeRoutedCatalogEntry` (which deletes `multi_agent_version` from routed entries) does
-not clobber the forced value.
-
-CLI: `ocx v2 mode v1|default|v2`. GUI: segmented control on the Models page. API: `GET/PUT /api/v2`
-with `multiAgentMode` field.
-
-The `multi_agent_v2` feature flag and the logical maximum thread count are separate from
-`multiAgentMode` (`src/codex/features.ts`): the mode decides which surface Codex advertises, while
-the flag and thread count decide what the native runtime allows.
-
-`keepNativeChatGptOnV1` makes mode `v2` a catalog-driven hybrid: OpenCodex disables the global
-`multi_agent_v2` override because codex-rs resolves that override before a model row's explicit
-`multi_agent_version`. Native ChatGPT rows then select v1 from the catalog and routed rows select
-v2. An explicit attempt to enable the global flag while the hybrid pin is active is rejected.
-
-### What the five-model `spawn_agent` window is, and how V1 differs from V2
-
-`MAX_SPAWN_AGENT_MODEL_OVERRIDES = 5` (mirrored in `src/codex/catalog/sync.ts`) is **not** a
-subagent concurrency limit and **not** an eligibility limit. Upstream uses it in exactly two
-places: the model list rendered into the `spawn_agent` tool description
-(`multi_agents_spec.rs:789`) and the "Available models:" suggestions in an unknown-model error
-(`multi_agents_common.rs:448`, inside the `ok_or_else` closure that runs only *after* the lookup
-already failed). The success path `find_spawn_agent_model_name` (`:431-442`) scans the whole
-catalog with neither the cap nor a `show_in_picker` filter, so a model outside the advertised
-five is still accepted when named exactly.
-
-Three different numbers, often conflated:
-
-| Quantity | Value | Source |
-| --- | --- | --- |
-| Models **advertised** as overrides | `min(5, picker-visible eligible rows)` | `multi_agents_spec.rs:785-790` |
-| Models **eligible** as targets | no numeric cap (only `"disabled"` is excluded, and only on V2) | `multi_agents_common.rs:36-42` |
-| **Concurrent** subagents | V1 6 children (root excluded); V2 total 4 including root → 3 children | `config/mod.rs:211-212`, `:1497-1506` |
-
-**The cap is the same 5 on both surfaces, but the window's contents are not.** The eligibility
-filter runs *before* `.take(5)`, and it behaves differently per surface: on a V1 call
-`model_supports_multi_agent_backend` short-circuits true for every row (including `disabled`
-ones), while a V2 call drops `Some(Disabled)` first — which lets a later row move into the five.
-Same catalog, different advertised list:
-
-| # | Model | pin | V1 advertises | V2 advertises |
-| ---: | --- | --- | :---: | :---: |
-| 1 | `v2-a` | `v2` | ✅ | ✅ |
-| 2 | `disabled-a` | `disabled` | ✅ | — |
-| 3 | `v1-a` | `v1` | ✅ | ✅ |
-| 4 | `null-a` | absent | ✅ | ✅ |
-| 5 | `v2-b` | `v2` | ✅ | ✅ |
-| 6 | `disabled-b` | `disabled` | — | — |
-| 7 | `null-b` | absent | — | ✅ |
-
-opencodex already matches this: `effectiveSubagentRoster` filters with
-`surface !== "v2" || isEligibleV2SubagentEntry(entry)`, so the V1 path skips the eligibility
-filter exactly as upstream does. opencodex also injects no roster on V1
-(`src/server/responses/collaboration.ts` emits only proactive text at the top effort tier), so
-the upstream tool description remains the authority there.
-
-Two further V1/V2 differences worth knowing: the list gate is
-`hide_agent_type_model_reasoning` on V1 (hard-coded `false` at registration, so V1 always
-advertises) but `expose_spawn_agent_model_overrides` on V2 (default `true`; when false the list
-is omitted *and* the `model`/`reasoning_effort` schema fields are removed). And V2's
-`hide_spawn_agent_metadata` defaults true, which removes `service_tier`.
-
-`modelPickerOrder` (#1649) separates **OpenCodex guidance** from native advertisement.
-`SPAWN_PRIORITY_FIELD` preserves the natural priority used by `effectiveSubagentRoster`, so
-OpenCodex's preferred/guidance candidate calculation stays independent of display order.
-Native Codex ignores that private field: its advertised five on V1 and exposed V2 follow the
-native `priority` and may change when the picker is reordered. Exact-name override lookup is
-not restricted to those five advertised rows. V1 receives no OpenCodex preferred-roster
-injection; V2 can additionally receive natural-priority guidance when its catalog state permits.
-The helper tests pin guidance behavior, not native tool-description equivalence.
-
-A nonblank bare id in `modelPickerOrder` opts into complete-picker display ordering. Exact
-ids take precedence over raw/encoded equivalents; routed-only and empty lists keep the legacy
-ordering behavior. This does not change the separate `opencodex_spawn_priority` contract.
-Retained rows recompute their natural ranks from the current featured roster and account-selector
-stride before display order is applied, so a discovery outage cannot preserve an obsolete
-featured or picker rank. Canonical `opencode-go` rows retain their configured reasoning ladder
-both when generated and when merged from retained catalog state; synthetic max/ultra choices
-are not added to that provider's declared ladder.
-
-Full derivation with per-line citations: `devlog/_plan/260816_codexrs_multiagent_v2_and_history_perf/013_five_cap_v1_vs_v2.md`.
-
-## Routed tool discovery and hosted search
-
-All routed catalog rows advertise `supports_search_tool: true` together with
-`tool_mode: "code_mode_only"` — the pair is load-bearing. The field selects Codex's deferred
-tool-discovery surface; it does not describe the hosted web-search sidecar. Under code mode,
-deferred MCP tools remain callable through exec's `tools` global / `ALL_TOOLS` without a
-`tool_search` round-trip (upstream codex-rs code_mode suite; live canary 2026-08-13: routed
-kimi/k3 executed `tools.mcp__node_repl__js`, devlog `260813_tool_catalog_deferral/010+020`).
-Stamping `false` instead forces every MCP declaration into `exec.description` — a measured 2.7x
-turn-1 payload regression (96,699 → 258,929 chars). For Cursor this can also make the unified
-`exec` exceed the 120,000-byte serialized `McpTools` ceiling; the budget then drops `exec` and
-its companion `wait` (#1830). Hosted search remains independent: non-Cursor routes keep
-`web_search_tool_type: "text_and_image"`, while Cursor omits it because runTurn bypasses the
-search sidecar.
-
-[Decision Log]
-- 목적과 의도: keep routed plugin/MCP tools reachable without paying the full-catalog turn-1 payload tax or starving Cursor's unified execution bridge.
-- 기존 구현 및 제약 조건: #1596 restored deferred discovery only for non-Cursor rows because Cursor bypasses the hosted-search sidecar; codex-rs treats deferred exposure and hosted search as separate capabilities, and Cursor independently enforces a 120,000-byte serialized tool-catalog limit.
-- 검토한 주요 대안: keep Cursor opted out, raise/disable Cursor's transport ceiling, synthesize another execution bridge, or enable Cursor-native local exec only when the bridge disappears.
-- 선택한 방식: enable Codex deferred exposure for Cursor code-mode rows too, while continuing to omit Cursor's hosted `web_search_tool_type`.
-- 다른 대안 대신 이 방식을 선택한 이유: it removes the known exec-description inflation before Cursor budgeting without weakening the measured transport limit, inventing caller tools, or turning bridge absence into local-execution authority.
-- 장점, 단점 및 영향: Cursor keeps a compact Responses-owned `exec` path under rich tool catalogs and hosted-search behavior remains unchanged; the existing Cursor budget and native-local-exec fail-closed policy remain authoritative.
-
-## Ultra reasoning level
-
-Ultra is always advertised in the catalog regardless of the `multi_agent_v2` toggle. The v2 toggle
-controls only the multi-agent collab surface, not ultra visibility. The `nativeEffortClamp` function
-wire-clamps ultra/max to each model's real top rung (e.g. gpt-5.5 ultra → xhigh on the wire).
-
-`effortCap` and `subagentEffortCap` are hard ceilings applied on the V2 path
-(`src/server/effort-policy.ts`): they lower or preserve the requested effort rather than rejecting
-the request, and they never raise it.
-
-The `ocx effort` CLI accepts only the same canonical cap ladder before live probing or persistence.
-Its status output preserves unsupported legacy cap values and reports that those fields are ignored;
-the read does not normalize or migrate them, and an ignored subagent field does not disable a valid
-main cap. Injection-effort input remains a separate contract.
-
-Operator-owned `pinnedReasoningEffort`, `modelPinnedReasoningEfforts`, and root
-`modelPinnedEfforts` resolve before applicable effort caps at the final destination.
-Provider model pins precede provider-wide pins, then global selector/destination pins.
-A pin can raise the effective caller effort; the later cap can still lower or omit it.
-`none` means explicit-effort omission (provider default), not guaranteed reasoning disablement.
-Compaction maintenance is exempt. Pins are user overlays and do not alter registry seeds,
-model discovery or advertised ladders. Native Chat normalizes newly pinned values through
-provider wire mapping; unpinned native requests retain their existing pass-through contract.
-
-[Decision Log]
-- 목적과 의도: Xiaomi MiMo의 공식 OpenAI Chat endpoint가 실제로 받지 않는 `max`/
-  `ultra` reasoning tier를 catalog에 노출하지 않도록 한다.
-- 기존 구현 및 제약 조건: `xiaomi`는 Anthropic endpoint, `mimo`는 token-plan endpoint를
-  소유하며, 공식 `https://api.xiaomimimo.com/v1`은 generic custom provider로 처리됐다.
-- 검토한 주요 대안: 기존 `xiaomi`/`mimo` contract를 확장하기, 모든 custom provider의 ladder를
-  일괄 축소하기, 공식 public endpoint만을 별도 registry row로 소유하기.
-- 선택한 방식: `xiaomi-mimo`를 고정 목적지의 `openai-chat` preset으로 등록하고
-  `low`/`medium`/`high`만 노출하며 높은 direct request는 `high`로 clamp한다.
-- 다른 대안 대신 이 방식을 선택한 이유: 서로 다른 auth/wire/host를 하나의 preset으로
-  합치지 않으면서 upstream error로 확인된 계약만 적용할 수 있다.
-- 장점, 단점 및 영향: 공식 endpoint에서 안전한 picker/wire 계약을 제공하고,
-  `preserveCustomDestination`으로 같은 이름의 다른 host/key를 보호한다. 대신 새 preset 표면을
-  문서와 registry parity에서 함께 유지해야 한다.
-
-[Decision Log]
-- 목적과 의도: Xiaomi token-plan에서 image input을 거부하는 `mimo-v2.5-pro`만 vision
-  sidecar로 우회하고, 실제 image input을 받는 `mimo-v2.5`는 native vision 경로에 남긴다.
-- 기존 구현 및 제약 조건: upstream `/v1/models`는 input modality를 제공하지 않으며,
-  `noVisionModels`는 text-only 모델을 sidecar로 보내면서 Codex catalog에는 image input을
-  광고하는 provider-scoped 계약이다.
-- 검토한 주요 대안: MiMo 전체를 text-only로 분류하기, live discovery에서 modality를
-  추측하기, `mimo-v2.5-pro` 하나만 registry에 고정 분류하기.
-- 선택한 방식: canonical `mimo` preset의 `noVisionModels`에 `mimo-v2.5-pro`만 추가한다.
-- 다른 대안 대신 이 방식을 선택한 이유: live endpoint 검증으로 확인된 최소 범위만
-  적용하며, 정상 동작하는 `mimo-v2.5`의 native image 경로를 훼손하지 않는다.
-- 장점, 단점 및 영향: Pro image 요청의 404를 sidecar 설명 경로로 바꾸고 base 모델은
-  그대로 유지한다. `preserveCustomDestination` guard 때문에 같은 provider id를 다른 host에
-  연결한 사용자 설정에는 이 capability 분류가 전파되지 않는다.
-
-[Decision Log]
-- 목적과 의도: GitHub Copilot의 live model catalog가 명시하는 모델별 image-input 지원을
-  Codex catalog에 정확히 보존한다.
-- 기존 구현 및 제약 조건: 공용 discovery parser는 직접 `capabilities.vision`과 표준 modality
-  필드는 읽었지만 Copilot의 `capabilities.supports.vision` 중첩 boolean은 읽지 않아 모든
-  Copilot 모델이 text-only fallback으로 축소되었다.
-- 검토한 주요 대안: 모든 Copilot 모델에 정적 vision seed를 추가하기, 모델 이름을 외부
-  metadata alias에 연결하기, live 모델별 boolean을 공용 parser에서 해석하기.
-- 선택한 방식: 직접 vision boolean이 없을 때만 중첩 `supports.vision`의 명시적 boolean을
-  사용하고, `false`도 보존하며 malformed 값은 추론하지 않는다.
-- 다른 대안 대신 이 방식을 선택한 이유: live 응답이 모델별 capability의 가장 좁은 근거라서
-  새 모델에도 적용되며 text-only 모델을 image-capable로 과장하지 않는다.
-- 장점, 단점 및 영향: Copilot vision 모델은 image attachment를 받을 수 있고 명시적 text-only
-  모델은 계속 차단된다. Capability를 제공하지 않는 모델은 기존 fallback을 유지한다.
-
-[Decision Log]
-- 목적과 의도: bare `defaultModel` selectors that route into third-party providers must keep their
-  adapter-owned effort ladder; only true ChatGPT-native requests should receive the mock-max repair.
-- 기존 구현 및 제약 조건: `nativeEffortClamp` already needed the original request id because
-  routing strips `provider/`, but bare third-party selectors like `glm-5.2-fast-preview` still look
-  native after that strip.
-- 검토한 주요 대안: (1) infer nativeness from the bare slug prefix alone, (2) gate clamping by the
-  resolved provider identity, (3) disable the clamp for all off-snapshot slugs.
-- 선택한 방식: request-time clamp entry is allowed only when the resolved route is the canonical
-  built-in OpenAI/Codex forward provider and the original request id is still bare.
-- 다른 대안 대신 이 방식을 선택한 이유: provider identity is the only durable signal that
-  distinguishes true native ChatGPT traffic from third-party `defaultModel` routes when both share a
-  bare model id shape.
-- 장점, 단점 및 영향: preserves `gpt-5.5 max -> xhigh` repair for native traffic, removes false
-  clamps for bare routed models, and keeps adapter-specific effort mapping as the single source of
-  truth for third-party providers.
-
-## Subagents
-
-New non-OAuth provider registrations carry `initialModelSelection` with a unique
-registration identity. Until reliable live/static discovery completes, public
-catalogs and model candidates withhold those providers' models; the provider itself
-stays active. At 20 or more canonical Models switch rows, initialization appends
-all corresponding disabled selectors once. Existing registrations and later manual
-choices are not reinitialized. OAuth/ChatGPT forwarding is exempt using the same
-usable-key override predicate as routing. Display aliases do not add switch rows.
-
-`src/providers/initial-model-selection-runtime.ts` commits the decision against a
-matching registration/inventory snapshot before catalog authority is captured.
-Ordinary management discovery also completes it with Codex integration OFF. The
-final catalog merge fences pending retained rows, including delete/re-add recovery.
-Raw management rows remain visible as pending/OFF. Config listener bindings are
-excluded from inventory identity because live and persisted bindings may differ.
-
-Codex `spawn_agent` advertises only the highest-priority first five picker-visible catalog rows.
-Use at most five configured `subagentModels` ids; they may contain bare catalog ids, routed
-`provider/model` ids, or exact account-qualified `<selector>/<native-openai-model>` ids. The
-dashboard offers bare native and routed choices; exact account-qualified choices are configured
-through `ocx agent subagents set` or the opencodex configuration.
-
-When account selectors are active, one featured bare native id expands into a complete selector row
-group. Catalog priorities use the selector count as a stride so each group stays together without
-widening Codex's five-row advertisement window. Fresh defaults are Astra, Sol, Terra, Luna, 5.5.
-Startup upgrades unmarked rosters once: prepend `gpt-6-astra`, retain the first four unique
-non-Astra choices, then move retained bare `gpt-5.5` last. The old fifth choice is dropped;
-an unmarked empty list becomes Astra only, and an unset list receives the fresh defaults.
-`subagentModelsVersion: 1` records completion, so later user edits (including an empty list or
-removing Astra) persist. The migration rebases on the latest disk config under the existing
-mutation lock; failed persistence degrades to an in-memory roster for that run without a stale
-whole-config overwrite. Existing disabled-model visibility rules remain unchanged.
-
-Quota-aware fallback walks a configured chain when the featured model is exhausted, probing
-availability on a bounded interval (default 60 s, `src/codex/subagent-model-fallback.ts`). It rewrites
-the requested model id only; effort remains owned by the caps described under
-[Ultra reasoning level](#ultra-reasoning-level).
-
-`injectionModel` and `injectionEffort` are shared selections with two independent consumers.
-`multiAgentGuidanceEnabled` controls only OpenCodex-authored delegation guidance.
-`syncCodexSubagentDefaults` is a separate, default-off opt-in that applies the selected values to
-Codex's native `[agents]` defaults on sync/restart for newly created Codex tasks when OpenCodex owns
-the active Codex routing; external user-managed provider configs remain untouched. It does not itself
-cause delegation. The TOML edit owns only marker-tagged values, preserves existing unmarked
-user-owned `[agents]` defaults rather than overwriting them, and rejects ambiguous table shapes
-without changing the file.
-
-V2 proxy guidance uses `<opencodex_subagent_guidance>` for both built-in metadata and
-custom `injectionPrompt` bodies. The built-in text reports the resolved preferred model,
-effort, roster and fallback chain without prescribing delegation, spawn overrides or
-`fork_turns`. Custom bodies retain their placeholder behavior. The guidance switch and
-catalog-state gates still apply; stale or unknown catalog state suppresses proxy guidance.
-V1 uses the shared `MULTI_AGENT_MODE_HINT_RECOMMENDATION.text` inside `<multi_agent_mode>`
-at `max` or `ultra`. Only the separate explicit delegation-request trigger changes; user,
-authority, task-scope and collaboration-tool rules remain applicable. This is guidance,
-not an enforcement mechanism or a change to native settings or tool access.
-
-Replay deduplication compares the latest exact generated developer text separately for
-each tag family, preserving built-in → custom → built-in transitions without duplicating
-unchanged proxy metadata after a native policy change. Native and legacy-tagged history
-remain intact: tags do not establish historical authorship or revoke old instructions,
-and mixed-version transition detection is not guaranteed.
-
-The native mode hint is separate from proxy guidance and native `[agents]` defaults.
-`src/codex/multi-agent-mode-policy.ts` owns the proactive recommendation; the dashboard
-obtains it from `/api/v2` rather than maintaining its own preset. An explicit dashboard,
-API or CLI hint write passes through `setMultiAgentModeHintText`, which replaces only
-the two byte-exact released OpenCodex presets with the current recommendation. Other
-valid custom text, including whitespace variants, is preserved. Reads, unrelated writes
-and upgrades do not migrate stored hints. The writer retains its native capability check
-and stores only `features.multi_agent_v2.multi_agent_mode_hint_text` in Codex TOML;
-`null` removes that key. The hint affects new native Codex sessions when their v2 surface
-is active, without changing reasoning effort or the proxy guidance switch.
-
-Claude Code `ocx-*` agent definitions consume the same effective `claudeCode.blockedSkills` policy
-as inbound bundle elision. When the list is non-empty (default: `claude-api`), generated definitions
-whose marker-stripped model resolves to a routed id receive a preventive instruction not to invoke
-those skills. Direct `provider/model` selectors are routed even when their inbound resolution is
-identity. The only unguarded `ocx-self` case is an identity-resolved `claude|anthropic` model while
-native passthrough is enabled; `modelMap` claims and `nativePassthrough:false` restore the guard. The
-guard avoids creating oversized skill messages before the proxy can intervene; inbound elision remains
-the fallback if a client still sends a blocked bundle. An explicit empty list disables both routed-model
-behaviors.
-
-[Decision Log]
-- 목적과 의도: keep generated Claude Code `ocx-*.md` roster files synchronized when the proxy is
-  started or ensured on Linux, Windows, and macOS, including background service restarts.
-- 기존 구현 및 제약 조건: explicit `ocx claude` launches and Management API writes reconciled the
-  files, while the startup call inside `injectSystemEnv` ran only on macOS with system-env enabled.
-  `startServer` is also used as an in-process library/test primitive and cannot safely mutate the
-  real user home on every invocation.
-- 검토한 주요 대안: write from `startServer`; duplicate hooks in each OS service manager; reconcile
-  once from the owning CLI lifecycle after the listener becomes available.
-- 선택한 방식: the foreground/service start and live-proxy ensure paths call one best-effort helper
-  after bind, using the live Management API context-window map and the existing marker-verified
-  atomic roster writer. macOS system-env startup keeps its existing shared-window sync and skips the
-  duplicate call.
-- 다른 대안 대신 이 방식을 선택한 이유: it covers every supported service entrypoint without
-  adding home-directory side effects to server-library consumers or creating a second roster format.
-- 장점, 단점 및 영향: stale OpenCodex-owned definitions converge on every daemon start, disabled integration
-  prunes them without provider discovery, and catalog failure falls back to unmarked definitions so
-  startup remains available. A later dashboard save or `ocx claude` launch restores missing context
-  markers after a transient failure.
-
-
-### Saved picker presets
-
-The Models page saves routed snapshots in `modelPickerOrder` and records their origin in
-`modelPickerOrderMode` (`alphabetical`, `provider`, `most-used`). Mode is UI provenance, not a
-catalog sorting policy: catalog writers consume the saved array. Routed-only featured/native
-bands and complete-picker natural-rank preservation remain as described above. Public
-`buildCatalogEntries` accepts the order as its final argument and applies the complete-order
-pass after building. On-disk convergence retains its existing post-merge final pass.
-
-Claude ModelInfo ordering receives optional `{ modelPickerOrder, featured }` after `fastRows`.
-It orders routed output groups after alias deduplication, preserving the collision winner and
-base/1M/Fast siblings. Native groups and explicit Desktop profile ownership are unchanged.
-Native Codex advertisements still follow display priority; private guidance ranks do not freeze them.
diff --git a/structure/04_transports-and-sidecars.md b/structure/04_transports-and-sidecars.md
deleted file mode 100644
index 3aac18b6ef..0000000000
--- a/structure/04_transports-and-sidecars.md
+++ /dev/null
@@ -1,1859 +0,0 @@
-# Transports And Sidecars SOT
-
-## Background service command selection
-
-A bare `ocx service` is an idempotent install-or-repair command. Argument validation happens before
-any platform status probe. macOS and Linux choose from the registration file's proven presence;
-Windows combines the Task Scheduler and WinSW probes into `installed`, `absent`, or `unknown`.
-Only proven absence enters registration. A query failure refuses the bare command with status
-guidance, because treating `unknown` as absent can rerun elevated `schtasks /create` against an
-existing task. Explicit `ocx service install` remains the operator-owned registration request.
-
-[Decision Log]
-- 목적과 의도: Make a bare service refresh safe and idempotent without converting a localized or transient Windows status failure into an elevated re-registration.
-- 기존 구현 및 제약 조건: The command defaulted to install and later used a boolean diagnostic whose scheduler query fallback could collapse unknown into absent; repair must preserve the existing Windows launcher and Bun stability workarounds.
-- 검토한 주요 대안: Always repair; keep a boolean installed check; infer presence from saved state alone; use a tri-state live registration probe.
-- 선택한 방식: Validate arguments first, then use a narrow tri-state platform probe only for a bare backend-neutral invocation; route installed to repair, absent to install, and unknown to a refusal.
-- 다른 대안 대신 이 방식을 선택한 이유: Saved state can be stale and unconditional repair breaks first install, while a boolean cannot represent the exact uncertainty that must fail closed.
-- 장점, 단점 및 영향: Healthy existing services avoid UAC and registration churn; stale Windows scheduler definitions may be refreshed and require elevation. Invalid input performs no status I/O, and uncertain Windows hosts require one explicit status/installation decision instead of risking a destructive guess.
-
-## Windows startup ownership listing reuse
-
-One proxy startup asks service-home ownership twice before listen: once before cache invalidation and
-again immediately before native-main lifecycle preparation. The second targeted Task Scheduler query
-is a deliberate race check and remains mandatory. On a localized host, however, the same nonzero
-targeted answer can require a full task listing with a 20-second ceiling; running that identical
-enumeration twice made a measured 12.3-second fallback cost roughly 25 seconds before listen.
-
-[Decision Log]
-- 목적과 의도: Preserve the race-sensitive Windows ownership recheck while paying for an unchanged locale-neutral full task listing only once during synchronous startup.
-- 기존 구현 및 제약 조건: Localized `schtasks /query /tn ... /xml` failures need a full listing to prove absence, the listing may legitimately take more than two seconds, and `unknown` must never become `absent` merely to reduce latency.
-- 검토한 주요 대안: Delete the second ownership check; lower the listing timeout; keep a process-wide or TTL cache; reuse an earlier absence regardless of the fresh targeted result; or scope a memo to the two pre-listen checks and key it to the complete targeted result.
-- 선택한 방식: Create one cache inside `startServer`, run every targeted query, and reuse its listing result only when status, timeout/spawn flags, stdout, and stderr are byte-identical. Runtime ownership retries do not receive the startup cache.
-- 다른 대안 대신 이 방식을 선택한 이유: Removing or weakening revalidation widens the install race, while a global/TTL cache can outlive startup and stale absence can authorize the wrong home. Exact targeted-result identity lets the ordinary no-task locale fallback coalesce without hiding changed evidence.
-- 장점, 단점 및 영향: The reported stable zh-CN absence path performs two cheap targeted queries and one full listing. A task that appears is detected by the second targeted query; changed or failed evidence triggers a fresh fail-closed decision, so unusual churn may still pay for two listings rather than guess.
-
-## Stable service launcher (launchd and systemd)
-
-Launchd and systemd installation resolve the first absolute `ocx` PATH candidate that is both a regular file
-and executable, keeps that path lexical so a version-manager shim remains an indirection, and
-records the same single resolution in the service definition and service state. Definition
-construction (`buildPlist`, `buildUnit`) never performs PATH discovery itself: callers provide either the resolved launcher or an explicit direct Bun/CLI
-fallback, keeping diagnostics and tests independent of the host PATH.
-
-Launcher mode omits the package-local Bun provenance pair because an upgrade may delete that
-versioned tree. The only runtime path carried through the launcher is a pre-Bun, proof-bound
-`OPENCODEX_BUN_PATH` whose durable runtime source is `override`; bundled and process fallbacks are
-rediscovered by the current launcher. The API-auth token remains file-backed and is loaded only by
-the service shell at start. On macOS, `start` and detailed `status` compare the live launchd job
-against `expectedLaunchdCommand`, which follows the recorded `launcherPath` rather than re-walking
-PATH, so a launcher-backed job is never misreported as an older plist (#3464).
-
-[Decision Log]
-- 목적과 의도: Keep systemd services upgrade-stable without losing an explicitly trusted Bun override or accepting a non-executable PATH placeholder.
-- 기존 구현 및 제약 조건: Version managers replace package trees but retain lexical shims; Bun dotenv makes ambient override values untrustworthy unless the Node launcher already stamped matching runtime provenance.
-- 검토한 주요 대안: Bake the package Bun and CLI forever; resolve the shim target; accept the first existing PATH entry; drop every runtime override in launcher mode; or preserve only a proof-bound override.
-- 선택한 방식: Require a regular executable lexical launcher, resolve it once during installation, preserve only `durableBunRuntime().source === "override"`, and keep token loading in the existing file-backed shell preamble.
-- 다른 대안 대신 이 방식을 선택한 이유: Resolving or pinning package paths recreates upgrade restart loops, existence-only selection can name a directory or non-executable file, and dropping a trusted override silently changes an operator's runtime.
-- 장점, 단점 및 영향: Mise/asdf-style upgrades keep working and explicit Bun selection survives; source installs still use the direct pair, while a removed or non-executable launcher requires `ocx service repair`.
-
-## Provider diagnostic outbound safety
-
-Provider connection tests and live model discovery share the GET-only provider outbound wrapper.
-Direct HTTP(S) resolves once and pins the validated address; HTTPS preserves the original Host/SNI
-and always verifies certificates. Proxy-configured requests stay on Bun fetch so HTTP(S)_PROXY,
-ALL_PROXY, and NO_PROXY semantics remain authoritative. The wrapper classifies successful local DNS answers, but
-only a typed DNS-resolution failure degrades to proxy resolution; every literal, metadata, and
-resolved-address policy error still rejects. Proxy mode logs once that the proxy-selected peer
-cannot be pinned. Private destinations additionally require allowPrivateNetwork plus NO_PROXY.
-
-Two fake-IP DNS accommodations exist, both for resolved answers only (a literal address in the URL
-still rejects). The IANA benchmark range (198.18/15 and its IPv4-mapped IPv6 spellings) is admitted
-whenever any outbound proxy applies to the host, because the range itself marks the answer synthetic.
-Mihomo's default IPv6 fake-IP range (fdfe:dcba:9876::/48) is ULA and carries no such mark, so it is
-admitted only when the proxy variable that matches the URL scheme is set (HTTPS_PROXY for https:,
-HTTP_PROXY for http:; ALL_PROXY is not consulted because Bun fetch does not honour it), the host is
-not in NO_PROXY, and the request is then bound to that proxy through Bun's explicit `proxy` option
-rather than environment inference. Both gates live in the outbound wrapper, not in classification:
-`classifyIpv6` and config-time validation (`providerDestinationResolvedError`) never admit the
-ULA, so provider save-time checks are unaffected (#3462).
-
-Both paths reject redirects and expose only credential-stripped final-address guidance. This phase
-does not cover ordinary requests, streaming, retries, or per-hop redirect review on those paths.
-Caller-owned `provider.fetch` executors are also deferred: they receive literal/config checks and
-redirect blocking, but cannot inherit DNS classification or peer pinning without a verified-peer
-executor contract. Main-request migration must not treat that branch as fixed-transport equivalent.
-
-## Responses HTTP/SSE
-
-`/v1/responses` is the main Codex-facing endpoint. The server parses Responses input, routes to a
-provider, lets the selected adapter speak the upstream protocol, then bridges adapter events back to
-Responses-compatible streaming output.
-
-### Credential-bearing HTTP redirects
-
-Credential/body-bearing HTTP sends use `redirect: "manual"` at the final executor boundary,
-including dispatch overrides and adapter/sidecar retries. `fetchWithHeaderTimeout` retains its
-legacy final argument for callers but no longer permits default-follow sends. Both same-origin
-and cross-origin redirects remain observable responses: retry helpers must not synthesize a 502
-before the owning route can apply its existing response and health policy. Native Responses and
-compact retain their 3xx/Location relay contract; image and search sidecar owners consume 3xx
-through their existing upstream-error path without relaying Location. This server policy does not govern client-side
-redirect following; providers requiring a redirect must be configured with their final API URL.
-
-### Fetch-helper import boundary
-
-`src/server/responses/fetch-helpers.ts` is a transport leaf shared by Responses, compact, and native
-Chat. Its runtime imports are limited to the Codex WebSocket transport, provider request pacing, and
-the upstream HTTP-version helper. Server, provider, and WebSocket data types remain type-only edges.
-It must not import routing, combos, OAuth, adapters, sidecars, response parsing, logging, or relay
-modules merely because those imports existed in the pre-split `responses.ts` monolith.
-
-### Semantic progress ownership
-
-The Responses proxy does not treat transcript growth as repository progress. It can observe request
-boundaries, response items, tool names and payloads, adapter events, retained bytes, and elapsed
-silence. It cannot observe the client's workspace or prove whether a successful tool result changed
-repository state. Consequently, the active-turn and session-lane gates are concurrency admission
-limits, the translator budget is a live retained-byte limit, the response-state caps are cache
-retention limits, and the stall watchdog is a silence limit. None is a cumulative continuation or
-semantic no-progress budget.
-
-[Decision Log]
-- 목적과 의도: Keep long but progressing client-driven tool continuations valid while locating repository-semantic loop detection at the layer that owns the workspace and continuation policy.
-- 기존 구현 및 제약 조건: Issue #2600 recorded 18 persisted Cursor continuations whose transcript and tool counters grew while the worktree did not. Every proxy-local liveness and capacity bound was therefore satisfied, but the proxy had no workspace delta to compare.
-- 검토한 주요 대안: Stop after a fixed continuation count; classify read-like tool names as no progress; compare assistant prose; emit a new proxy-only terminal code after a time budget; or leave semantic progress to the client while preserving transport cancellation for objective proxy failures.
-- 선택한 방식: Do not add a proxy semantic cutoff without a client-supplied progress contract. Keep objective transport, byte, concurrency, and silence bounds typed and cancellable; require the workspace-owning client to bound repeated continuations using repository state plus its own side-effect ledger.
-- 다른 대안 대신 이 방식을 선택한 이유: Calls and prose are not a repository oracle, and tool names do not prove side effects. A proxy cutoff would either miss the reported loop because items kept changing or terminate legitimate slow work. Retrying after the cutoff could also replay side-effecting work.
-- 장점, 단점 및 영향: OpenCodex does not manufacture a root cause or silently terminate healthy long turns. The combined route still needs a client-side semantic boundary; if a future client sends an explicit privacy-safe progress marker, the proxy may enforce that contract without inferring workspace state.
-
-[Decision Log]
-- 목적과 의도: Keep transport helpers reusable without making every consumer evaluate the full routed Responses and sidecar graph at module load.
-- 기존 구현 및 제약 조건: The original `responses.ts` split copied the monolith import header into `fetch-helpers.ts`; seven helper exports therefore retained 39 distinct runtime import specifiers and reached 326 modules even though the implementations used only three runtime dependencies.
-- 검토한 주요 대안: Leave the imports because current modules have limited top-level side effects; move the helpers again; prune the copied imports and lock the direct runtime boundary.
-- 선택한 방식: Preserve the file and all public exports, remove unused runtime edges, and enforce an explicit three-specifier allowlist with a source-level regression that also proves type-only imports are ignored.
-- 다른 대안 대신 이 방식을 선택한 이유: Relying on unrelated modules to remain side-effect-free makes startup ownership accidental, while another move adds churn without changing the responsibility boundary.
-- 장점, 단점 및 영향: Ordinary native Chat and compact consumers no longer load unrelated routing, combo, OAuth, web-search, vision, and relay modules through this leaf. The allowlist is intentionally strict, so a future helper that needs a new runtime dependency must make that ownership decision explicit in code, tests, and this document.
-
-[Decision Log]
-- 목적과 의도: Prevent routed models from turning invented or neighboring-agent tool names into client-executable Responses calls.
-- 기존 구현 및 제약 조건: The request catalog already controlled custom-tool restoration and the non-OpenAI prompt nudge, but an undeclared upstream name still fell through as an ordinary `function_call`; Codex then reduced the mismatch to a bare `aborted` result.
-- 검토한 주요 대안: Rely only on prompt guidance; automatically translate undeclared `apply_patch` into Code Mode; validate returned names against the request-visible catalog at the final bridge.
-- 선택한 방식: Retain the allowed wire-name set with the existing bridge maps and fail the turn with an explicit compatibility error before emitting any undeclared tool item.
-- 보완된 경계: Key-auth Responses passthrough restores a routed custom call only when the adapter actually lowered that name after request normalization and the caller's `tool_choice` still authorizes it. Native `apply_patch` stays in its upstream function-call form unless the destination explicitly denies Responses custom tools; tools replaced by hosted-provider policy also stay in their upstream function-call form.
-- 다른 대안 대신 이 방식을 선택한 이유: Model guidance is not an enforcement boundary, while automatic translation would invent executable caller intent and arguments after generation.
-- 장점, 단점 및 영향: Streaming and non-streaming routed responses now fail closed with an actionable provider-contract error; providers that emit aliases they never advertised must correct their adapter mapping instead of relying on client abort behavior.
-
-[Decision Log]
-- 목적과 의도: Accept a routed model's decorated outer `apply_patch` delimiter lines without changing the executable meaning of any provider-returned program.
-- 기존 구현 및 제약 조건: Routed custom tools arrive through a public function wrapper and are restored at the response boundary, but arbitrary `exec` JavaScript is caller-executable source whose strings, comments, templates, and helper arguments cannot be safely rewritten with text patterns.
-- 검토한 주요 대안: Regex-rewrite nested helper calls in `exec`; wrap a raw `exec` patch body as a helper call; reject every decorated patch; or normalize only the outer lines of a complete top-level `apply_patch` custom-tool payload.
-- 선택한 방식: After unwrapping the request-authorized custom-tool function shape, normalize only exact decorated Begin/End lines when the entire `apply_patch` input is one structurally recognizable patch with a file operation. Keep `exec` and all other freeform bodies byte-identical.
-- 다른 대안 대신 이 방식을 선택한 이유: A top-level `apply_patch` call already carries explicit executable intent, so its unambiguous outer-line spelling can be repaired without inventing a call or parsing JavaScript. Every broader rewrite could reinterpret ordinary data as code.
-- 장점, 단점 및 영향: Decorated top-level patches regain compatibility while strings, comments, generated source, raw `exec` text, incomplete envelopes, and patch-file content remain untouched. Nested malformed helper source must be corrected by the provider instead of being guessed at the response boundary.
-
-[Decision Log]
-- 목적과 의도: Stop wasting a turn when a routed model submits one complete patch envelope as the entire code-mode `exec` body.
-- 기존 구현 및 제약 조건: The decision above rejected "wrap a raw `exec` patch body as a helper call" because a text rewrite could reinterpret data as code. Rollout evidence then showed about 55 such bodies across four models, each a guaranteed isolate throw. Measurement added the missing fact: a complete envelope is never valid JavaScript, since `*** Begin Patch` fails to parse at the leading `**`.
-- 검토한 주요 대안: Keep failing closed; rewrite decorated delimiters inside `exec` JavaScript; parse `exec` bodies as JavaScript; or retarget only a body that is itself one complete operation-bearing envelope.
-- 선택한 방식: Retarget only that complete-envelope shape to the existing apply_patch helper, through one shared resolver used by all four restore paths. Delimiter-repair functions stay unchanged and every other `exec` body, including JavaScript that mentions an envelope, stays byte-identical. Streaming holds a buffer that could still become an envelope so the live preview is never rewound.
-- 다른 대안 대신 이 방식을 선택한 이유: This narrows the earlier rejection rather than reversing it. The rejection protected bodies with a competing executable reading; a complete envelope has none, so it is the same one-faithful-reading rule the delimiter repair already follows. Rewriting inside JavaScript remains rejected: there the marker is a delimiter or a string or a comment, and no lexical or parse-based rule separates them safely.
-- 장점, 단점 및 영향: A previously wasted turn now performs the edit the model intended. This does convert a hard failure into a real filesystem write, so the predicate stays anchored and operation-bearing; prefixed, suffixed, incomplete, namespaced, and JavaScript bodies still fail closed. The write itself is the same `apply_patch` capability code mode already grants, reached by payload shape instead of tool name.
-
-[Decision Log]
-- 목적과 의도: Keep Codex client-side deferred tool discovery usable through third-party Responses-compatible gateways that implement public function tools but reject the private `tool_search` declaration.
-- 기존 구현 및 제약 조건: The chat translation path already exposed search as a function and bridged its call back to `tool_search_call`; passthrough only promoted definitions returned by an earlier search, so it could not initiate discovery on a strict third-party Responses endpoint.
-- 검토한 주요 대안: Require every gateway to implement Codex-private tool types; route affected models through `openai-chat`; lower the declaration only; lower the noncanonical request and restore both JSON and SSE response lifecycles.
-- 선택한 방식: On noncanonical Responses passthrough only, lower an actually declared `tool_search` to a collision-free public function name, translate its replayed call/output history to public function pairs, record only caller-authorized request-local conversions, and restore matching JSON/SSE calls to client `tool_search_call` items. Canonical OpenAI forward remains byte-shape native.
-- 다른 대안 대신 이 방식을 선택한 이유: Provider-specific workarounds fragment the contract, while unconditional restoration could turn an untrusted ordinary function call into a privileged client discovery action.
-- 장점, 단점 및 영향: Strict third-party Responses gateways can start and continue deferred discovery without changing native ChatGPT behavior; ordinary same-named functions remain distinct, and the proxy performs a capped SSE lifecycle rewrite only when the request actually required compatibility translation.
-
-[Decision Log]
-- 목적과 의도: Keep Codex 0.147 namespace tool catalogs usable after a routed provider adopts native Responses but implements only the public flat tool variants.
-- 기존 구현 및 제약 조건: Chat translation already flattened namespace children, while native Responses passthrough forwarded the private `namespace` variant unchanged. xAI therefore rejected Grok requests before inference after its OAuth Grok 4.5/4.6 route moved to Responses.
-- 검토한 주요 대안: Move Grok back to Chat; special-case only xAI or the reserved `functions` group; flatten every complete namespace on noncanonical Responses and restore request-authorized aliases on return.
-- 선택한 방식: Noncanonical Responses lowers `functions` children to their bare top-level names and every other complete namespace to collision-checked `<namespace>__<name>` aliases after custom/tool-search conversion. It rewrites matching replay calls and tool selectors, records the aliases on the built request, and restores only those aliases in JSON/SSE call items before custom/tool-search lifecycle repair. Canonical OpenAI forward preserves native namespace shapes.
-- 다른 대안 대신 이 방식을 선택한 이유: A transport regression should not discard Responses streaming or create a provider-specific fork, and restoration without request-local authorization could reinterpret an unrelated upstream function as a client namespace call.
-- 장점, 단점 및 영향: Grok and other public-schema Responses gateways accept current Codex catalogs while Codex still receives explicit namespace routing. No `type: "namespace"` value survives the boundary: a group the layer cannot express — empty, nested, or with an unusable child name — is dropped along with the children it cannot represent, because relaying the private shape costs the whole request rather than one tool. Genuinely ambiguous wire names still fail closed, now as a 400 rather than an unstructured 500.
-
-Two coordinates that lower to the same wire name are treated as one tool when they denote one:
-`buildTools` flattens the reserved `functions` group without a namespace, so a bare declaration and
-a `functions` child of the same name are the duplicate the parser already tolerates — and the one
-`promoteClientLoadedTools` produces. The declaration is emitted once instead of failing the request.
-
-Replayed call items are lowered whether or not this turn declares the group they name. A catalog can
-be absent or change mid-session, but the client is still replaying items this layer's own response
-restoration stamped with a private `namespace`. Routed compaction runs this boundary before removing
-the tool surface so request-local aliases remain available for response restoration. Only
-`tool_choice` resolves a bare name through the catalog: a history
-item records which tool actually ran, so re-pointing it at a same-named namespace child would
-rewrite that record on a coincidence rather than translate it.
-
-Codex-private tool fields are removed at the same boundary from one table
-(`CANONICAL_ONLY_TOOL_FIELDS`) rather than one bespoke pass each: `external_web_access` on either
-web-search variant, and `defer_loading` on any declaration, which `activateDeferredTool` clears only
-for tools a `tool_search_output` already loaded. A new private bit is a row there.
-
-After that namespace boundary has produced public function tools, the Grok CLI Responses transport
-applies the same root-schema policy as its Chat transport. A root `oneOf`/`anyOf` is flattened only
-when the shared xAI normalizer can preserve its meaning; an unsafe function is omitted instead of
-letting one incompatible declaration reject the entire request before inference. This is scoped to
-`cli-chat-proxy.grok.com`: public `api.x.ai` keeps native root unions, as do unrelated Responses
-gateways. Both top-level `tools` and Responses Lite `additional_tools` pass through this policy.
-
-Only the ROOT rejects a union, so exclusivity is preserved by moving it down rather than widening
-it: a root `oneOf` whose branches differ in one property becomes that property's `oneOf`, or its
-`anyOf` when the branches are provably disjoint and the two keywords describe the same set. That
-property is also promoted into `required`, because absent it matched every branch — which the root
-`oneOf` rejects. Branches that are wholly identical validate nothing and have no faithful
-flattening, so they omit the tool. The walk carries depth, node, and variant budgets, since nested
-unions are combinatorial and a `$ref` diamond amplifies the same way without ever cycling;
-exceeding a budget omits that one function rather than expanding until memory is gone.
-
-Omitting a function makes `tool_choice` the loose end. A selector naming a dropped tool would reach
-Grok as a dangling reference, and relaxing it to `auto` is worse — the turn would quietly run
-without the tool the caller required. So an `allowed_tools` list drops the omitted entries while any
-remain, and a selection with nothing left to point at fails locally with the same 400 a tool catalog
-this proxy cannot lower already returns.
-
-The same noncanonical boundary strips ChatGPT's private `external_web_access` bit from routed
-`web_search` declarations. The public tool remains enabled and all other options remain intact;
-canonical OpenAI forwarding preserves the bit. xAI's public Responses schema enables browsing by
-the presence of `web_search` and rejects the private argument, so forwarding it made the first
-post-namespace request fail with HTTP 400.
-
-The option-aware `openai` provider uses `openai-responses` with `authMode: "forward"`. Pool mode
-resolves main plus added accounts through affinity/quota/cooldown ownership; Direct forwards only
-the allowed Codex/OpenAI auth/session headers from the current request and short-circuits pool
-state. `openai-apikey` uses its configured key and canonical API base URL. Missing credentials fail
-within their route; neither route falls through to the other. See
-[`08_openai-provider-tiers.md`](08_openai-provider-tiers.md).
-
-### Routed service-tier capability
-
-OpenAI-compatible service-tier support is resolved only after the final provider/model wire is
-known. `supportsServiceTier` remains the provider fallback, while the exact
-`modelSupportsServiceTier` map can override it per upstream model, including an explicit `false`.
-The catalog and request path share this decision: a routed row publishes `service_tiers` only when
-the resolved policy is eligible, and the final-route normalizer applies the same gate to
-`service_tier`. Both `openai-responses` and `openai-chat` use the resolved provider/model capability
-for catalog publication, routing evidence, and fingerprints. Canonical Fast injection additionally
-requires a compatible FastWire mapping on the final adapter and an eligible policy. Setting
-`fastMode: false` drops it. On classified Chat routes, `chatServiceTier` separately authorizes
-foreign caller values; an exact-model `true` does not grant that forwarding permission. On
-unclassified Chat routes it gates every caller tier because no canonical Fast capability has been
-validated. An object-form registry wire default may also set `forwardCallerServiceTier: false` to
-close a known subscription gateway while leaving generic unclassified Responses passthrough
-unchanged. Exact `false`
-narrows provider defaults, and provider-level `supportsServiceTier: false` cannot be reopened.
-Capability is namespaced by the selected provider and model; model-name similarity and adapter type
-alone never opt a gateway in.
-
-`POST /v1/responses/compact` handles remote compaction v1 before the generic `/v1/responses` branch
-and before the `/v1/*` guard. Unknown `/v1/*` paths return JSON 404 errors instead of falling through
-to GUI static serving.
-
-Combo compaction recall uses accepted completed-response callbacks to record the final client-visible
-model and originating combo target. The existing child callback gate defers publication until an
-attempt is accepted and drops discarded/failed attempts. Both compaction entry points preserve
-explicit configured selectors before consulting bounded lane state. The existing state-store
-reconciliation owns removal of obsolete targets and generation fencing; core imports no registration
-composition root or Lab code. Recall retains routing identity only, never account credentials.
-
-[Decision Log]
-- 목적과 의도: Complete Cursor turns at the protocol terminal instead of waiting for a separate HTTP-body EOF that may never arrive.
-- 기존 구현 및 제약 조건: Cursor can send turnEnded followed by a clean Connect END_STREAM envelope while RunSSE remains open or later closes through an abort-shaped transport error. The adapter logged the clean envelope but did not settle its terminal owner, so a completed-looking turn could remain open until the Responses stall watchdog.
-- 검토한 주요 대안: Shorten the global stall timeout; treat every later abort as success; settle only when the HTTP stream emits end; make the clean Connect envelope authoritative.
-- 선택한 방식: Process preceding frames in order, preserve an already-emitted terminal, run any already-armed drained client-tool finalizer before protocol cleanup clears its grace timer only while the call set is still drained, otherwise finalize once through the existing fail-closed tool-call logic, and settle the transport successfully on a clean Connect END_STREAM.
-- 다른 대안 대신 이 방식을 선택한 이유: The protocol envelope is upstream's explicit terminal signal. Timeout changes only hide the race, and globally swallowing aborts would mask genuine mid-turn cancellation.
-- 장점, 단점 및 영향: Completed Cursor responses no longer wait for the 300-second watchdog when the HTTP body stays open; incomplete tool calls still emit their existing truncation error, and error-bearing Connect terminals remain failures.
-
-A replayed compaction item carries an `encrypted_content` blob only its minting backend can decode,
-and the client replays it on every later turn. The proxy's own `ocx1:` envelopes are transparent
-base64, so they always lower to plain user messages. A native blob is relayed only when there is no
-known serving-identity mismatch and the destination is known to decode native blobs — the canonical
-ChatGPT forward surface, the official OpenAI API, or a provider with the explicit
-`decodesNativeCompactionBlobs` capability. The destination gate alone is insufficient because more
-than one backend, including OpenAI and xAI, mints native blobs: a destination can decode its own blob
-without being able to decode the previous backend's. The same serving-identity mismatch signal
-therefore strips reasoning `encrypted_content` and degrades native compaction blobs through the
-existing opaque-note path. When the thread has no recorded identity, the destination-only behavior
-is deliberately unchanged. Forward auth alone is not evidence: noncanonical forward providers
-receive no caller credentials and may point at any backend. On any other routed destination the blob
-also degrades to the same opaque note the bridged parser uses, because forwarding it there fails the
-turn and the item outlives the failure in the client transcript, repeating on every later turn
-including the compaction turn the proxy itself drives. With `store: false`, request sanitization
-strips ids from every input item, including compact-wire items, matching codex-rs
-(`core/src/client.rs:918-925`). Compact-wire items remain exempt from response-side field backfill.
-
-[Decision Log]
-- 목적과 의도: Keep a session usable after its history crosses backends, instead of wedging it on a
-  compaction blob the current upstream cannot decode.
-- 기존 구현 및 제약 조건: Compaction handling was binary — `ocx1:` envelopes were ours, everything
-  else was treated as a native blob and gated only by the destination, even though multiple backends
-  mint mutually incompatible blobs. Response-side field backfill exempted only `compaction`, so its
-  two sibling types received synthesized ids the client then replayed.
-- 검토한 주요 대안: Tag every compaction item with its minting provider/credential/model identity;
-  drop compaction items on any route change; gate relay on the destination that would decode them.
-- 선택한 방식: Reuse the thread's recorded serving identity to degrade native blobs after a known
-  route change; otherwise retain the destination capability gate, and treat the compact wire family
-  as one enumeration so id-bearing passes cannot diverge per type.
-- 다른 대안 대신 이 방식을 선택한 이유: Full per-item provenance tagging is unnecessary when the
-  existing thread identity proves a route change, while dropping the item would silently discard
-  compacted context and widening unknown-identity behavior needs a separate decision.
-- 장점, 단점 및 영향: A cross-backend session degrades one compaction summary to a note instead of
-  failing every later turn. A self-hosted OpenAI relay keeps its blobs only when explicitly opted in;
-  other routed gateways see a note because routed compaction produces an `ocx1:` envelope.
-
-### Mixed-wire provider defaults
-
-Registry `modelWireDefaults` select an evidence-backed upstream protocol for an exact model without
-changing the provider-wide adapter. Explicit, allowed `modelAdapters` configuration always wins,
-including an entry that opts the model back into the provider-wide wire. Defaults are applied only
-while the configured provider still matches the registry transport, so reusing a preset name for a
-different custom destination does not inherit its upstream assumptions. Object-form defaults may
-also narrow the decision by inbound protocol and authentication mode; an auth-scoped default must
-not leak from a subscription transport into an API-key or forwarded-credential route.
-
-xAI keeps `openai-chat` as its provider-wide compatibility wire, but Grok 4.5/4.6 subscription
-Responses requests default to native `openai-responses`. Existing namespace, hosted-search and
-reasoning-replay normalization remains in force. The reserved `xai` OAuth transport is name-pinned
-to the Grok CLI gateway even if its saved base URL differs; custom provider IDs do not inherit this
-default. API-key requests, translated Chat/Anthropic defaults and other Grok models retain their
-existing wire and tier policy. OAuth still drops caller-owned `service_tier` on either wire.
-
-Native Responses participates in the same pre-stream OAuth HTTP-429 account rotation as the Chat
-bridge. It uses the existing account quorum, cooldown and three-rotation request cap, refreshes
-the complete credential/transport/replay identity, and attributes usage to the serving account.
-Single-account installs do not retry; a missing alternate credential preserves the original error.
-
-Startup removes legacy Grok 4.5/4.6 Chat overrides once and persists the provider-owned
-`xaiResponsesDefaultVersion` marker. Later explicit Chat choices survive restarts. The migration
-rebases under the config mutation lock; unavailable persistence warns and uses an isolated in-memory
-projection without overwriting invalid disk state. Read-only config loading does not migrate.
-
-The dashboard's Chat Completions switch and `ocx provider edit xai --xai-chat on|off` share the
-existing `modelAdapters` lane. On writes Chat for both models; off writes Responses. Unrelated
-overrides remain intact. The legacy PATCH field `xaiResponsesOptIn` retains its direction:
-true selects Responses, false now writes explicit Chat rather than deleting entries. Its derived
-`xaiResponsesOptInState` reflects effective Responses-inbound routing, including registry defaults;
-only genuinely different effective wires report mixed. A switch write also records the migration
-version (without lowering a future version), and provider-form overwrites retain omitted choices.
-
-Native routed Responses code-mode turns also receive the shared result-emission contract in both
-instructions and the lowered exec input description: a bare awaited helper return is discarded by
-the host, so visible results need `text(...)` or `notify(...)` in that first call. Paired exec outputs
-containing only an empty completion/failure wrapper use the shared explanatory annotation. The
-whole result is examined; populated text, image/file parts, unpaired results, shell-only catalogs,
-compaction and OpenAI-operated destinations are untouched. This does not rewrite valid JavaScript
-or reconstruct output that the code-mode host never emitted.
-
-Routed code-mode turns also carry the host contract for the nested helpers, stated in the same three
-injection sites as the result-emission rule (shared catalog nudge, Cursor code-mode guidance, native
-routed Responses instructions): `tools.apply_patch` takes one string that opens and closes with the
-bare patch marker lines (blank lines or indentation around them are tolerated; a decorated or missing
-marker is rejected), the isolate has no `import`/`require`, and a command that outlives
-`yield_time_ms` is polled through `write_stdin` with empty `chars` rather than a shell sleep loop.
-When a code-mode exec result still carries one of the host's failure strings ("expects a string
-input", "The first line of the patch must be", "The last line of the patch must be", "Unsupported
-import in exec"), the native routed Responses, Kiro, and Cursor result paths append a one-line
-recovery hint naming the broken rule; flat shell bridges and foreign MCP namespaces are never
-annotated, Responses and Kiro additionally require the request's verified code-mode catalog, Cursor
-matches the exact `exec` name under its `opencodex-responses` provider without catalog context, and
-Cursor's error classification and Kiro's whitespace and failed-wrapper grouping are unchanged. Both
-halves live in `src/adapters/exec-tool-result-normalize.ts`
-so the pre-call and post-hoc wording cannot drift. This guidance and annotation change rewrites
-neither the model's JavaScript nor its patch payload; the existing name-alias delimiter
-normalization in `src/responses/code-mode-helper-compat.ts` is unchanged, and the host still rejects a
-malformed call exactly as before. Anthropic, Google, OpenAI-chat and command-code result paths
-have no exec-result seam today and are not annotated.
-
-[Decision Log]
-- 목적과 의도: Stop routed models from abandoning `apply_patch` after the Codex host rejects an object argument or a decorated marker, and from blocking a turn in a shell sleep loop when the host offers `session_id` polling.
-- 기존 구현 및 제약 조건: The shared nudge, Cursor guidance and native Responses instructions already carry the result-emission rule from `exec-tool-result-normalize.ts`, but none stated the helper's argument type, the marker rule, the import ban, or the polling protocol; `260905_apply_patch_envelope_gap` refused to rewrite JavaScript bodies (MODE B), so payload repair is off the table.
-- 검토한 주요 대안: Repair the argument shape inside the proxy (rejected: same body ambiguity as MODE B and it turns a rejected write into a performed one); Cursor-only guidance (rejected: the incident was native routed Responses on xAI); annotate every adapter's tool results (rejected: Anthropic/Google/OpenAI-chat/command-code have no exec-result seam and would need a new one).
-- 선택한 방식: One pre-call sentence and one marker→recovery table in the module that already owns the echo pair; inject the sentence at the three existing code-mode sites; annotate at the three existing exec-result seams with an exec-gated, idempotent helper that never changes error status.
-- 다른 대안 대신 이 방식을 선택한 이유: The safe repair for a host contract the model broke is to state it before the call and name it after the failure; keeping both halves in one file is what keeps them consistent.
-- 장점, 단점 및 영향: Code-mode system prompts grow by roughly 600 characters on routed turns; OpenAI destinations, flat catalogs and compaction requests are untouched. An exec result that legitimately prints one of the four phrases gains a recovery line, which is additive text and never an error flip. On Cursor, a structured tool literally named `exec` whose output quotes one of those phrases would also gain that line. The effect on the live Grok defect rate is unmeasured until a re-probe.
-
-[Decision Log]
-- 목적과 의도: Keep Codex hosted web search usable on xAI's public Responses endpoint without forwarding private OpenAI-only fields that xAI rejects.
-- 기존 구현 및 제약 조건: Codex emits `external_web_access`, `search_context_size`, `search_content_types`, and `user_location`; xAI documents a live-only `web_search` tool with domain filters and image flags, while Codex cached mode explicitly forbids external access.
-- 검토한 주요 대안: Strip only the first rejected field; pass every hosted-search field unchanged; disable web search for all xAI turns; normalize only the exact official xAI API destination.
-- 선택한 방식: On `https://api.x.ai` Responses traffic, lower live search to xAI's public shape, map image content requests to `enable_image_search`, remove unsupported OpenAI-private fields, and omit cached/index-only search plus stale selectors because xAI has no non-live equivalent.
-- 다른 대안 대신 이 방식을 선택한 이유: One-field stripping exposes the next schema mismatch and turning `external_web_access:false` into xAI live search widens the caller's network policy; destination scoping leaves custom gateways and canonical OpenAI byte-shape native.
-- 장점, 단점 및 영향: Grok 4.5/4.6 no longer fail every default Codex turn with an unsupported-argument 400; live search remains available when explicitly enabled, while cached search degrades to no hosted search on xAI rather than silently going live.
-
-### xAI string agent-message continuation
-
-`normalizeRoutedAgentMessages` owns raw Responses `agent_message` lowering. Its existing
-nonempty all-readable array behavior remains shared by non-forward destinations. The optional
-`allowStringContent` argument defaults to false and is enabled only by the non-forward adapter
-call when `isXaiResponsesDestination` recognizes HTTPS `api.x.ai` or `cli-chat-proxy.grok.com`
-on the standard port. A nonblank string becomes one `input_text` part with the original text;
-the same author/recipient attribution is retained and the private transport item id is removed.
-
-This addresses readable child-result delivery (#3907), not scheduling or decryption. Blank,
-malformed, ciphertext-only and mixed unknown/encrypted content retains the existing fail-closed
-path. Forward destinations never enable the option. The parser and encrypted-task recovery
-owners are unchanged, and no broad content-schema validation or adapter-wide string conversion
-is introduced. Mocked server fixtures cover parent, child, and parent-result continuation over
-SSE and JSON while preserving actual tool-call/result pairs.
-
-OpenCode Go documents `gpt-5.6-luna` on `/zen/go/v1/responses` while sibling models use its Chat or
-Anthropic endpoints. The built-in preset therefore selects `openai-responses` only for Luna and
-keeps the provider-wide `openai-chat` default for other non-pinned models. This endpoint correction
-does not set `modelResponsesUpstreamStreaming`: client `stream: true` remains real upstream
-streaming until a current-runtime reproduction justifies a separate bounded-JSON compatibility
-policy.
-
-Go's non-forward Responses request path moves valid `additional_tools` wrappers into top-level
-`tools` through `src/adapters/opencode-go-additional-tools.ts`. Placement runs after existing
-custom/search/namespace lowering and before code-mode, compaction and final hosted-tool pruning.
-It does not recalculate wire identities or response aliases. The matcher reads the constructed
-send URL, resolving it with URL semantics, and requires HTTPS `opencode.ai`, the standard port
-and exact `/zen/go/v1/responses`. Normal and endpoint-inclusive bases or split `responsesPath`
-configurations agree; a custom path resolving to Zen or elsewhere does not acquire Go placement.
-Credentials, query, fragment, foreign hosts and other resource paths are excluded. The existing
-URL constructor canonicalizes trailing base slashes before this check. Malformed wrappers remain unchanged and
-the shared mixed-ciphertext agent-message gate remains fail-closed.
-
-The canonical `opencode-go` registry entry defaults to `statelessResponses: true` because Go
-rejects reasoning ciphertext combined with `previous_response_id` (#3838). Existing derive
-logic fills absent values and preserves explicit false; renamed custom configurations receive
-no new destination-based migration. The existing stateless pass sets `store: false`, removes
-stored continuation parameters, and repairs orphan calls/results without claiming execution
-success. A local replay-cache hit supplies history; a miss cannot reconstruct it, so callers
-must resend complete history without `previous_response_id`. This flag also enables the existing
-visible content-to-summary rewrite for SSE and JSON; summary-channel items and opaque reasoning
-blobs keep their existing response handling. The shared recording callback applies the same
-reasoning rewrite under the exact client-visible predicate before caching output, after tool
-restoration and function normalization. This keeps full-content replay fingerprints comparable
-for both full-history-plus-ID and delta continuations without weakening identity checks. Hidden
-summaries and opaque blobs keep their existing cache representation. It does not change streaming selection or Chat
-model routes. Go fixtures cover Luna, Grok and Muse against both response formats.
-
-The canonical OpenCode Go transport also derives `x-opencode-session` from the existing hashed
-session lane before per-model wire selection. One conversation keeps one opaque affinity value
-across Responses, Chat, retries, and key rotation, while sibling subagents remain distinct. An
-operator-supplied header wins case-insensitively. Renamed providers are covered only when their
-fixed key-auth destination still matches the registry; custom and lookalike URLs receive nothing.
-Muse Spark's Responses sanitizer also drops the provider-rejected `search_content_types` and
-`indexed_web_access` fields from plain `web_search` tools while preserving preview tools and
-unrelated models.
-
-[Decision Log]
-- 목적과 의도: Match OpenCode Go's model-specific Luna endpoint without changing sibling model behavior.
-- 기존 구현 및 제약 조건: The preset had one Chat default even though the upstream publishes a mixed Chat, Responses, and Anthropic matrix; operators must retain explicit override precedence.
-- 검토한 주요 대안: Move the whole preset to Responses; infer from the model name; declare one exact registry default; also force bounded JSON from an older conditional terminal report.
-- 선택한 방식: Use one exact Luna wire default and leave upstream streaming unchanged.
-- 다른 대안 대신 이 방식을 선택한 이유: The endpoint mismatch is reproducible from current code and upstream documentation, whereas a current-dev live canary has not established the separate terminal-delivery policy.
-- 장점, 단점 및 영향: Luna reaches its documented endpoint across inbound surfaces and explicit opt-out still works; any future stream workaround remains a separately reviewed compatibility decision.
-
-[Decision Log]
-- 목적과 의도: Give OpenCode Go the stable per-conversation header it requires for prompt-cache routing without exposing raw Codex identifiers.
-- 기존 구현 및 제약 조건: Codex already supplies task and subagent identity, but Go requests reached every adapter without `x-opencode-session`; one static provider header would collapse unrelated conversations.
-- 검토한 주요 대안: Forward a raw thread header; reuse `prompt_cache_key`; configure one global value; inject separately in Chat and Responses adapters; enrich the canonical provider before wire selection.
-- 선택한 방식: Hash the existing parent-qualified session lane with a provider-specific domain, attach it as runtime-only provider metadata before wire selection, and preserve an explicit operator override.
-- 다른 대안 대신 이 방식을 선택한 이유: The lane already separates sibling subagents, while cache keys may represent shared cohorts and adapter-local changes would drift across Go's mixed wire matrix.
-- 장점, 단점 및 영향: Go requests gain stable opaque affinity across normal retries and key rotation without persisted config changes; requests with no stable lane remain headerless rather than receiving a per-request value that defeats affinity.
-
-### Passthrough SSE stream shapes (#314)
-
-Native passthrough SSE has TWO shapes, selected per request in
-`src/server/responses/core.ts`:
-
-- **Default outside Windows: tee + background inspection.** `upstreamResponse.body.tee()` sends
-  branch[0] through a terminal-aware client relay while branch[1] is
-  drained eagerly by `consumeForInspection`/`consumeForResponseLogMetadata`
-  for terminal-outcome recording, quota, the passthrough continuation cache,
-  and request logs. This remains the default shape on bundled Bun 1.3.14.
-- **Terminal-aware eager bounded relay** (`src/server/relay-eager.ts`). Windows
-  uses this single-reader shape for rewrite traffic and for no-rewrite traffic
-  selected by `selectEagerPath` in `src/lib/bun-stream-caps.ts`; the latter keeps
-  `legacy-tee` and known-bad-runtime `auto` on tee as documented. When selected,
-  `response.completed` closes the client stream even if upstream keeps HTTP/SSE
-  alive. Darwin uses it for no-client-rewrite traffic only (neither image-gen
-  aliases nor item-id repair) and is explicit-only: `auto` stays tee even after
-  a future threshold bump. One eager reader + byte-bounded
-  client queue + post-cancel bounded discard-drain replaces the tee and goes
-  directly to the response without a JS rewrite wrapper, preserving the full
-  inspection side-effect set (shared `createSseInspector` factory in `relay.ts`)
-  including the #44 late-terminal semantics.
-
-Both client readers also retain a bounded, redacted message from a bare upstream
-`error` event. If EOF arrives without a real Responses terminal, they synthesize
-one `response.failed` with that message instead of replacing it with `adapter_eof`.
-The delivering reader owns this evidence; an asynchronous tee inspection branch
-cannot reliably supply it before EOF. Inspection independently applies the same
-bare-error rule when EOF arrives, so account health records failure instead of
-clearing avoidance as if the turn had succeeded. Existing real terminals and
-caller cancellation retain precedence on both branches. Native recovery preflight
-also preserves a rejected body reader and its bounded prefix for the normal
-mid-stream failure path; it does not turn that rejection into a decrypt retry.
-
-Native Responses may rebuild once when encrypted function/custom-tool output or
-agent-message content receives the exact known decrypt rejection before output
-commits. Recovery replaces only encrypted parts with an omission marker, preserves
-the raw request object used by continuation persistence guards, and uses the same
-adapter and cancellation path. A missing Content-Type is allowed only under the
-existing successful streaming condition. Default combo preflight classification
-is unchanged; only the native recovery caller supplies the exact error predicate.
-
-Both shapes carry the inbound caller-abort signal separately from the turn/shutdown
-controller. A caller-driven read rejection is 499/client_cancel without pool penalty;
-a genuine upstream reset remains synthetic 502. An already received terminal, including
-one completed by the error-path parser flush, retains its real outcome. Eager relays
-remove the caller listener when done and close signal-cancelled downstream streams even
-when the response-body cancel hook has not run.
-
-The two-shape contract is mirror-commented in `src/server/index.ts`; the real
-`core.ts` gate is source-invariant-tested by `tests/responses/passthrough-abort.test.ts`,
-and the platform matrix lives in `tests/lib/bun-stream-caps.test.ts`. Keep all three
-in lockstep with any passthrough-policy change.
-
-Canonical ChatGPT forward streaming has one transport-specific exception. A
-stable Bun runtime at or above 1.4.0 may use Codex's upstream
-`responses_websockets` transport; bundled Bun 1.3.14, prereleases, and
-unverifiable runtime identities stay on HTTP/SSE. A successful upstream WS
-response is re-encoded to the same SSE surface and forced through the bounded
-eager single-reader relay instead of `tee()`: raw and enveloped frames are capped
-at 4 MiB and the WS producer queue at 8 MiB. Overflow closes the upstream and
-the downstream relay emits its terminal `response.failed` event plus `[DONE]`.
-Pre-open HTTP fallback remains unmarked and follows the ordinary configured
-stream path.
-
-At the canonical ChatGPT destination, HTTP Responses Lite intent is copied into
-the native per-frame WS metadata key, and the routing hint is derived from the
-final outgoing model/tier. No caller identity is synthesized. Noncanonical
-opt-in gateways keep their own metadata policy. Oversized/unsupported-runtime
-HTTP fallback preserves the original HTTP body and Lite header.
-
-Canonical WS quota and response metadata preceding the first Responses event
-are projected into bounded, allowlisted HTTP headers before the response is
-committed. Later quota observations update only the captured serving account;
-they cannot retroactively change HTTP headers already sent to the client.
-Control frames remain bounded, and provider credential/cookie headers are not
-forwarded. Once a WS create may have been sent, a missing prelude, overflow or
-disconnect settles as an errored SSE body rather than a retryable fetch failure,
-so HTTP fallback cannot duplicate that inference. A standalone no-response
-exchange has a 90-second prelude deadline in addition to the upgrade deadline.
-That prelude deadline is a ceiling, not a floor: the exchange runs under the
-caller's abort signal, so a `connectTimeoutMs` shorter than 90 seconds cancels
-an already-sent create before the prelude timer fires.
-These are transport-fidelity guarantees, not a provider-billing guarantee.
-
-Eligible complete-input creates can retain a canonical upstream socket within
-one selected account, credential, thread and turn. Model/tier and immutable
-handshake headers and the selected outbound proxy must also match. Turn-state and turn-metadata headers are
-projected into their same-name per-frame metadata slots; explicit body values win.
-The pool retains at most 32 sockets, expires idle sockets after 30 seconds, and
-retires a socket after five minutes or 32 successful exchanges (after active work
-finishes). Cancellation, errors, idle unsolicited frames and shutdown dispose it.
-A busy key uses a separate one-shot connection rather than interleaving requests.
-
-This is connection reuse, not native incremental-input synthesis: complete HTTP
-inputs are never trimmed and no previous response id is invented. Explicit
-continuation IDs, named lanes, warmup and background requests remain outside this
-pool. A fresh credential-dispatch guard runs before every warm send. Per-exchange
-listeners, response/item correlation and metadata ownership detach before release.
-No pool timer or shutdown registration exists before eligible traffic activates it.
-
-Translated response request-log tracking and the heartbeat relay also reuse
-`createSseInspector`. This keeps every client-facing SSE observation path on
-the same byte-bounded, discard-and-resynchronize frame policy and ensures the
-request-log, first-output, and terminal observers share one payload parse.
-The inspector records a structured `response.failed` status before invoking the
-terminal observer. Native Responses, Chat Completions, Claude Messages, and WebSocket
-request logs must therefore finalize through the context-aware terminal mapper; recognized
-`cyber_policy` terminals stay `400 / cyber_policy` rather than collapsing to a generic 502.
-
-The client-facing boundary treats the first Responses terminal as authoritative in both relay
-shapes. High-confidence policy errors carried as `response.incomplete`, `response.failed`, or a
-top-level `error` are normalized to one `response.failed / cyber_policy` event without changing the
-refusal outcome; later bytes cannot create a second terminal. A clean HTTP 200 EOF with no terminal
-instead emits one `response.incomplete` with `adapter_eof`, followed by one `[DONE]`. Delimiter-less
-EOF candidates follow the owning repair policy: the native boundary accepts a structurally valid
-terminal tail, while an opted-in terminal repair keeps its unframed suffix tainted and emits
-`missing_terminal_event`. Pull/tee and eager relays therefore agree on terminal, sentinel, and
-request-log accounting without promoting a truncated repair candidate.
-
-[Decision Log]
-- 목적과 의도: Turn upstream terminal variants and bare EOF into one deterministic Responses
-  outcome instead of a retryable disconnect or duplicate terminal.
-- 기존 구현 및 제약 조건: Policy refusals can arrive in several SSE envelopes, while a clean EOF,
-  an unterminated final frame, and a read error exercise different pull/tee and eager cleanup paths.
-- 검토한 주요 대안: Forward every byte unchanged; classify only request logs; synthesize a failure
-  after every EOF or read error; normalize the bounded terminal at the client output boundary.
-- 선택한 방식: Rewrite only high-confidence policy terminal shapes, preserve their bounded metadata,
-  flush native terminal candidates before transport-error classification, keep repair-owned
-  delimiter-less candidates tainted, and synthesize `adapter_eof` only when no real terminal exists.
-- 다른 대안 대신 이 방식을 선택한 이유: Log-only classification leaves Codex retry behavior
-  unchanged, while unconditional synthesis can create two contradictory outcomes for one turn.
-- 장점, 단점 및 영향: Both native relay shapes expose exactly one terminal and one sentinel with
-  matching accounting. Ordinary upstream errors remain fail-closed, and policy refusals remain
-  refusals rather than becoming successful model output.
-
-## Standalone Search and exact account selectors
-
-`POST /v1/alpha/search` retains the selected model in its request body. When that value is an
-account-qualified native selector, the server resolves the public namespace, uses only the mapped
-stored Codex credential, and sends the bare native model upstream. That exact path is fail-closed:
-it does not consult Pool active state or affinity when selecting, and its outcomes cannot rotate
-the active Pool account. An account-wide credential failure still quarantines that credential and
-clears stale ordinary Pool affinities so they cannot reappear after reauthentication. Quota and
-transient outcomes from an exact request leave Pool affinities untouched. Ordinary search requests
-keep the normal Direct/Pool sidecar behavior.
-
-Standalone Images and Live requests currently carry neither the account-qualified model selector
-nor a trustworthy thread correlation from the Codex client. They therefore retain normal provider
-routing. Do not infer an exact account from caller-supplied account headers, process-global last
-selection, connection identity, or other ambient state; concurrent threads could cross-route
-credentials. Extending exact routing to those endpoints requires an opaque client correlation that
-can be bound server-side to a previously validated selector.
-
-## Standalone Images
-
-Codex's local `image_gen.imagegen` tool makes a second Images request after the model calls it:
-`POST /v1/images/generations` for generation or `POST /v1/images/edits` for reference-image edits.
-These are standalone Images API routes, not the hosted Responses `image_generation` tool.
-
-`src/server/images.ts` uses the existing ChatGPT/OpenAI fallback unless `images.provider` explicitly
-selects a custom API-key `openai-responses` provider. Explicit selection fails closed when the
-provider is missing, disabled, registry-managed, incompatible, or lacks a usable key; it never
-falls through to another paid upstream. The relay accepts bounded JSON generation and edit requests,
-then forwards the decoded JSON without rewriting Codex's edit schema. Each paid Images POST receives
-one upstream attempt; client cancellation aborts the upstream and pool-only failures update the
-existing account-health state. Unknown Images subpaths still reach the JSON `/v1/*` 404 guard.
-
-When the OpenAI credential path is unavailable or its authentication fails, `generations` (not
-`edits`) may fall back to Google Antigravity if that provider is logged in. The fallback is
-credential-driven: it exists so an image request reaches a real upstream answer rather than dying on a
-local credential error, and it does not apply when the caller selected an explicit keyed custom
-provider, because a configured pool owns its own authentication failure rather than hiding it behind
-separately billed generation.
-
-On non-loopback binds, data-plane authentication and origin policy cover both Images routes. An
-explicit keyed Images provider accepts the proxy admission secret as either an OpenAI-style bearer
-or `x-opencodex-api-key` because the provider key replaces caller authorization before fetch. The
-ChatGPT forward path still requires the dedicated header so its upstream bearer remains distinct.
-
-The API-key `openai-responses` path also adapts Codex's private standalone image tool to the public
-Responses tool surface. A complete `image_gen` namespace is lowered to safe
-`image_gen__<inner-name>` function aliases even when no hosted image tool is present, because public
-Responses runtimes may reserve the namespace itself and reject dotted function names. Native and
-legacy dotted calls replayed in `body.input` are encoded to the same aliases. When any client
-image-gen declaration is replaced by a usable `image_gen__<inner-name>` alias, the adapter also drops
-hosted `image_generation` and deduplicates aliases in stable container order. Empty or malformed
-namespaces do not remove the hosted fallback. Discovery and normalization span both top-level
-`body.tools` and Codex Desktop Responses Lite `input[].type = "additional_tools"` containers.
-
-For a model explicitly listed in `modelPreferHostedTools`, a non-forward Responses provider may opt
-to remove colliding client `image_gen` declarations before this normalization and rewrite their
-selectors to hosted `image_generation`, so a provider-reserved hosted tool takes precedence without
-loosening a caller's tool-choice restriction. The opt-in is intentionally model-scoped: the default
-alias path remains safest for ordinary public Responses endpoints.
-
-For OpenAI API virtual `-pro` models, preference lookup checks the selected public ID first and
-uses the resolved base wire-model ID as a fallback. `modelAdapters` resolves the public ID first and
-the base ID second; the second pass selects the final adapter, and configuration validation mirrors
-both steps.
-
-Client-facing API-key responses perform the inverse mapping: JSON output and SSE function-call
-items restore `{ namespace: "image_gen", name: "<inner-name>" }` so Codex can dispatch the local
-extension. When item-id repair is also enabled, both transforms compose in one SSE parse/stringify
-pass (`src/server/sse-payload-rewrite.ts`) rather than chaining separate JS pull wrappers.
-Inspection and continuation-cache branches keep the raw upstream alias, allowing stored
-replays to return upstream without leaking a client-only namespace shape. The image-gen layer itself
-leaves malformed and empty image-gen namespaces untouched, but on a noncanonical route the general
-namespace boundary above runs after it and lowers whatever remains, so no private group reaches the
-wire. ChatGPT forward mode preserves the private namespace and hosted tool because that backend
-understands their native semantics.
-
-Per-model `modelReasoningSummaryDelivery` is a narrow compatibility layer for
-`openai-responses` gateways whose summary capability is real but whose accepted delivery enum
-differs from Codex. Presence advertises reasoning summaries in the routed catalog and rewrites only
-an already-present `stream_options.reasoning_summary_delivery` at the adapter boundary. It never
-injects summary generation into a request, and config validation rejects a delivery map that
-conflicts with `modelSupportsReasoningSummaries: false` for the same model.
-
-[Decision Log]
-- 목적과 의도: Preserve Codex Desktop reasoning summaries while adapting only the delivery enum rejected by a specific Responses-compatible upstream.
-- 기존 구현 및 제약 조건: The existing boolean capability either passed Codex's enum unchanged or disabled summaries entirely; stale running clients can keep sending the old enum after a catalog refresh.
-- 검토한 주요 대안: Disable summaries; rewrite the enum globally; inject a delivery field when absent; configure a provider-wide value.
-- 선택한 방식: Use a validated per-model allowlisted map, imply summary capability for that model, and rewrite only a caller-provided delivery field at the Responses adapter boundary.
-- 다른 대안 대신 이 방식을 선택한 이유: Upstream enum support differs by model and provider, while global rewriting or injection would change unrelated requests and disabling summaries removes Desktop UX.
-- 장점, 단점 및 영향: Configured models retain the native summary UI and stale clients self-heal; each incompatible model needs an explicit map entry and contradictory opt-out configuration now fails closed.
-
-## Claude Desktop config-library resolution
-
-The Desktop profile writer and the management status probe share
-`resolveDesktop3pConfigLibraryPath`. The resolver reproduces Desktop's own rule rather than a guess:
-an explicit `CLAUDE_USER_DATA_DIR` (or the opencodex override) wins; on Windows
-`%LOCALAPPDATA%\Claude-3p` wins; otherwise the Electron user-data path gains a `-3p` suffix if it
-does not already have one. `configLibrary` is appended to that root.
-
-`Claude-3p` is Desktop's real directory name, assembled at runtime from `"Claude" + "-3p"`, which is
-why searching the app bundle for the literal string finds nothing. It is not a legacy path to migrate
-away from. Resolution stays a pure function of (env, platform, home) so the Windows branch is
-testable on any host: stubbing `process.platform` does not propagate to `os.platform()` under Bun.
-
-[Decision Log]
-- 목적과 의도: 생성된 Claude Desktop 프로필이 설치된 Desktop이 실제로 읽는 디렉터리에 떨어지고, 대시보드 상태가 그 쓰기 대상과 일치하게 한다.
-- 기존 구현 및 제약 조건: 두 호출자가 경로 계산을 각자 복제했고, Desktop이 실제로 참조하는 `CLAUDE_USER_DATA_DIR`와 Windows `LOCALAPPDATA` 분기가 빠져 있었다(#539). 사용자가 프로필 루트를 직접 지정하는 경우도 있다.
-- 검토한 주요 대안: `-3p` 접미사를 구버전 잔재로 보고 제거; 두 디렉터리를 모두 스캔; 레거시 파일을 자동 이전; 크로스플랫폼 해석기를 한 곳에 둔다.
-- 선택한 방식: Desktop 번들의 해석 규칙을 그대로 이식한 override 인지 해석기를 한 곳에 두고, 쓰기 경로와 상태 조회가 같은 함수를 쓴다.
-- 다른 대안 대신 이 방식을 선택한 이유: `-3p`는 Desktop의 정상 동작이므로 제거는 회귀였다. 해석기를 한 곳에 두면 두 호출자의 드리프트가 불가능해지고, 파괴적 이전 없이 상태와 쓰기 대상이 일치한다.
-- 장점, 단점 및 영향: 지원 플랫폼 전부에서 apply 결과가 Desktop에 보인다. 비표준 레이아웃 사용자는 문서화된 override를 써야 하고, 해석기는 Desktop 번들의 규칙 변경을 따라가야 한다.
-
-## Cursor Native Exec
-
-Cursor's experimental live transport can receive server-driven local read/write/delete/ls/grep,
-shell, and fetch exec frames. These frames are denied by default because they bypass Codex's normal
-approval and sandbox path. `nativeLocalExec: "on"` is the explicit config-owner opt-in for trusted
-local experiments; `off` and the backwards-compatible `codex-sandbox` spelling both fail closed.
-MCP, screen recording, and computer-use stay on their separate explicit executor/MCP config paths.
-
-[Decision Log]
-- 목적과 의도: prevent caller-controlled Responses text from authorizing Cursor native local shell, filesystem, or fetch execution.
-- 기존 구현 및 제약 조건: the adapter preserved top-level `instructions`, system messages, and developer messages, then treated a `sandbox_mode ... danger-full-access` prose marker as an exec allow signal in `codex-sandbox` mode.
-- 검토한 주요 대안: keep marker-based authorization, require a future trustworthy attestation channel, or restrict authorization to server-local config.
-- 선택한 방식: keep marker detection only as diagnostic/context and make `nativeLocalExec: "on"` the only non-legacy mode that enables built-in local exec; unset, `off`, and `codex-sandbox` all deny.
-- 다른 대안 대신 이 방식을 선택한 이유: opencodex has no trustworthy per-request sandbox attestation in request text or headers, so any prompt-carried marker is spoofable by data-plane callers.
-- 장점, 단점 및 영향: this closes prompt-to-native-exec escalation while preserving an explicit operator escape hatch; existing configs that relied on `codex-sandbox` must switch to `nativeLocalExec: "on"` for trusted local experiments.
-
-Cursor's generic tool-use prompt filter must preserve every Responses-owned execution-path tool
-that survives the transport budget: unified Desktop `exec` as well as the legacy
-`exec_command`/`shell_command` aliases. The legacy aliases receive Cursor-specific shell guidance;
-unified `exec` keeps its own schema and is surfaced back to Codex as a client tool. It must never
-fall through to the separate native-local-exec dispatcher.
-
-[Decision Log]
-- 목적과 의도: keep fresh Cursor-routed Codex Desktop subagents able to invoke the actual unified `exec` tool exposed by their client catalog.
-- 기존 구현 및 제약 조건: catalog truncation already pinned `exec`, but the later generic-tool filter recognized only bare `exec_command`/`shell_command` and could erase the sole executable client tool while also naming aliases that were absent.
-- 검토한 주요 대안: synthesize a legacy alias, execute `exec` through Cursor native-local-exec, disable generic filtering, or treat every Responses-owned execution-path tool as eligible.
-- 선택한 방식: preserve the existing client tool and schema by filtering with `isCursorExecutionPathTool`; keep alias-specific prompt guidance gated on an alias actually being present.
-- 다른 대안 대신 이 방식을 선택한 이유: Codex Desktop remains the execution and approval authority, no unavailable tool name is invented, and the existing Responses MCP suspension path can relay the call without widening native execution privileges.
-- 장점, 단점 및 영향: unified `exec` survives the filter and returns to Desktop for execution; legacy aliases behave as before; `wait` and unrelated tools remain excluded from generic tool-count prompts.
-
-## WebSocket
-
-The WebSocket endpoint exists at `/v1/responses`, but discovery is opt-in:
-
-```json
-{
-  "websockets": false
-}
-```
-
-`websocketsEnabled(config)` is true only for an explicit `true`. When false, opencodex removes
-`supports_websockets` from injected provider tables and routed catalog entries, keeping Codex on
-HTTP/SSE. When true, Codex may use Responses WebSocket frames handled by `src/server/ws-bridge.ts`.
-If Codex still attempts a WebSocket upgrade while the feature is disabled, `/v1/responses` rejects
-the upgrade with 426 so Codex falls back to HTTP cleanly.
-
-That setting controls the client-facing upgrade only. The transparent upstream
-ChatGPT WS optimization described above is selected independently and still
-returns the same downstream SSE contract. Its WSS route checks NO_PROXY first, then selects the
-first non-empty HTTPS_PROXY, https_proxy, ALL_PROXY, or all_proxy value. HTTP_PROXY alone does not
-route WSS. Unsupported or malformed selected proxy values skip the WebSocket attempt and use the
-existing SSE path immediately; they never fall through to a lower-priority proxy or direct WebSocket
-egress. HTTP/SSE fallback retains Bun fetch's own proxy rules, which do not consult ALL_PROXY.
-
-The endpoint handles `response.create`, ignores `response.processed`, supports warmup
-`generate: false`, and feeds the same request pipeline as HTTP/SSE.
-
-Registry-declared per-model compatibility hints (`modelResponsesUpstreamStreaming`) may ask the
-upstream Responses endpoint for bounded JSON on ANY client transport — WebSocket or ordinary
-HTTP/SSE. The bridge reframes that JSON into the same Responses event sequence
-(`src/server/responses-json-events.ts`): WS turns send the frames as WebSocket messages, while
-HTTP clients that requested streaming receive a synthesized terminal SSE body (created →
-output_item.done → terminal → `[DONE]`). No production registry entry currently opts in:
-DeepSeek V4 Flash used this path while its public-beta Responses stream was suspected of not
-closing on the terminal event, but the official guide documents a
-`response.completed`/`response.incomplete`/`response.failed` terminal with no `data: [DONE]`
-sentinel, and live probes (2026-08-07) confirm the stream closes on the terminal. The relay's
-terminal-output boundary (`src/server/relay.ts`) cuts the stream at that event and synthesizes
-`[DONE]` itself, so DeepSeek streams live again; the registry knob remains as a one-line
-rollback for upstreams that regress, kept suite-reachable by a synthetic-registry fixture in
-`tests/providers/deepseek-inbound-wire.test.ts`.
-Synthesized output is capped at 10,000 items across HTTP and WebSocket reframing. HTTP frames are
-encoded incrementally, so bounded upstream JSON cannot expand into an unbounded event array or SSE string.
-
-DeepSeek V4 Flash keeps native Responses streaming for progressive reasoning, text, and tool-call
-delivery. Its registry entry enables a model-scoped terminal repair before the existing
-inspection/client split. A real `response.completed`, `response.failed`, or `response.incomplete`
-event always passes through unchanged. If every opened output item has a structurally complete
-`output_item.done` and no real terminal arrives for five seconds, the repair emits exactly one
-`response.completed` snapshot and closes the upstream reader. EOF or `[DONE]` uses the same strict
-completion check; open, malformed, duplicate, contradictory, or unknown output graphs fail closed
-as `response.incomplete`, never synthetic success. The repair shares the per-turn translator byte
-budget, preserves backpressure, and composes ahead of item-id/snapshot rewrites so HTTP/SSE and
-WebSocket clients observe the same canonical lifecycle.
-
-`ws-bridge.ts` preserves upstream `failed` and `incomplete` status values in the final WebSocket
-frame rather than always emitting `response.completed`. If the response status is `failed`, a
-`response.failed` frame is sent; otherwise `response.completed` carries through the original status.
-
-## Heartbeat and stall deadline
-
-The HTTP/SSE bridge emits an SSE comment-line keep-alive (`: opencodex heartbeat`) during upstream
-silence to re-arm Codex's idle timer (Codex's default `stream_idle_timeout` is 300 s and ANY SSE
-bytes re-arm it). A comment line is discarded by every eventsource parser without producing an event,
-so strict Responses decoders never see an unknown variant. Those bridge-enqueued keepalive frames do
-NOT count as activity for the bridge's own watchdog: a bounded stall deadline (default 300 s,
-configurable via `stallTimeoutSec`, checked on the 2 s heartbeat tick) closes the stream with
-`response.incomplete` / `upstream_stall_timeout` and cancels the upstream request if no real
-adapter events arrive. Adapter-yielded `{ type: "heartbeat" }` events DO reset the watchdog.
-
-Top-level `emptyCompletionRetry: true` opts Responses turns into one identical replay when an
-upstream turn produces neither output text nor a tool call, including a stream that ends before a
-terminal event. A terminal-less stream is replayed only before actionable output; post-output EOF
-remains incomplete so text or tool calls cannot be duplicated. The default is off because the replay
-may be billable; `OCX_EMPTY_COMPLETION_RETRY=0` is a disable-only emergency override. Streaming and
-buffered HTTP adapters plus `runTurn` transports share the same guard, while combo attempts and
-routed compaction stay excluded. Pre-content reasoning is retained under named event-count and byte
-caps and emits liveness heartbeats while held. A second empty result or retry failure becomes typed
-502 `empty_completion_retry_failed`; usage is merged across sends, and the Logs attempt records
-recovery kind `empty-completion`.
-
-The web-search loop requests `stream: true` for every routed-model iteration, but buffers the events
-needed to decide whether to intercept a synthetic search call. Text explicitly phased as
-`commentary` is safe to forward live because it cannot terminate the turn; this keeps Kiro's
-progress visible. A Kiro stream EOF after user-facing text or reasoning gets one bounded completion
-retry, because neither the upstream text event nor `END_TURN` / `STOP_SEQUENCE` reliably distinguishes
-progress from a final answer. Those two clean-stop reasons prove only that the inference ended; on a
-tool-enabled turn, only the private completion tool authorizes `final_answer`. Any other explicit
-reason already terminated the inference upstream and is reported as a terminal state rather
-than converted into another model request: output-token limits become continuable incomplete output,
-context-window exhaustion becomes a non-retryable `context_length_exceeded` error, filtering becomes
-filtered incomplete output, and a `TOOL_USE` without an actual tool call is a contradiction. Since
-the stop reason arrives only at the end of the stream, `required`-mode assistant text is held inside
-the adapter until a real tool call starts or the stream ends, then released as `commentary` unless a
-private completion call supplied the final answer. Each held event yields a `heartbeat` in its place
-so the stall watchdog stays armed. Synthetic search calls, real tool calls,
-and terminal events remain buffered until the iteration validates. Only the first iteration's final
-response headers/status and any 429 key rotations are handled eagerly. A failure before downstream
-SSE starts returns non-2xx JSON; once headers have started the final response, a generation failure
-is emitted as `response.failed` SSE.
-
-### Pre-stream provider input overflow
-
-A provider HTTP 413 received before streaming starts is unambiguous request-size refusal, but raw
-relay is not compatible with Codex: Codex classifies the unknown status as retryable and resends the
-same oversized turn through its reconnect budget. For a streaming Responses caller, OpenCodex
-therefore converts the final 413 (after any adapter-owned bounded image retry) into one HTTP-200 SSE
-`response.failed` event with `error.code = context_length_exceeded` and `retryable = false`. Codex
-recognizes that terminal contract, marks the context as full, and can run its own compaction policy
-on the next turn. Combo routing treats 413 as a stop condition and performs the conversion only at
-the outer client boundary, so the failed target is never recorded as a successful combo attempt.
-
-Non-streaming Responses callers retain HTTP 413 and receive a JSON `error` with
-`type: invalid_request_error` and `code: context_length_exceeded`, including routed synthetic
-compaction. The upstream body is replaced with the same bounded, proxy-owned message used by SSE.
-Combo attempts retain their existing internal failure accounting; classification happens only at
-the outer client boundary. Local admission and configured outbound-byte refusals keep their own
-distinct codes. Classification does not shrink input or automatically retry compaction.
-The proxy never silently drops
-prompts or images: it does not own the client's transcript, and deleting input would hide data that
-was never analyzed. The streaming error message is proxy-owned and bounded instead of relaying the
-upstream 413 body, which may echo request content.
-
-[Decision Log]
-- 목적과 의도: Stop Codex from replaying a provider-rejected oversized turn and hand the failure
-  to the client's existing context-compaction semantics.
-- 기존 구현 및 제약 조건: Providers can reject before SSE starts; Codex retries raw HTTP 413,
-  while it recognizes terminal `response.failed` `context_length_exceeded`; the proxy cannot edit
-  Codex's persisted transcript safely.
-- 검토한 주요 대안: Relay 413 unchanged; return HTTP 400 JSON; silently remove media or old turns;
-  synthesize a successful assistant warning.
-- 선택한 방식: Preserve HTTP 413 with typed JSON for non-streaming clients, and map the final
-  streaming 413 to one redacted non-retryable Responses failure at the outer request boundary.
-- 다른 대안 대신 이 방식을 선택한 이유: Raw 413 causes a retry loop, HTTP JSON does not enter
-  Codex's context-window path, and silent deletion or fake success loses user intent without fixing
-  transcript ownership.
-- 장점, 단점 및 영향: Codex stops reconnecting and can compact on the next turn; no input is
-  silently lost. The failed turn itself is not auto-replayed, and callers must retry after Codex
-  compacts or reduce the current input.
-
-Kiro transient HTTP 429 recovery is coordinated process-wide after the first throttle: healthy
-traffic remains parallel, but throttled followers wait behind one abort-aware probe and share a
-deadline that is re-checked after every sleep. Event-stream `ThrottlingException` records the same
-deadline for the next client replay. Retries are bounded to three attempts; hard quota responses and
-ordinary 5xx errors are not replayed. Completion fallback rebuilds only replayable text, preserves
-the original user/tool-result turn for reasoning-only attempts, supplies neutral non-empty carriers
-for empty tool output, and validates role alternation plus tool-use/result pairing before transport.
-
-Provider-level `retryOn429` (devlog 260802_429_same_target_retry) is the generic, opt-in
-same-target 429 retry for API-key providers (`authMode: "key"`), primarily single-key pools
-that cannot use multi-key failover. In the pre-stream recovery loop, a 429 waits (`Retry-After`
-or the fixed interval, capped at `maxIntervalMs`) and replays the identical request on the same
-key before any failover, up to `attempts` extra times per request (the budget lives outside the
-recovery loop, so a 413/401 replay cannot re-arm it). The same wait-and-replay applies to every
-other key-auth surface that bypasses that loop: the Responses passthrough wire (e.g. the
-built-in DeepSeek preset), the image/video bridge and web-search sidecar loops (before their
-`on429` key rotation), and Anthropic terminal-guard continuations (before key/account
-failover). The policy covers HTTP-capable adapters only: custom `runTurn` transports in the
-image loop run through an event queue and never receive an HTTP status, so they are outside
-the HTTP retry scope and cannot replay a 429. Codex never retries 429 client-side (openai/codex#30471), so this is the only
-defense for those providers; the final 429 still carries `Retry-After` for clients that honor
-it. Concurrent requests each honor their own policy — there is no process-wide shared cooldown
-(unlike the Kiro pattern), so a rate-limit storm multiplies upstream volume by at most
-`attempts + poolKeys` per request (same-key replays, then failover keys; the pool size is the
-operator-configured `apiKeyPool` length, fixed for the duration of the request). Every surface
-releases (and awaits the cancellation of) the unread 429 body before the backoff, records the
-`rate-limit-429` recovery kind on replay sends, and the bridge loops clear the old
-response-header deadline before the wait and start a fresh one afterward — client cancellation
-is re-checked after the wait, so 499 always wins over a stale-deadline edge, and backoffs never
-consume the connect budget or surface as a 504. The wait is abort-aware:
-once the server observes the client disconnect (Bun propagates it asynchronously, observed
-1–10 s), the sleep is interrupted, the unread 429 body is released, and the request is
-cancelled with 499 before any replay; because the propagation is async, a replay may precede
-the cancel if the interval elapses first (bounded by the same `attempts` budget).
-
-Provider-level `requestPacing` is the proactive companion to `retryOn429`. It reserves outbound
-request-start slots before transport work begins, so a known RPM ceiling does not have to fail once
-before the proxy reacts. One provider-wide lane enforces the aggregate ceiling. Exact model lanes
-may add a slower interval without lowering the provider-wide interval or blocking an otherwise
-eligible sibling model. Queue wait is abort-aware and happens before the response-header timeout is
-armed. The shared fetch boundary covers HTTP and Responses WebSocket sends; explicit adapter
-`fetchResponse` and `runTurn` dispatches reserve the same lane at their call sites. Image-bridge
-iterations reserve before arming their per-attempt response-header deadline.
-
-[Decision Log]
-- 목적과 의도: Prevent Kiro progress from becoming a false final answer, reject invalid empty completion retries, and stop concurrent transient 429s from consuming independent retry budgets.
-- 기존 구현 및 제약 조건: Kiro text has no trustworthy phase; stop metadata arrives only at stream end; the private completion tool is adapter-owned; normal parallel tool traffic must remain parallel; client cancellation must interrupt all waits.
-- 검토한 주요 대안: Trust native `END_TURN`; infer completion from wording; serialize every Kiro request; leave throttling entirely to the client; manufacture empty assistant turns to preserve alternation.
-- 선택한 방식: Require the private completion tool on tool-enabled turns, rebuild only valid replayable wire turns, validate the final conversation, and activate a shared cooldown plus single probe only after a transient throttle.
-- 다른 대안 대신 이 방식을 선택한 이유: Native stop metadata has mislabeled progress, wording is language-dependent, global serialization harms healthy concurrency, client-only retries amplify bursts, and empty structural turns are rejected upstream.
-- 장점, 단점 및 영향: Completion phase is deterministic and throttled concurrency recovers without a request storm; some clean Kiro stops pay one bounded validation call and an exactly repeated completion answer may be shown twice to preserve `final_answer` semantics.
-
-Historical `web_search_call` output items from previous Responses turns are not converted into
-assistant text. They are UI/search-cell evidence, not a replayable search result payload; turning
-them into strings risks routed models echoing an internal marker or implying a current search ran
-when the sidecar is unavailable. The active sidecar path is the only place that emits new
-`web_search_call_begin` / `web_search_call_end` events.
-
-Four independent clocks bound this path. `stallTimeoutSec` is the base bridge event-stall budget.
-`connectTimeoutMs` (default 200 s) covers only DNS/TCP/TLS and the wait for final response headers,
-not response-body generation. Config-file-only
-`webSearchSidecar.routedModelStallTimeoutMs` (default 200 s, integer 1..2147483647) bounds continuous
-raw response-byte inactivity for a routed-model iteration and resets on every non-empty byte.
-`webSearchSidecar.timeoutMs` (default 60 s) separately bounds one hosted search request (lowered
-from 200 s so an unavailable/limit-exhausted search backend degrades within ~1 min instead of
-hanging the whole turn, #398). The
-effective web-search bridge watchdog is
-`max(base stall, connect timeout, routed-model stall, sidecar timeout) + 30 s` (230 s at defaults,
-dominated by the routed-model stall clock),
-with seam heartbeats between bounded units. None of these clocks is a total generation deadline.
-
-## Reasoning and tool-result compatibility
-
-Kiro groups only consecutive original-message tool results whose raw call ID exactly matches
-the originating call. Its wire-ID map retains the original ID privately so replacement or
-truncation collisions cannot join unrelated results. Every non-tool message ends the group,
-including a reasoning-only assistant omitted from the Kiro turns. Group finalization preserves
-single-result normalization, ordered meaningful raw text and whitespace in multi-result output,
-failure text, image order and sticky error status. Empty hints are applied once for an entirely
-text-empty group, not once per chunk; local grouping state never enters the wire payload.
-
-`src/responses/task-input.ts` recognizes complete external Codex task-input envelopes
-before translated Responses adapters: `function_call_output`, no `call_id` property,
-nonblank `id`/`name`/`namespace`, and fully representable nonempty text/image output.
-`parser.ts` emits a user turn, clears pending reasoning and includes that turn in the
-existing continuation conversation-boundary calculation. The metadata is structural,
-not authentication. Unknown/opaque/malformed parts reject the entire conversion;
-ordinary missing/empty tool call ids retain the existing translated-route 400 guard.
-Native passthrough and compaction retain raw-body handling. The leaf reuses the input
-content converter after validation and imports no optional subsystem.
-Stateful developer-guidance injection reuses that validator for its raw insertion
-boundary, so parsed messages and stored raw history retain the same task/guidance order.
-
-Native OpenAI passthrough sanitizes routed reasoning history so `reasoning` input items do not send
-non-empty `content` arrays to upstream models that reject them. Chat Completions bridging repairs
-orphan `toolResult` messages by inserting a synthetic assistant `tool_call` before tool messages.
-It also repairs the opposite direction (260718): an assistant `tool_calls` round left dangling —
-by an intervening user/developer barrier or an interrupted turn — is closed by deferring barrier
-messages until the round completes, reattaching real results to their original call occurrence,
-and synthesizing explicit "no tool result was recorded" answers only when no real result exists
-(Kimi/Moonshot 400 `ocx-mrqaiw05-269`; unit `devlog/_fin/260718_dangling_toolcall_hardening`).
-
-Forward-mode OpenAI passthrough also repairs replayed `call_id` values longer than the Responses
-API's 64-character limit. Sidechat/fork replay can namespace routed-provider ids beyond that limit,
-so each oversized id and all matching call/output items receive the same deterministic,
-request-local alias. Raw API-key continuations deliberately preserve ids because an output-only
-continuation may reference a call stored upstream under its original id; proxy-expanded API-key
-replays are explicit and receive the same repair.
-
-These compatibility guards are covered by focused tests and should stay close to the adapters that
-need them.
-
-Responses passthrough always removes output-only `status` from `reasoning` input items, including
-items that retain opaque `encrypted_content`. The prior retains-blob-keeps-status invariant was
-defensive rather than observed: measured OpenAI reasoning items never contain `status`, and Grok
-accepts its own blob with `status` removed. Keeping it on a cold cross-backend replay instead made
-OpenAI reject the unknown field before validating the blob, starving opaque-blob recovery of the
-provenance error it needs. The established raw-`content` rule remains separate: ChatGPT accepts
-reasoning input only with empty `content`, so a native blob plus raw content keeps the blob but still
-blanks `content`. The blob is kept unless the in-process thread record proves that the current
-provider, destination, adapter, model, or credential differs from the route recorded for the prior
-request on that client thread. On a proven change the blob is removed while the reasoning item and
-its summary survive; `status` has already been removed on every path. Missing, expired, or evicted
-identity state is unknown. The comparison uses the durable destination and credential identities
-with the provider, adapter, and model, so OAuth token-generation refreshes do not look like backend
-changes; when either durable dimension is unavailable it refuses to record rather than falling back
-to a volatile identity. Route binding only compares: it does not replace the recorded identity until
-the destination successfully serves the turn. Bridged streams commit on a completed or incomplete
-terminal; native passthrough streams use the non-error upstream status before relay as their success
-boundary so the proxy does not retain request state across the whole stream. This deterministic
-pre-flight is the primary path and covers threads the process has served while their record remains
-inside the TTL/LRU bounds. Missing, expired, evicted, and
-pre-process history stays fail-soft on the first send. If a Responses upstream then returns its own
-self-identifying opaque-blob 4xx (`invalid_encrypted_content`, or xAI's two `invalid-argument`
-decoder errors), the proxy rebuilds once through the same sanitation path: reasoning
-`encrypted_content` is removed and compaction blobs use the existing text degradation. A one-shot
-guard makes a second rejection terminal, and a successful recovery records the current serving
-identity so later route changes return to deterministic pre-flight. A cold-record cross-backend
-switch therefore costs one extra upstream round trip and one turn of degraded reasoning, rather than
-wedging the thread; unrelated 4xx responses and requests whose outbound body carries no blob never
-enter this recovery.
-
-After a self-identified opaque-blob rejection, the proxy also keeps a five-minute rejection memo.
-The memo key is the resolved conversation identity plus the durable serving identity: provider,
-destination, adapter, model, and credential. It is recorded only when the blobless recovery resend
-succeeds. A missing durable destination or credential prevents memo creation and lookup. On a later
-request with the same key, pre-flight sanitation removes opaque reasoning `encrypted_content` and
-degrades compaction blobs before the first upstream send. This skips the rejected first send and
-the recovery round trip. A different serving identity does not match the memo. Route changes still
-follow the normal pre-flight stripping rule. Memo expiry returns to the fail-soft recovery path.
-
-A combo target rotation between turns legitimately changes that serving identity, so the following
-turn drops blobs minted by the prior target. This is correct because the new target cannot decode
-them, but it is intentionally unobvious to the client: `pickComboTarget` keys selection state only by
-combo id, without a conversation dimension, and the SSE model-name rewrite preserves the requested
-combo name instead of exposing the concrete target switch. A user can therefore observe a reasoning
-cache drop with no visible model change.
-
-The image and web-search auxiliary loops consume `_reasoningReplayScope` for bridge-level replay but
-never call `bindRouteReasoningReplayScope`, so their internal small-model requests do not update the
-serving-identity record. That omission is intentional: binding those routes would poison the main
-conversation's last-serving identity and cause a later main-model turn to strip valid blobs.
-
-[Decision Log]
-- 목적과 의도: Keep same-backend opaque reasoning replay while preventing backend-private blobs and output-only fields from breaking the first turn after a route change.
-- 기존 구현 및 제약 조건: Reasoning-input sanitation already handled raw content and `ocxr1:` envelopes; the replay cache already supplied a bounded, thread-scoped physical-route identity, but no record connected that identity to native `encrypted_content` provenance.
-- 검토한 주요 대안: Strip every opaque blob, persist provenance across restarts, trust generic 4xx prose, rely only on a retry, or combine deterministic route comparison with a narrowly identified recovery.
-- 선택한 방식: Remove output-only `status` from every reasoning input item without changing the pre-existing raw-`content` blanking rule; compare a 64-entry/256 KiB/one-hour in-process serving-identity record using durable destination and credential dimensions before sending, commit it only after the selected destination succeeds, pass a proven change into the Responses adapter before the first send, and use one self-identified opaque-blob recovery only when provenance was unknown.
-- 다른 대안 대신 이 방식을 선택한 이유: The former blob/status coupling was defensive rather than observed, and live backends showed that removing `status` preserves same-backend Grok replay while allowing cold cross-backend requests to reach blob validation. Unknown provenance can still be valid after restart, durable storage is unnecessary for this bounded compatibility hint, and deterministic pre-flight avoids the extra paid or stateful upstream attempt whenever the process has evidence. The upstream's narrow error identity supplies authoritative evidence only for histories the process could not observe.
-- 장점, 단점 및 영향: Same-route and unknown replay retain cached reasoning on the first send without replaying an output-only field, known cross-route replay keeps the reasoning item without its undecodable blob, and a cold cross-route replay can reach opaque-blob recovery instead of failing early on `status`. A repeated blob rejection is surfaced unchanged after exactly one recovery attempt.
-
-DeepSeek's stateless Responses compatibility pass normalizes only unambiguous tool-call batches.
-Calls emitted before the first matched output stay together as one assistant batch, followed by
-their outputs in call order; hook-injected messages that split the batch move after it without being
-dropped. This preserves #1292's single-call adjacency repair without splitting a same-turn parallel
-batch away from its preceding plaintext reasoning (#1477). Tolerant providers never enter this pass,
-and duplicate, missing, or backwards call/result pairs are left for the upstream to reject rather than guessed.
-
-[Decision Log]
-- 목적과 의도: Preserve DeepSeek reasoning replay for parallel tool calls while retaining the provider-scoped repair for hook-interleaved results.
-- 기존 구현 및 제약 조건: Pair-by-pair adjacency fixed one call but split parallel calls into separate assistant turns; DeepSeek always enables parallel tool calling and merges adjacent reasoning and calls into one assistant message.
-- 검토한 주요 대안: Disable parallel calls, duplicate reasoning, remove the #1292 repair, or normalize one unambiguous call/output batch.
-- 선택한 방식: Group calls that occur before the first matched output, emit the call batch followed by outputs in call order, and retain intervening non-tool items after the batch.
-- 다른 대안 대신 이 방식을 선택한 이유: The batch shape matches the documented Responses contract without inventing reasoning or reintroducing hook-interleaving failures.
-- 장점, 단점 및 영향: Sequential and parallel tool continuations both retain their reasoning contract; only the declared strict provider changes order, and ambiguous histories still fail closed upstream.
-
-## Cursor parameterized models
-
-Cursor Router's parameterized `default` model is represented in Codex by four catalog rows:
-`cursor/auto` preserves Cursor's team/account default, while `cursor/auto-cost`,
-`cursor/auto-balance`, and `cursor/auto-intelligence` make each optimization level explicit.
-All four route to the `default` Cursor wire model. Explicit variants additionally populate
-`AgentRunRequest.requested_model.parameters` with the `optimization` parameter; this is the same
-parameterized-model channel used by current Cursor clients. Router rows are static capabilities and
-must survive a live `GetUsableModels` response that omits `default`.
-
-`cursor/grok-4.5-fast` and `cursor/grok-4.6-fast` are stable Codex-facing rows, but current Cursor
-clients do not request them as flat model slugs. OpenCodex sends the matching Grok base id through
-`requested_model` with separate `effort` and `fast=true` parameters, leaving legacy `model_details`
-unset for that parameterized external selection. Grok 4.5 stops at `high`; Grok 4.6 additionally
-advertises and sends `xhigh`. Live discovery recognizes Cursor's flattened
-`cursor-grok-{version}-{effort}-fast` variants, plus the older
-`grok-{version}-fast-{effort}` ordering, as availability evidence only.
-
-## Cursor active-context usage
-
-Cursor's `conversationCheckpointUpdate.tokenDetails.usedTokens` is treated as the authoritative
-absolute active-context size for a Cursor conversation. Some client-tool suspension turns must end
-before Cursor emits a new checkpoint; those turns carry forward the last observed total for the same
-Cursor conversation instead of reporting only the tiny current-turn output delta. The carry-forward
-cache is process-local, numeric-only, bounded, and keyed by Cursor conversation id. Compaction
-boundaries clear the carry so pre-compaction totals are not reused after Codex replaces history.
-Historical compaction markers restored by `previous_response_id` expansion are acknowledged as a
-replayed prefix and do not clear a fresh post-compaction checkpoint again on every later turn.
-Compaction summarizer turns may still report their own checkpoint for that response, but their
-pre-compaction checkpoint is not persisted for later carry-forward.
-
-```text
-[Decision Log]
-- 목적과 의도: Keep Codex's visible "context left" indicator aligned with Cursor's active-context usage on client-tool turns that finalize before a checkpoint arrives.
-- 기존 구현 및 제약 조건: Checkpoint turns reported totalTokens correctly, but no-checkpoint client-tool finalize fell back to output-only usage and could overwrite a meaningful prior total with values like 109 tokens.
-- 검토한 주요 대안: Add a longer wait for late checkpoints; infer prior+output totals; store full prompt/history state; carry forward only the last numeric checkpoint per Cursor conversation.
-- 선택한 방식: Carry forward the last numeric absolute checkpoint per Cursor conversation with bounded LRU/TTL storage, update it only from live checkpoint frames, and clear/suppress it once when a newly appended compaction boundary starts an epoch; previous_response replay provenance acknowledges historical markers without serializing private metadata upstream.
-- 다른 대안 대신 이 방식을 선택한 이유: It fixes the UI regression without delaying tool turns, fabricating token growth, storing prompt/tool content, or repeatedly clearing valid post-compaction usage when historical markers replay; one-time compaction resets still prevent stale over-report when history is replaced.
-- 장점, 단점 및 영향: Active-context reporting stays monotonic within an uncompacted Cursor conversation; no-checkpoint turns remain estimated; a process restart loses the numeric cache, and when neither a checkpoint nor a carry-forward is available the turn reports a request-local estimate derived from the same pruned payload sent to Cursor (#373 — reporting output-only usage made Codex read the context as nearly empty). Estimates are never persisted or promoted into checkpoint carry-forward; only live checkpoint frames update the cache.
-```
-
-## Cursor conversation checkpoint reuse
-
-After a successful no-tool turn, the Cursor adapter keeps the returned ConversationStateStructure in
-a process-local store and reuses that snapshot on the next validated linear continuation instead of
-rebuilding rootPromptMessagesJson and conversationTurns. Tool-result turns reuse the last completed
-checkpoint plus only the uncovered suffix. A request without checkpointRef may use the prefix index
-only when a remembered Cursor conversation or stable client thread owns the resolved conversation id.
-The stable owner may be the Codex parent-thread header or the existing bounded process-local HMAC of
-the complete Desktop session-id/thread-id pair. The request must also have a covered message prefix
-and system/developer digest that match exactly one snapshot for that same
-conversation. Headerless requests without a stable owner full-replay. Isolated helper/shadow turns
-never join the parent or sibling conversation. An explicit missing checkpointRef full-replays. Compaction, account or model mismatch, missing refs, decode failures, and
-invalid_argument recovery keep the existing full-replay path. previous_response_id may select a
-branch's opaque checkpointRef; it is never a Cursor conversation ownership key. Cursor Connect still
-does not expose authoritative cache_read_tokens.
-
-```text
-[Decision Log]
-- 목적과 의도: Reuse Cursor's returned ConversationStateStructure on validated linear continuations so OpenCodex does not rebuild the full root history every turn.
-- 기존 구현 및 제약 조건: Stable conversation ids already exist (#366), but every turn still reconstructed rootPromptMessagesJson and conversationTurns. Cursor Connect still reports only usedTokens/maxTokens, so cache_read_tokens cannot be treated as authoritative (#275).
-- 검토한 주요 대안: Keep full replay; copy Pi's live MCP bridge immediately; store raw protobuf in Responses JSON; key checkpoints only by conversation id.
-- 선택한 방식: Keep an opaque process-local checkpointRef on OcxProviderContinuationState.cursor, bind the snapshot to conversation/account/model affinity, and require a remembered provider conversation or stable client thread before a ref-less prefix lookup. Reuse the bounded process-local Desktop session/thread HMAC when the canonical parent-thread header is absent. Pin referenced blobs for the checkpoint lifetime, and fall back to the existing full-replay path for unowned headerless requests, isolation, compaction, restart, missing refs, and invalid_argument recovery. Tool-result turns reuse the last completed checkpoint plus an uncovered suffix. previous_response_id is a branch anchor, never a Cursor conversation ownership key.
-- 다른 대안 대신 이 방식을 선택한 이유: It removes avoidable replay cost without claiming cache-hit rates, without changing OAuth, and without collapsing helper/compaction isolation or tool-call replay safety.
-- 장점, 단점 및 영향: Validated no-tool follow-ups stop growing local rootBytes with history; a process restart or missing blob lease falls back to full replay; large-context 429 / premature-completion acceptance for #1527 is still unproven; a stateful live MCP bridge remains out of scope.
-```
-
-## Google thought-text visibility boundary
-
-Google-family responses may represent model-internal reasoning as a text-bearing part with
-`thought: true`. The Google adapter maps that text to the internal `reasoning_raw_delta` event;
-only text without the marker becomes visible `text_delta`. Streaming SSE and buffered JSON share
-one classifier so transport selection cannot change whether provider-declared reasoning is shown
-as assistant output. Thought-signature observation still runs on the original parts before text
-classification, preserving the opaque continuation state independently of display semantics.
-
-[Decision Log]
-- 목적과 의도: Prevent provider-marked internal reasoning from appearing as ordinary assistant text while preserving reasoning and tool-call continuation.
-- 기존 구현 및 제약 조건: Both Google response paths emitted every non-empty `Part.text` as visible text; function calls, inline images, and Antigravity/Vertex thought-signature replay already depended on the original part ordering.
-- 검토한 주요 대안: Drop thought text; classify it separately in each parser; remove the marker and keep visible text; use one shared classifier without mutating the provider parts.
-- 선택한 방식: Map `thought: true` text to `reasoning_raw_delta` through one helper used by streaming and buffered parsing, leaving part order and signature observation unchanged.
-- 다른 대안 대신 이 방식을 선택한 이유: Dropping the text loses reasoning replay/display policy input, while duplicated parser rules can drift and exposing marked thoughts violates the provider's visibility boundary.
-- 장점, 단점 및 영향: Internal reasoning no longer leaks into normal answers and both transports stay consistent; downstream reasoning policy still decides whether raw reasoning is rendered or only preserved, and malformed non-boolean markers remain ordinary text rather than broadening hidden-content inference.
-
-## Google response-part field boundary
-
-Google-family adapters validate the values inside an otherwise well-formed response part before
-they become `AdapterEvent`s. A present `functionCall` must be an object with a nonblank string
-`name`; because Gemini delivers that call atomically rather than across deltas, an invalid name is a
-terminal protocol error and is never dispatched. A non-string optional `text` value is dropped
-without coercion, while the rest of the part and turn continue. Structured `functionCall.args`
-remain provider-native and are serialized as before.
-
-[Decision Log]
-- 목적과 의도: Keep malformed Google-compatible response fields from violating the internal string-only text and tool-name contract or dispatching an unidentified tool.
-- 기존 구현 및 제약 조건: Container validation guaranteed object parts, but truthy string/number/array functionCall values emitted a nameless tool call and truthy non-string text values crossed as text or reasoning events. Gemini supplies a complete call in one part, so there is no later name fragment to await.
-- 검토한 주요 대안: Pass malformed values through; coerce them to strings; silently drop every malformed field; terminate the turn for every malformed field; distinguish dispatch identity from optional text.
-- 선택한 방식: Prevalidate function calls and terminate on a non-object, non-string, empty, or whitespace name; drop only non-string text; leave arguments untouched.
-- 다른 대안 대신 이 방식을 선택한 이유: Passing or coercing can execute the wrong tool or fabricate transcript text, while terminating for optional malformed text discards an otherwise usable response. An invalid call name cannot be recovered or safely ignored once the model selected a tool.
-- 장점, 단점 및 영향: Streaming and buffered paths enforce the same AdapterEvent contract and invalid calls cannot enter thought-signature replay. Nonconforming third-party Google-compatible text fields are ignored rather than surfaced, and operators receive a structured terminal error for call identity failures.
-
-## Google tool-call thought-signature replay
-
-Gemini may attach an opaque `thoughtSignature` to a `functionCall` and requires that exact value on
-the matching model turn when its tool result is submitted. Antigravity and Vertex share the existing
-bounded TTL/LRU replay store, keyed by compiled function-call name plus canonical arguments. Vertex
-prefixes its cache model key with the transport, project, and location identity, so a signature
-minted by Vertex cannot be sent to Antigravity even when both routes expose the same public model id.
-Vertex prefers Codex's opaque `prompt_cache_key` for session identity and falls back to the existing
-first-user-message derivation for clients that omit it; only the fixed hash is retained.
-Both streaming and non-streaming responses feed the store; request compilation happens before replay
-so matching uses the provider-visible tool name.
-
-[Decision Log]
-- 목적과 의도: Preserve Vertex Gemini tool-call continuation without exposing opaque signatures to Codex or another Google backend.
-- 기존 구현 및 제약 조건: Responses history does not carry a safe Gemini signature field; Antigravity already used a bounded in-process replay cache, while Vertex bypassed it and received HTTP 400 after the first tool call.
-- 검토한 주요 대안: Serialize the signature into Responses item ids or reasoning content; create an unbounded Vertex map; reuse the bounded cache with or without a transport namespace.
-- 선택한 방식: Reuse the bounded cache for Vertex, observe both response shapes, apply after wire-name compilation, and scope Vertex by transport/project/location plus the opaque client session key when available.
-- 다른 대안 대신 이 방식을 선택한 이유: Responses ids are not Gemini signatures and previously caused Base64/TYPE_BYTES failures; a second cache duplicates limits; an unscoped cache could send provider-private state across destinations.
-- 장점, 단점 및 영향: Tool loops continue with exact opaque state and bounded memory while cross-transport reuse fails closed. Replay remains process-local, matching the existing Antigravity contract.
-
-## Google tool-result adjacency repair
-
-Google-family requests serialize a model tool-call turn and its results as one adjacent
-`model -> user` pair. The user turn contains exactly one `functionResponse` for every representable
-call in original call order. Missing results use an explicit unknown-history marker; duplicate,
-mismatched, and standalone results become marked text instead of unpaired function responses.
-Representable data-URL images remain sibling `inline_data` parts in either case.
-
-[Decision Log]
-- 목적과 의도: prevent interrupted or replayed Claude-on-Antigravity histories from reaching the
-  Google wire with unanswered `functionCall` or unpaired `functionResponse` parts.
-- 기존 구현 및 제약 조건: `messagesToGeminiFormat` emitted every internal message independently;
-  Antigravity translates the resulting Gemini shape back into strict Anthropic tool-use blocks, and
-  rejects malformed adjacency with HTTP 400. Tool-result images cannot live inside a
-  `functionResponse` and already rely on sibling `inline_data` parts.
-- 검토한 주요 대안: repair the shared internal history; synthesize fake calls for orphan results;
-  repair only the Google adapter serialization boundary.
-- 선택한 방식: group only consecutive results after a model call batch, match by the normalized
-  request-scoped call id, emit responses in call order, synthesize an explicit missing result, and
-  degrade remaining results to marked text while retaining image siblings.
-- 다른 대안 대신 이 방식을 선택한 이유: shared-history mutation could change other adapters,
-  while fabricating a successful call would invent model behavior. The adapter boundary owns the
-  strict upstream wire contract and can repair it without changing client-visible history.
-- 장점, 단점 및 영향: normal histories remain byte-shape equivalent, parallel and interrupted
-  histories become provider-valid, and orphan data is not lost. A result separated by a non-tool
-  barrier is intentionally not reattached across that boundary.
-
-## OpenRouter provider routing
-
-The canonical OpenRouter `openai-chat` transport may carry optional provider-routing preferences
-from `OcxProviderConfig.openRouterRouting`, with exact model-id replacements in
-`modelOpenRouterRouting`. The adapter maps camel-case config to OpenRouter's request wire
-(`order`, `only`, `allow_fallbacks`) after the Codex-facing routed slug has been decoded to the
-native model id.
-
-Preferences are accepted only for `https://openrouter.ai/api/v1` (an optional trailing slash is
-equivalent) and the `openai-chat` adapter. Alternate ports, credentials, query strings, fragments,
-lookalike hosts, and custom proxy paths fail validation. A model override replaces rather than
-merges the provider-wide default, keeping precedence deterministic. With no preference configured,
-the request body is byte-for-byte unchanged in this area and OpenRouter retains its default routing.
-
-## Kimi Coding Plan prompt-cache affinity
-
-The canonical `kimi` OAuth and `kimi-code` API-key presets opt into forwarding the internal
-request's `prompt_cache_key` to Kimi's Chat Completions body. Kimi Code Plan documents a stable
-session/task key as required to improve cache hit rates. The chat adapter never invents a key of
-its own: it forwards what the request already carries — Codex's session key on
-`/v1/responses`, or the session-scoped key the Claude `/v1/messages` inbound derives
-(metadata.user_id hash, else the system+tools cohort hash) — and a request with no key stays
-keyless. An explicit provider-level `promptCacheKey: false` continues to opt out, and the flag is
-persisted through `providerConfigSeed`/`enrichProviderFromRegistry` for new configs; key-pool 429
-rotation keeps it — along with every other registry backfill — because the retry starts from the
-fresh committed provider row and routes it again (`rotateProviderTransportOn429` in
-src/providers/key-failover.ts). Stale request-time config fields are deliberately discarded so a
-concurrent deletion stays authoritative; only runtime `fetch` state and generated OpenCode session
-affinity survive the rebuild. If an opted-in upstream rejects the field, OpenCodex does not strip it and retry or mutate the
-saved configuration. Other OpenAI-compatible providers remain deny-by-default because strict
-backends may reject the OpenAI-specific field.
-
-## xAI Grok hardening (official Grok Build contract parity)
-
-Grounded in the open-sourced official client (xai-org/grok-build); unit + evidence:
-`devlog/_fin/260716_grok_build_hardening/`.
-
-- **Reasoning folding:** the Responses parser folds `reasoning` items into the FOLLOWING
-  assistant turn (`pendingReasoning` in `src/responses/parser.ts`) so the Grok chat wire carries
-  ONE assistant message with `reasoning_content` — exact-prefix cache stability. Unsigned
-  siblings newline-join; `ocxr1`-signed siblings stay separate parts (Anthropic replay keeps
-  each signature on its own text); boundaries (user/tool-result/agent) clear pending state;
-  call items fold pending reasoning into the same turn.
-- **Grok CLI credential ownership:** `source:"local-cli"` xAI credentials re-read
-  `~/.grok/auth.json` (read-only) before any refresh and adopt a newer usable generation with
-  zero IdP calls (`shouldAdoptGrokGeneration`, later-expiresAt authority); an IdP refresh
-  detaches the credential to `source:"oauth"`.
-- **Two-lock refresh transaction:** per-provider+account intent lock held across the IdP
-  exchange plus a short global store-write lock + async mutation funnel around every
-  `auth.json` load-merge-persist (`src/oauth/store.ts`); generation-guarded persist
-  (`expectedGeneration` → superseded adoption), conditional `needsReauth`, bounded jittered
-  retry for transient token-endpoint failures.
-- **Reactive 401 replay:** both the adapter recovery loop and native Responses passthrough branch
-  force-refresh once (singleflight, generation-checked) and replay OAuth-backed xAI requests
-  exactly once with a re-resolved transport; API-key/BYOK paths are excluded
-  (`src/server/responses/core.ts`).
-- **Header parity:** per-attempt `x-grok-req-id` (fresh UUID inside the transport fetch
-  wrapper), stable session/conv affinity headers, always-set User-Agent, and a single
-  compatibility profile const for the Grok client version (`src/providers/xai-transport.ts`);
-  `fetchWithHeaderTimeout` takes an executor so provider fetch wrappers stay inside the
-  timeout race.
-
-The generated Grok client marker also enables a client-facing sparse-terminal repair for native
-Responses streams. Grok Build renders text deltas immediately but derives its durable assistant
-turn from `response.completed.response.output`; an OpenAI-compatible stream may instead place the
-complete items in `response.output_item.done` and finish with an explicit empty output array. For
-that marked client only, OpenCodex uses a terminal-only tracker: it retains bounded, contiguous,
-unique and semantically valid raw completed items, then backfills a missing or empty terminal
-snapshot. It never promotes locally synthesized or merely repaired items. Unmarked callers continue
-to treat an explicit empty array as authoritative. Within this marked client-facing repair,
-malformed, gapped, oversized, contradictory, failed, or incomplete streams stay fail-closed.
-
-[Decision Log]
-- 목적과 의도: Prevent Grok Build from classifying a visibly streamed answer as empty and replaying
-  the same billable turn when the terminal snapshot is sparse.
-- 기존 구현 및 제약 조건: OpenCodex already reconstructed missing terminal output for provider
-  opt-ins, but preserved explicit empty arrays; Grok Build discarded ordinary completed-item events
-  when constructing its final conversation response.
-- 검토한 주요 대안: Change every caller's empty-array semantics; accept a turn merely because a
-  text delta was visible; reuse the provider's broader lifecycle synthesis; add a strict repair at
-  the generated Grok client boundary.
-- 선택한 방식: Use the existing generated client marker to opt Grok into a terminal-only repair and
-  backfill only from unique, contiguous, bounded real done items whose raw semantics are valid.
-- 다른 대안 대신 이 방식을 선택한 이유: A global rewrite would alter valid provider semantics,
-  while accepting deltas without durable items would leave persistence and continuation empty. The
-  marker is already the client-specific compatibility boundary; keeping the provider repair separate
-  also prevents synthesized or permissively normalized items from overriding an explicit empty terminal.
-- 장점, 단점 및 영향: Grok receives one durable completed answer without a paid retry; ordinary
-  clients remain byte-semantics compatible. The proxy retains bounded item state for marked streams
-  and intentionally refuses ambiguous reconstruction.
-
-## Kiro client parallel-tool hint
-
-Kiro's wire remains serialized even when an OpenAI Responses client sends
-`parallel_tool_calls: true`. That request field is permissive: it allows parallel calls but does not
-require the routed transport to expose a matching flag. The Kiro catalog therefore continues to
-advertise `supports_parallel_tool_calls: false`, and the adapter emits no parallel-control field,
-while accepting the client hint and translating the ordinary tool catalog normally.
-
-[Decision Log]
-- 목적과 의도: Keep current Codex clients usable with Kiro without claiming or inventing parallel execution on the CodeWhisperer wire.
-- 기존 구현 및 제약 조건: Codex can send `parallel_tool_calls: true` even for catalog rows that advertise false; Kiro has no verified parallel-control request field and serializes tool execution.
-- 검토한 주요 대안: Reject the client hint, rewrite it to false before routing, or accept it as permission while leaving the Kiro wire unchanged.
-- 선택한 방식: Accept either request value, preserve the parsed client intent internally, and omit all parallel-control fields from the Kiro payload.
-- 다른 대안 대신 이 방식을 선택한 이유: Rejection interprets permission as a requirement and blocks valid turns, while rewriting shared request state hides caller intent and can affect later policy or diagnostics.
-- 장점, 단점 및 영향: Codex tool turns reach Kiro again and the adapter contract stays honest; Kiro still cannot produce true parallel tool batches through this transport.
-
-## Kiro Responses text controls
-
-Kiro refuses structured output and tolerates every other Responses `text` member. `text.format`
-of type `json_schema` or `json_object` is a contract the CodeWhisperer wire cannot honour, so the
-adapter rejects it rather than returning prose to a caller expecting JSON. `text.verbosity` and
-`text.format: {"type":"text"}` are preferences, not contracts; they are accepted and dropped,
-because `buildKiroPayload` composes `conversationState` from parsed fields and never forwards the
-raw body.
-
-[Decision Log]
-- 목적과 의도: Stop rejecting valid Kiro turns whose only offence is carrying a Responses text control the wire ignores.
-- 기존 구현 및 제약 조건: The guard tested `_rawBody.text !== undefined`, so `text.verbosity`, `text.format:{"type":"text"}`, and even `text:{}` produced HTTP 400 with sendCount 0 while identical turns without `text` succeeded; `_structuredOutput` already distinguishes real structured output, and the catalog's `support_verbosity: false` helps neither a client holding a cached catalog nor the default text format, which no capability flag governs.
-- 검토한 주요 대안: Keep the presence check, add an openai-responses-style stripper before serialization, or narrow the guard to `_structuredOutput` alone.
-- 선택한 방식: Narrow the condition to `_structuredOutput`; no stripper is needed because the Kiro payload never spreads the raw body.
-- 다른 대안 대신 이 방식을 선택한 이유: The presence check reads a preference as a requirement — the same error `db040e70f` removed for parallel-tool hints — and a stripper would add a serialization stage to defend against a body Kiro already ignores by construction.
-- 장점, 단점 및 영향: Kiro-routed Codex turns stop failing intermittently and structured output stays honestly refused; a future `text` member Kiro genuinely cannot ignore would need its own condition.
-
-## Kiro reasoning round-trip (`redactedContent`)
-
-Kiro never returns plaintext reasoning for its **GPT-5.6 family** (`gpt-5.6-sol`, `-terra`,
-`-luna`): `reasoningContentEvent` carries a KMS-encrypted `redactedContent` blob, never `text`.
-Their `additionalModelRequestFieldsSchema` (`ListAvailableModels`) accepts only `reasoning.effort`
-with `additionalProperties: false` — there is no display/summary opt-in, so this is the only
-reasoning these models can return. Kiro's own CLI replays the blob on the matching
-`assistantResponseMessage.reasoningContent` to preserve model reasoning across turns; dropping it
-makes every turn restart without the previous turn's reasoning. Verified on kiro-cli 2.14.1 and
-2.16.0, all three models.
-
-The Claude 4.6+/5 entries advertise a different, richer contract (`thinking.type` adaptive/disabled,
-`thinking.display` summarized/omitted, `output_config.effort`, `max_tokens`) and are not covered by
-that measurement; older Claude, deepseek, minimax, glm, and qwen entries advertise no additional
-fields at all. The handling below keys off the wire field, not the model id, so any model that
-sends `redactedContent` round-trips.
-
-- The blob rides the existing `ocxr1:` envelope as `krc` (`src/responses/reasoning-envelope.ts`) on
-  an envelope-only reasoning item — `summary: []`, no text deltas — so it stays invisible in the
-  Codex app while round-tripping, exactly like the hidden-thinking path.
-- **Pairing is backwards.** Kiro emits `reasoningContentEvent` at the END of an assistant turn,
-  after content AND tool calls. A `krc`-only item therefore belongs to the turn that already
-  closed, so the parser attaches it to the PRECEDING assistant message rather than folding it into
-  the following turn like ordinary reasoning (`src/responses/parser.ts`). With no assistant turn to
-  own it, the blob is dropped rather than mis-paired.
-- The blob lives on `OcxAssistantMessage.kiroRedactedReasoning`, not on a thinking content part, so
-  no other adapter replays provider-private state if the conversation switches providers.
-
-Kiro reports context pressure in its own `contextUsageEvent`, which is the authoritative source. On
-every capture taken (2.14.1 and 2.16.0) `metadataEvent` carried only `stopReason` — which is why
-reading the percentage from `metadataEvent` alone never saw a value — but the parser still accepts a
-finite `contextUsagePercentage` (and a `tokenUsage` block) there as a fallback, so a value parsed
-from `metadataEvent` is legitimate rather than impossible. Both feed the same field, and any
-positive value overwrites an earlier one.
-
-Spend arrives in `meteringEvent` as **credits, not tokens**. No captured response carried
-`tokenUsage` on any event, which is why Kiro usage stays estimated; `meteringEvent` is currently
-ignored because a credit is not a token count.
-
-## Chat Completions inbound native path
-
-`POST /v1/chat/completions` sends eligible `openai-chat` routes directly to the provider's Chat
-Completions endpoint. Route selection reads the raw Chat body and the native request keeps that body
-as its wire source; a Responses projection is constructed only after the native route is declined
-and is never converted back into Chat. Request construction remains owned by `src/adapters/openai-chat.ts`, including model
-normalization, credential and provider headers, capability-specific fields, and the canonical
-`openaiChatCompletionsUrl()` path. The passthrough builder uses an explicit Chat-field whitelist so
-messages (including `name` and separate `system`/`developer` entries), Chat token controls,
-sampling/logprob fields, caller identity/metadata, and caller stream options retain their wire
-shape. For streams, caller `stream_options` are merged with mandatory `include_usage: true`. On
-the native passthrough there is no canonical Fast injection and no wire mapping: every caller
-`service_tier` — canonical or foreign — is forwarded raw and only under `chatServiceTier: true`,
-and `fastMode` injects nothing here. Resolved-Fast-policy injection applies only to routes that
-take the Chat -> Responses -> Chat bridge below. `parallel_tool_calls` is emitted only for providers opted into
-parallel tools (or pinned false by the existing provider opt-out contract).
-Combo/policy routes and requests that need Responses-only hosted tools, continuation, background,
-or storage semantics retain the existing Chat -> Responses -> Chat bridge.
-
-The direct SSE relay accepts CRLF and arbitrary transport chunk boundaries while retaining at most
-one bounded event. EOF with an unterminated event and an event above the translator limit are typed
-upstream failures, never successful partial completions. Provider-controlled structured error
-messages are redacted before either JSON or SSE reaches the client. The native path uses the same
-request-attempt logging, reset retry, same-key 429 replay, key rotation, usage extraction, and
-request-signal cancellation contracts as routed Responses transport.
-
-## Chat streaming client with a JSON upstream result
-
-The translated inbound path in `src/server/chat-completions.ts` may receive a complete JSON
-Responses result even when the Chat client requested SSE. Its synthetic stream reuses
-`responsesJsonToChatCompletion` as the semantic authority: converted text, reasoning, available
-refusal content, tool calls, finish reason, and usage must survive this final delivery conversion.
-Tool calls gain their array-order stream `index`; the stream retains one assistant-role frame,
-one terminal choice, and one `[DONE]`. Both native and translated JSON fallbacks share
-`jsonCompletionSse`; its temporary frame strings and final body ownership are charged to the
-existing translator budget. Known incomplete limits take precedence over tool finish reasons;
-unmapped incomplete boundaries remain errors. The existing response-body lifecycle owns translation-budget
-release on consumption or cancellation. Actual upstream SSE and native Chat bypass this fallback.
-
-[Decision Log]
-- 목적과 의도: Keep tool execution and incomplete-response detection working when a streaming client receives a JSON upstream result.
-- 기존 구현 및 제약 조건: The existing fallback copied only text and forced `stop`, despite the JSON converter already retaining tool calls, reasoning, and incomplete status.
-- 검토한 주요 대안: Duplicate Responses parsing in the emitter; perform another inference request; preserve the already-converted Chat completion.
-- 선택한 방식: Copy supported converted message fields into one delta, assign tool-call stream indexes, and retain the converted finish reason.
-- 다른 대안 대신 이 방식을 선택한 이유: One conversion authority prevents the streaming fallback from drifting from non-streaming semantics without changing routing or retry behavior.
-- 장점, 단점 및 영향: No additional upstream request or dependency; this remains buffered delivery, not token-by-token upstream streaming. Handler regressions cover tools, reasoning, length, ordinary and empty completions, and budget release.
-
-### Chat refusal projection
-
-`src/chat/outbound.ts` keeps Responses refusal parts separate from ordinary content. JSON output
-and the stream collector expose nullable `message.refusal`; `jsonCompletionSse` preserves it as
-`delta.refusal`, while the native SSE relay remains opaque. The translated live stream keys refusal
-state by raw `output_index` / `content_index`, validates present item IDs as correlation constraints,
-and emits buffered parts in that order only at a valid completed/incomplete terminal. Deltas append;
-equal, empty, absent, and shorter-prefix snapshots preserve existing text; extending snapshots add
-only new text. Non-string or contradictory snapshots fail with a content-free typed error.
-
-The existing turn budget accounts for refusal text and map metadata, including empty entries, and
-releases that state on terminal, failure, or cancellation. Pending role/tool/refusal/finish/`[DONE]`
-frames form one terminal batch: all serialized strings and encoded frames must be admitted before
-any batch frame is enqueued. Admission failure releases the batch and refusal state, cancels upstream,
-and emits only the bounded overflow error. Collector processing failures cancel their reader before
-releasing its lock, so upstream translation cannot continue after failed JSON collection. The outer
-response finalizer continues to own retained response bytes. These are projection rules, not new
-refusal policy or changes to ordinary content/tool semantics.
-
-## Parallel tool calls (default-on for chat providers)
-
-The openai-chat adapter buffers ALL streamed `tool_calls` deltas (keyed by `index`, falling back to
-`id`, then last-seen) and flushes them as atomic start/delta/end sequences at the terminal signal.
-This is required by the bridge's sequential tool-call contract and makes interleaved parallel
-deltas, id-only-first-chunk continuations, and whole-chunk multi-call frames all safe.
-
-Parallel tool calls are DEFAULT-ON for openai-chat providers: the adapter follows Codex's
-request-level `parallel_tool_calls` bit (default true) and routed catalog entries advertise
-`supports_parallel_tool_calls`. `OcxProviderConfig.parallelToolCalls: false` is the per-provider
-opt-out (registry-seeded, router-backfilled; an explicit user value always wins). Non-chat
-adapters advertise the catalog bit only on explicit `true`; cursor keeps its own special-casing.
-Providers with flaky parallel streaming can be opted out individually. Evidence and provider
-ledger: `devlog/_fin/260709_parallel_tool_calls/`.
-
-## Volcengine Ark assistant continuation shapes
-
-The `openai-chat` adapter keeps Volcengine's pay-as-you-go Chat endpoint and Coding Plan endpoint
-on separate empty-assistant contracts. The pay-as-you-go `/api/v3` route retains the structured
-`[{ "type": "text", "text": "" }]` placeholder inferred for #796, while `/api/coding/v3` uses the
-ordinary empty string accepted by its live tool-call continuation contract (#1571). Matching only
-the shared Ark hostname is too broad because the two endpoint families reject opposite shapes.
-
-[Decision Log]
-- 목적과 의도: Preserve multi-turn tool-call continuations across both Ark Chat endpoint families.
-- 기존 구현 및 제약 조건: The #796 workaround was host-wide and unverified; live Coding Plan evidence shows its structured placeholder returns HTTP 400 while an empty string succeeds.
-- 검토한 주요 대안: Remove the workaround globally, select by model ID, or scope it by endpoint path.
-- 선택한 방식: Apply the structured placeholder only to recognized Ark hosts whose normalized base path is exactly `/api/v3`.
-- 다른 대안 대신 이 방식을 선택한 이유: Global removal would reopen #796, while model IDs can appear behind multiple Ark products and therefore do not identify the wire contract.
-- 장점, 단점 및 영향: Coding Plan regains its accepted continuation shape without changing generic providers; any future Ark endpoint family must provide evidence before inheriting the pay-as-you-go quirk.
-
-## Chat structured-output compatibility
-
-First-party Kimi and Moonshot Chat destinations normalize a `$ref` with sibling keywords because
-their wire rejects that valid JSON Schema 2020-12 shape. Inlining preserves conjunction semantics:
-`required` members are unioned, lower numeric bounds take the maximum, upper numeric bounds take the
-minimum, and overlapping `properties` recurse with the same rules. The walk remains depth-, node-,
-and expansion-bounded. Unresolvable or cyclic references keep the existing bare-`$ref` fallback,
-and unrelated OpenAI-compatible providers retain the caller's schema unchanged.
-
-[Decision Log]
-- 목적과 의도: Make Moonshot's compatibility rewrite remove rejected sibling `$ref` shapes without silently weakening a tool schema.
-- 기존 구현 및 제약 조건: The target and sibling both apply under JSON Schema 2020-12, but a shallow shared-property merge let sibling bounds replace stricter target bounds; Moonshot still requires the local bounded rewrite.
-- 검토한 주요 대안: Keep shallow sibling precedence; emit `allOf`; intersect only top-level bounds; recursively compose the supported set-valued and ordered assertions.
-- 선택한 방식: Reuse the existing bound and required intersection rules recursively for overlapping object properties inside the first-party destination gate.
-- 다른 대안 대신 이 방식을 선택한 이유: Shallow precedence weakens constraints, while a new `allOf` wire shape needs separate provider evidence; recursive composition fixes the demonstrated loss without broadening normalization to custom providers.
-- 장점, 단점 및 영향: Looser siblings cannot relax nested constraints and tighter siblings still narrow them; non-ordered conflicting keywords retain the existing sibling precedence and are not treated as a complete JSON Schema algebra.
-
-The `openai-chat` adapter translates Responses `text.format` and Chat Completions
-`response_format` through one internal format, then emits `response_format` on the upstream chat
-wire. That remains the default because silently returning prose breaks clients that requested a
-JSON object or schema. A mixed-capability gateway may list exact native model ids in
-`noStructuredOutputModels`; only those models omit the wire field, while siblings keep the normal
-translation. The proxy does not infer this from provider names, localhost destinations, or a model
-family shared by unrelated upstreams.
-
-[Decision Log]
-- 목적과 의도: Recover chat models that reject `response_format` without removing structured output from models that support it.
-- 기존 구현 및 제약 조건: The adapter forwarded the field to every routed chat model after #1137, while the same model id may sit behind gateways with different capabilities.
-- 검토한 주요 대안: Revert translation globally; blacklist a model id globally; detect a proxy by name or URL; add an explicit provider/model opt-out.
-- 선택한 방식: Preserve default translation and omit it only for exact ids in `noStructuredOutputModels`.
-- 다른 대안 대신 이 방식을 선택한 이유: Global or heuristic rules regress supported providers and make custom gateway names part of the wire contract.
-- 장점, 단점 및 영향: Compatible siblings retain schema enforcement and explicitly incompatible models avoid the upstream 400; operators must classify each unsupported model they route.
-
-## MiniMax Anthropic-compatible clients
-
-The MiniMax platform CLI's text resource posts Anthropic Messages to
-`/anthropic/v1/messages`. `ocx mmx` adapts that hard-coded client path with a temporary
-loopback bridge instead of adding another server route. The bridge accepts only POSTs to the
-messages and count-tokens paths, rewrites them to the existing `/v1/messages` data plane,
-preserves the query and streaming body, strips all incoming credential headers, and pins the
-public loopback placeholder. It stops as soon as the MMX child exits, so the server's
-`AUTH_MATRIX` and authentication surface remain unchanged.
-
-`ocx mmx` exposes only the text resource because the other MMX resources use MiniMax-specific
-image, video, speech, music, vision, search, quota and file endpoints. The launcher isolates
-`~/.mmx` credentials behind a temporary config, removes ambient proxy variables so loopback
-traffic cannot be sent off-machine, owns the temporary bridge lifecycle, and refuses
-destination, region and credential overrides. It is
-loopback-only because MMX cannot carry the dedicated remote-admission header. MiniMax Code uses
-the separate reversible `custom_provider.opencodex` file integration and is likewise
-loopback-only; its generated block never changes `defaultModel`. Each generated MCode model
-copies an authoritative catalog context window into `limit.context` and a nonempty canonical
-reasoning ladder into `thinking.effortOptions`. Missing capabilities stay absent instead of
-falling back to OpenCodex guesses, and the integration does not write the removed
-`thinking.effort` / `defaultEffort` fields because MCode owns the active effort per session.
-
-## Anthropic structured-output compatibility
-
-The Anthropic adapter lowers Responses `text.format` and Chat Completions `response_format` JSON
-Schema requests to `output_config.format`. The local transform follows Anthropic's TypeScript SDK
-subset so upstream rejects neither OpenAI-only envelope fields nor unsupported schema constraints.
-The adapter merges `format` into an existing adaptive-thinking `output_config` rather than replacing
-it, so a compatible `output_config.effort` remains alongside the structured-output format.
-Routed Anthropic Messages input carries `output_config.format` through internal `text.format`, so
-stored-OAuth requests regain the same native format when the Anthropic adapter rebuilds the wire body.
-Unsupported constraints remain in `description` as model guidance instead of disappearing. Root
-`$defs` stay beside a root `$ref`, intentionally differing from the current SDK transform's early
-`$ref` return so local references remain resolvable.
-
-[Decision Log]
-- 목적과 의도: Preserve schema-constrained output when OpenAI-shaped Responses or Chat Completions requests route to Anthropic Messages.
-- 기존 구현 및 제약 조건: The parser retained the requested schema, but the Anthropic adapter dropped it; forwarding the OpenAI schema unchanged fails when it includes constraints outside Anthropic's supported subset.
-- 검토한 주요 대안: Keep tool-call emulation; forward the raw schema; depend on the full Anthropic SDK; maintain a local compatibility transform based on the SDK.
-- 선택한 방식: Merge Anthropic `output_config.format` into compatible adaptive-thinking configuration, mirror the SDK transform locally with strict `unknown` narrowing, move unsupported constraints into descriptions, and preserve root `$defs` before returning a root `$ref`.
-- 다른 대안 대신 이 방식을 선택한 이유: Native structured output avoids synthetic tools, raw forwarding produces upstream 400s, and importing the full SDK only for a small wire transform would duplicate the adapter's direct HTTP ownership.
-- 장점, 단점 및 영향: Both OpenAI-shaped input surfaces gain native Anthropic schema enforcement and unsupported intent remains visible to the model; the copied subset must track upstream SDK changes, description-carried constraints are guidance rather than hard validation, and the root-reference fix is an intentional divergence to keep definitions reachable.
-
-## Reasoning display parity (hideThinkingSummary)
-
-Reasoning-envelope serialization uses preflight byte sizing and transient reservations before
-creating JSON, UTF-8, or base64 copies. Encoding also admits the matching decode projection, so
-a successfully encoded standalone envelope fits the standalone decoder's limit. Callers retain
-ownership of returned values; the helper releases only its temporary reservation. Inbound
-Anthropic translation carries one budget across all assistant blocks and accounts for retained
-envelopes until the response lifecycle disposes it. Standalone translation owns a temporary
-budget and disposes it on success or failure. Final translated-request sizing uses plain-JSON
-measurement rather than allocating a serialized copy just to measure it.
-
-[Decision Log]
-- 목적과 의도: Keep reasoning replay bounded while preserving opaque values exactly.
-- 기존 구현 및 제약 조건: Reasoning continuity needs JSON/base64 envelopes, and existing callers already own retained accounting and typed overflow handling.
-- 검토한 주요 대안: Per-field truncation, an independent fixed field limit, or shared transient admission plus cumulative inbound ownership.
-- 선택한 방식: Reserve conservative copy projections in the envelope helpers and use the existing request budget across inbound blocks.
-- 다른 대안 대신 이 방식을 선택한 이유: Truncation changes signed values; one field limit does not describe aggregate ownership. Existing budget errors retain the established HTTP and stream error contracts.
-- 장점, 단점 및 영향: Normal replay is unchanged; envelope admission includes copy overhead and is stricter than a raw-string length ceiling. These are translator accounting limits, not a process-wide RSS guarantee.
-
-`hideThinkingSummary` (request reasoning summary absent/"none" — the routed catalog default) is
-honored by BOTH reasoning paths: anthropic `thinking_delta` AND raw `reasoning_raw_delta`
-(openai-chat `reasoning_content`, kiro tags). Hidden reasoning emits an envelope-only reasoning
-item (`summary: []`, txt-only `ocxr1:` `encrypted_content`, no text deltas) — invisible in the
-Codex app, so tool cells group like native models — while the text still round-trips for
-`preserveReasoningContentModels` replay. Visible mode (summary "auto") keeps the raw
-`content[reasoning_text]` shape. Diagnosis and codex-rs grouping evidence:
-`devlog/_fin/260709_native_response_pattern/`.
-
-The content-to-summary channel rewrite skips any reasoning item that carries a native
-`encrypted_content` blob. The blob is opaque, state-bearing provider data, so the item must
-round-trip unchanged unless that backend has an explicit replay contract permitting a rewrite.
-This defensively protects providers that issue blobs and later join the route through
-`preserveReasoningContentModels`. The rewrite's round trip was verified against DeepSeek, which is
-`statelessResponses` and issues no blob. Grok is unaffected in practice because it natively emits
-summary-channel reasoning and no `reasoning_text` events, so this content-to-summary item rewrite
-does not engage on its route. Only the stored item is exempt — `reasoning_text` delta events carry
-no blob and still route to the summary channel, so the live expandable trace is unchanged.
-
-The process-local raw-reasoning fallback is fail-closed unless a request has an explicit client
-thread plus an exact provider destination, wire adapter, final model, and physical credential
-identity. API-key material is represented only by a process-keyed HMAC; OAuth replay is bound to the
-existing credential slot and exact credential generation, and an authentication-header override is
-folded into that identity without retaining the raw value. A token refresh intentionally starts a
-new fail-closed replay namespace. The destination is likewise process-HMACed because a configured
-base-URL path may itself be a credential. Header-only/keyless routes cannot establish a physical
-credential identity and therefore fail closed. Parsed-request copies and already-created bridges
-share one scope holder, and key/account rotation replaces its current identity before rebuilding
-the request. A retry may therefore reuse reasoning on the same physical target, but a provider, model, or
-credential failover receives the provider's configured placeholder instead of another target's raw
-reasoning.
-
-[Decision Log]
-- 목적과 의도: Preserve tool-call continuation compatibility without forwarding one provider or physical account's private reasoning to another fallback target.
-- 기존 구현 및 제약 조건: Conversation-only scoping stopped process-global call-id collisions, but combo and 429 failover can reuse the same thread and provider-generated call id across destinations or credentials.
-- 검토한 주요 대안: Disable replay on every failover-capable provider; key only by provider name; use persisted or truncated secret-derived ids; bind the in-memory cache to an exact process-local route and credential tuple.
-- 선택한 방식: Keep a shared mutable scope holder and key entries by thread, provider name, an opaque destination HMAC, adapter, final model, and an opaque HMAC/account identity; incomplete identities read and write nothing.
-- 다른 대안 대신 이 방식을 선택한 이유: Exact binding preserves same-generation same-target retries while making account switches and OAuth token refreshes fail closed, without logging, persisting, or exposing credential material.
-- 장점, 단점 및 영향: Cross-provider/account replay is blocked and rotations are visible to live bridges; providers without a stable credential identity lose cache replay and use the existing minimal placeholder path.
-
-## Chat-to-Responses message phase inference
-
-Chat Completions streams do not carry the Responses `message.phase` field. The bridge keeps an
-unphased live message provisional while its deltas arrive, then assigns `commentary` when a later
-tool, search, reasoning, or assistant boundary proves that more work follows, and assigns
-`final_answer` only when a clean terminal `done` closes the current message. Explicit adapter
-phases always win. Streaming `output_item.added` remains unphased until that future boundary is
-known; `output_item.done` and the terminal response snapshot carry the authoritative inferred phase
-with the same item id. The batch/non-streaming bridge follows the same rule.
-
-```text
-[Decision Log]
-- 목적과 의도: Prevent Codex App from rendering one bridged Chat Completions answer as both live commentary and a second persisted final answer.
-- 기존 구현 및 제약 조건: openai-chat emits text deltas without phase, the bridge streamed them immediately, and whether text is pre-tool commentary or the terminal answer is unknowable until a later boundary arrives.
-- 검토한 주요 대안: Mark every delta final_answer; mark every delta commentary; buffer the entire answer before emitting; infer phase only when the message is finalized.
-- 선택한 방식: Keep the live added item provisional and infer commentary or final_answer at the authoritative close boundary, preserving explicit phases and item identity in done/completed output.
-- 다른 대안 대신 이 방식을 선택한 이유: Eager defaults misclassify either tool preambles or final answers, while full buffering removes live streaming; close-time inference provides correct persisted semantics without adding latency.
-- 장점, 단점 및 영향: Codex App receives a definitive phase for persisted bridged messages and avoids the duplicate-final rendering path; the provisional output_item.added event intentionally has no phase because its classification is not yet knowable.
-```
-
-## Upstream reset retry
-
-`src/lib/upstream-retry.ts` guards upstream fetches against stale pooled keep-alive sockets
-(Cloudflare closes idle connections; Bun's fetch reuses the dead socket and rejects with
-`ECONNRESET` before any response bytes). `fetchWithResetRetry` retries only
-connection-reset-shaped rejections (up to 3 total attempts, jittered backoff, warn-logged);
-timeouts, aborts, `ECONNREFUSED`, HTTP error statuses, and mid-stream SSE failures are never
-retried. Guarded paths: the ChatGPT passthrough and generic adapter fetch in
-`src/server/responses.ts`, the vision/web-search sidecars, and the web-search loop's direct-fetch
-fallback. Adapters with their own `fetchResponse` (kiro, cursor, google) keep their own retry
-policies; kiro imports the shared abort/sleep helpers from this module.
-
-## Same-provider combo quota fallback
-
-For a failover combo with multiple models on the same Codex-login OpenAI provider, a pre-stream
-429/402 carrying only `x-codex-*-reset-at` may advance to the later model on the same account. The
-failed physical combo target still enters its normal target cooldown. An explicit `Retry-After`
-remains an account-wide instruction and blocks the later target; a quota response with neither an
-explicit retry delay nor a usable reset timestamp keeps the conservative default account cooldown.
-This exception is request-scoped and is not applied to direct requests, round-robin combos, or a
-combo whose remaining eligible targets use other providers.
-
-```text
-[Decision Log]
-- 목적과 의도: Let an ordered combo recover when one model-specific Codex quota window is exhausted but another model on the same account remains usable.
-- 기존 구현 및 제약 조건: Account health is shared across models, and recording a reset-derived 429 before combo advancement rejected the later model locally.
-- 검토한 주요 대안: Make every quota cooldown model-scoped; ignore all combo 429 cooldowns; or defer only reset-derived cooldown recording for an eligible later same-provider failover target.
-- 선택한 방식: Use the narrow request-scoped deferral while retaining target cooldown and all explicit Retry-After/default account cooldown behavior.
-- 다른 대안 대신 이 방식을 선택한 이유: Reset timestamps identify quota windows rather than a literal account-wide retry instruction, but widening the exception would risk hot retries and provider abuse.
-- 장점, 단점 및 영향: Same-account model fallback works without weakening explicit upstream backoff; the account health map intentionally does not remember that one deferred reset-derived failure, while the combo target map does.
-```
-
-## Combo streaming commit boundary
-
-An HTTP 200 does not by itself commit a streaming combo child. The combo parent runs the child's
-downstream Responses SSE through `src/server/responses/combo-stream-preflight.ts`, which owns one
-reader and buffers only until one of these boundaries:
-
-- a non-control Responses event begins client-visible output or a tool/action item, after which the
-  target is committed and cross-target replay is forbidden;
-- a `response.failed` terminal arrives first, in which case the terminal is converted back through
-  the ordinary bounded combo-failure classifier and may advance to the next declared target;
-- a completed/incomplete terminal or the aggregate preflight byte or retained-chunk cap is reached,
-  in which case the current target is committed conservatively.
-
-The buffered bytes are replayed unchanged before the reader continues. Native passthrough and eager
-relay identity markers are restored on the wrapped response so Windows/Bun stream paths and deferred
-logging retain their existing owners. A failed child keeps its physical attempt receipt and usage,
-while the successful child remains the logical request result.
-
-HTTP 410 remains terminal by default. It advances and cools only the exact combo target when the
-structured code or message explicitly identifies a model lifecycle event (end-of-life, retired,
-deprecated, sunset, decommissioned, or no longer available). An unrelated application-level 410 is
-not retried.
-
-```text
-[Decision Log]
-- 목적과 의도: Recover a failover combo from a provider-local SSE or model-lifecycle failure only while replay is provably free of duplicate client output and tool calls.
-- 기존 구현 및 제약 조건: The parent committed every HTTP-200 child before reading its SSE body, while terminal stream errors were classified only later by logging; generic 410 responses stopped the chain.
-- 검토한 주요 대안: Retry every failed stream, buffer the complete turn, inspect only HTTP status, or preflight a bounded prefix until an explicit output/terminal boundary.
-- 선택한 방식: Put the one-reader bounded preflight in a dedicated module, commit on any non-control event, and treat only explicit model-lifecycle 410 evidence as target-local.
-- 다른 대안 대신 이 방식을 선택한 이유: Replaying after output can duplicate text or tools, full-turn buffering destroys streaming and grows memory, and making every 410 retryable hides caller/application errors.
-- 장점, 단점 및 영향: Zero-output provider failures can reach a healthy target with ordered receipts and cooldown; ambiguous or oversized pre-output streams keep the current fail-closed behavior instead of consuming unbounded memory.
-```
-
-## Transport inventory
-
-The sections above cover the transports with load-bearing invariants. The rest of the transport
-surface is listed here so a maintainer can find the owner without grepping:
-
-| Transport | Owner | Invariant worth knowing |
-| --- | --- | --- |
-| Azure OpenAI Responses | `src/adapters/azure.ts` | Deployment-shaped URLs on top of the Responses contract. |
-| Google / Vertex / Antigravity | `src/adapters/google.ts`, `src/adapters/google-http.ts`, `src/adapters/google-wire-compiler.ts`, `src/adapters/google-tool-schema.ts`, `src/adapters/google-truncation.ts`, `src/adapters/google-errors.ts`, `src/adapters/google-antigravity-wire.ts`, `src/adapters/google-antigravity-replay.ts` | Vertex and Antigravity install a Google-family `fetchResponse` and so own their retry policy, while AI Studio Gemini leaves it undefined and uses the default server fetch path. The Google-family wrapper reuses the shared abort/deadline helpers (`src/lib/upstream-retry.ts`), wire-body repair, and upstream error normalization. |
-| Mimo Free | `src/adapters/mimo-free.ts` | Client identity and JWT handling are transport-local; the per-install client id lives in the opencodex state root. |
-| Anthropic image ingress | `src/adapters/anthropic-image-guard.ts`, `src/adapters/anthropic-image-normalize.ts` | Oversized or unsupported images are normalized or rejected before reaching upstream. |
-| Adapter execution support | `src/adapters/run-turn-queue.ts`, `src/adapters/tool-catalog-nudge.ts`, `src/adapters/identity.ts`, `src/adapters/image.ts`, `src/adapters/upstream-http-error.ts` | Shared machinery: turn ordering, tool-catalog nudging, client fingerprinting, image conversion, upstream error normalization. |
-| Cursor (beyond the sections above) | `src/adapters/cursor/live-transport.ts`, `src/adapters/cursor/http1-bidi.ts`, `src/adapters/cursor/live-models.ts`, `src/adapters/cursor/transport-retry.ts`, `src/adapters/cursor/mcp-manager.ts`, `src/adapters/cursor/thread-continuity.ts`, `src/adapters/cursor/checkpoint-store.ts` | Thread continuity is the point: a retry must not start a new Cursor thread, and a validated checkpoint must not rebuild the full root history. HTTP/2 remains the default; an explicit `http1.1`/`h1` pin maps the bidi run onto Cursor's `RunSSE` receive stream plus sequenced `BidiAppend` sends, and applies to live discovery too. |
-| Claude Messages | `src/server/claude-messages.ts` | Routed translation, a native Anthropic passthrough branch, and `count_tokens`. |
-| Chat Completions inbound | `src/server/chat-completions.ts`, `src/chat/` | Inbound translation onto the same routing pipeline. The content mapper preserves image URLs and supported detail, including screenshot-bearing tool results; target adapters own image placement on their wire. Image-free tool results stay strings. |
-| Hosted search relay | `src/server/search.ts` | Direct relay; distinct from the web-search sidecar loop below. |
-| Image/video generation loop | `src/images/loop.ts`, `src/images/plan.ts`, `src/images/fulfill.ts`, `src/images/xai-client.ts`, `src/images/xai-video-client.ts`, `src/images/artifacts.ts` | A provider-returned image URL is downloaded into a local artifact once, then served locally; warnings stay URL-free because provider CDN URLs may embed credentials. |
-| GitHub Copilot | `src/providers/xai-transport.ts` (`resolveProviderTransport`), `src/providers/github-copilot-transport.ts` | `resolveProviderTransport` selects the Copilot transport when the routed provider name is `github-copilot`; the Copilot module then resolves its headers and base URL, and the registry seeds the provider row and model fallback. |
-| API-key pools | `src/providers/api-key-selection.ts`, `src/providers/key-failover.ts` | A 429 rotates the active key and records a cooldown; `provider.apiKey` keeps mirroring the active entry so routing stays single-key. |
-| OAuth account failover | `src/oauth/generic-account-failover.ts`, `src/oauth/anthropic-routing.ts` | Reactive pre-output 429 recovery is presence-driven with 2+ eligible accounts. Pool and `oauthAccountFailover` flags govern proactive routing, not the reactive retry: a disabled Anthropic pool recovers through quota ordering rather than its dormant strategy, and a per-provider `enabled` beats the global default in either direction. |
-| Alibaba regions | `src/providers/alibaba-region-backup.ts`, `src/providers/alibaba-region-migration.ts`, `src/providers/alibaba-region-startup.ts` | Region migration backs up before rewriting and is idempotent across restarts. |
-| Discovery and quota | `src/providers/model-discovery.ts`, `src/providers/quota.ts` | Discovery rejects a response over 4 MiB or past 2,000 raw rows before caching it. |
-
-[Decision Log]
-- 목적과 의도: Keep reactive OAuth 429 recovery available without silently enabling proactive account-routing policy the operator switched off.
-- 기존 구현 및 제약 조건: #3495 made reactive recovery presence-driven, but a disabled Anthropic pool still consulted its dormant strategy on the reactive path, and a per-provider `oauthAccountFailover.enabled: true` could no longer beat a global `false`.
-- 검토한 주요 대안: Restore the old all-or-nothing enable flag; leave the merged behavior and document the gaps; or keep the reactive/proactive split and repair the exact policy boundaries.
-- 선택한 방식: Keep presence-driven reactive recovery, apply proactive precedence only before dispatch, and use quota ordering for disabled-pool Anthropic recovery.
-- 다른 대안 대신 이 방식을 선택한 이유: This preserves the merged product decision without letting disabled proactive settings influence a retry, and it restores the published narrow-over-broad precedence in both directions.
-- 장점, 단점 및 영향: 429 recovery stays automatic for operators with multiple eligible accounts; operators who require no automatic account switch must keep one eligible account, which the GUI and public docs state explicitly.
-
-Cursor external-model continuations attach data-URL screenshots from the contiguous active
-tool-result batch through the existing image preparation and selected-context owners. The batch
-shares the 12-image active cap. Bounded source labels are emitted in active user-action text so
-root pruning cannot erase attachment provenance; the same text participates in token estimation.
-Native Composer/MCP behavior and text-only historical replay remain unchanged.
-
-## Chat streamed tool-call identity
-
-`src/adapters/openai-chat.ts` retains a call's first observed non-negative safe integer
-index as an alias when the call started by ID. Every present, non-null index must
-be a number in that range: strings (including numeric and empty strings), booleans,
-objects, arrays, negative numbers, fractions and unsafe integers terminate the stream
-before any key, alias, ID or last-call matching. `Number.MAX_SAFE_INTEGER` is accepted;
-larger integers are rejected because distinct wire literals can parse to the same number.
-The invalid-index error releases all pending call reservations without emitting
-those calls or a successful completion; invalid indexes are never treated as absent.
-Only missing and null indexes are absent-index placeholders. Repeated ID, name and
-argument string-field tolerance retains its existing rules.
-
-For valid indexes, lookup preserves direct-key precedence, then index alias, then
-ID fallback. The initial key continues to own all translator budget reservations
-and release; learning an alias creates no additional owner. Unassociated index-only
-fragments are not guessed onto pending ID-only calls.
-`tests/adapters/openai/openai-chat-parallel-stream.test.ts` covers late aliases,
-parallel/colliding identities, distinct unsafe raw JSON index literals, the maximum
-safe-integer boundary, invalid index types, missing/null continuations and UTF-8
-byte-limit boundaries.
-
-## Cursor executable tool schema ownership
-
-`src/adapters/cursor/tool-schemas.ts` owns advertised and argument-normalization
-schemas; `tool-definitions.ts` remains the public facade and protobuf encoder.
-Advertisement and normalization intentionally differ for shell bridges: Cursor may
-emit `cmd`, while the declared Responses contract decides whether it becomes
-`command`. Both paths preserve execution-control fields. Freeform tools use one
-required string `input` in a closed object, retaining that tool's string-valued
-input description from the parser (including patch-envelope guidance). Other input
-constraints cannot widen the canonical shape. Bare shell bridge names are rejected
-on the freeform path.
-Namespaced tools do not acquire bare-shell behavior. Regression coverage lives in
-`tests/providers/cursor/cursor-tool-definitions.test.ts`.
-
-## Sidecars
-
-Web search and vision sidecars run only when the main request needs that capability and a usable
-sidecar authority exists. Vision has two possible backends; web search's config union additionally
-admits `xai`, `gemini`, and `exa`. xAI is a live explicit-only backend through stored Grok OAuth;
-Gemini and Exa remain inert until their executors ship. Selection differs per sidecar:
-
-| Sidecar | Backend selection | Default model | Activation |
-| --- | --- | --- | --- |
-| `web-search/` | Explicit configuration only: unset always resolves to the OpenAI forward path. No backend — Anthropic or otherwise — is auto-selected from credential availability (doing so once sent OpenAI model ids to the Anthropic API). Explicit xAI requires usable stored Grok OAuth and may add hosted `x_search`; explicit Gemini/Exa remain fail-closed until their executors land. | `gpt-5.6-luna` (OpenAI), `claude-sonnet-5` (Anthropic), `grok-4.6` (xAI) | Hosted `web_search` requested by a non-passthrough routed model. |
-| `vision/` | Explicit configuration wins for both backends. Only an unset backend auto-selects: Anthropic when a usable Anthropic OAuth provider exists, otherwise the OpenAI forward authority. An explicitly selected backend whose authority is unavailable produces no plan rather than falling back. | `claude-sonnet-5` (Anthropic), `gpt-5.4-mini` (OpenAI) | Input contains images for a model listed in `noVisionModels`. |
-
-The asymmetry is in the unset case only: vision may describe an image with whichever model can see
-it, while a hosted search tool is tied to a provider-specific tool contract, so search never infers
-Anthropic from credentials alone.
-
-On the OpenAI path there is one deterministic `openai` sidecar candidate and its current account mode
-owns credential selection; API-key OpenAI is not a ChatGPT forward sidecar candidate.
-
-Sidecar failures must degrade to text markers or skipped capability, not abort the main request.
-
-### Grok snapshot module ownership
-
-The client-specific tracker lives in `grok-responses-snapshot-repair.ts`; the
-provider-opt-in tracker remains in `responses-snapshot-repair.ts`. Their unchanged
-object guard, JSON block encoder and retained-item shape live in the dependency-
-free `responses-snapshot-codec.ts`. Core imports each tracker directly. No existing
-snapshot export moves, and neither tracker imports the core dispatcher. The Grok
-marker selects compatibility behavior and conveys no authenticated client identity.
-
-Manual and automatic OAuth/API-key selection commit through their shared selection owners before
-dispatch. Selection revisions fence stale retries and reselection; request identity includes the
-actual committed account/key. Generic proactive selection is opt-in and preserves a healthy active
-account, while reactive429 recovery remains enabled even with the pool off. Post-commit selection
-events immediately invalidate dashboard roster state; see`05_gui-and-management-api.md`.
-
-
-### Incomplete quota terminals
-
-A native forward response that ends with quota or rate-limit evidence in an
-`incomplete` terminal records account quota failure and spawn-fallback health.
-Structured `incomplete_details.reason` and error codes are accepted without a
-message; ordinary output-limit, filtering, steering and stall incompletes do not
-cool an account. Cyber-policy classification retains precedence. The terminal is
-not replayed after output, and fixed-account request selection remains fixed.
-
-Remote compact requests release the server request-idle timeout only after a complete
-JSON object with a valid model has been read. Partial or invalid uploads retain
-the listener guard; admitted compaction then uses the upstream operation's own
-deadlines and client cancellation.
-
-Buffered routed compaction treats nonempty text and reasoning deltas as progress
-without exposing partial summary text. Comments, empty deltas and gateway
-keepalives do not reset the adapter-event stall watchdog. The default stall
-timeout stays 300 seconds; encrypted compaction content is preserved unchanged.
-
-Native compact response buffering also enforces a body-byte inactivity deadline
-using `stallTimeoutSec` (300 seconds by default). Nonempty chunks reset that
-deadline; a stalled body returns HTTP 504, client cancellation retains HTTP 499,
-and cleanup does not wait for a stuck upstream cancellation promise. The 32 MiB
-response ceiling and the original body bytes are preserved.
-
-A canonical upstream WebSocket refused-create error can become an HTTP 4xx only
-before the response is committed and after stream correlation checks. Permitted
-quota headers are bounded and rebuilt without upstream framing headers; the JSON
-response is not cacheable. Post-commit and 5xx errors keep the no-resend path.
-
-When encrypted agent-task recovery refuses a routed task, its existing 400 error
-can include a bounded `recovery_reason`: `unsupported_envelope`,
-`admission_denied`, `recovery_unavailable`, `caller_cancelled`, `input_changed`,
-`recovery_http_rejected`, `recovery_timeout`, `recovery_aborted`,
-`recovery_transport_error`, or `recovery_invalid_output`.
-HTTP rejection requires an observed non-success response. Invalid output includes
-invalid UTF-8, oversized bodies, malformed or incomplete recovery streams, and
-invalid or conflicting assignments. A caller's cancellation takes precedence over
-an owned deadline, which takes precedence over decode/transport failures.
-`recovery_aborted` describes a shared recovery cancelled independently of that caller.
-Shared-flight waiters receive the same underlying failure unless individually cancelled;
-only successful plaintext is cached. Diagnostics contain no upstream error or payload text.
-The field is omitted when no classified recovery result exists, and existing combo
-branches that return the original target failure keep that response.
-`recovery_unavailable` includes cache/singleflight capacity and does not prove an
-upstream request was attempted. No retry or broader envelope acceptance is enabled.
-
-## Voice diagnostic metadata
-
-`src/server/live.ts` owns optional `OCX_LIVE_FRAME_LOG` diagnostics for both sideband directions.
-The JSONL schema contains only `ts`, `dir`, `kind`, `bytes`, and `fffd`. It never stores frame
-content or transcript excerpts, and logging failures do not affect transparent frame delivery.
-Binary detection decodes only the supplied buffer view; malformed UTF-8 can itself produce U+FFFD,
-so the flag does not identify the peer responsible for corruption. Existing diagnostic files are
-not rewritten. Audio devices, WebRTC media negotiation, captions and spoken handoff delivery remain
-client responsibilities.
diff --git a/structure/AGENTS.md b/structure/AGENTS.md
new file mode 100644
index 0000000000..bcab24189b
--- /dev/null
+++ b/structure/AGENTS.md
@@ -0,0 +1,150 @@
+# Rules for `structure/`
+
+This file applies to `structure/` and inherits the repository-wide rules in [`AGENTS.md`](../AGENTS.md).
+[`INDEX.md`](INDEX.md) is the reading order and the source-to-doc map; it is generated from
+[`manifest.json`](manifest.json), so it is never the file you edit to record something.
+
+## What belongs here
+
+A doc in this folder states **the contract that holds right now**, in the present tense, for one
+subsystem. That is the whole job.
+
+- Public user workflows belong in `docs-site/`.
+- Open work, triage, and investigation belong in `devlog/`.
+- Superseded or alternative reasoning belongs in `decisions/`, not in the doc body.
+- Unreleased security findings belong in scratch space and nowhere in this repository. The rule in
+  the root [`AGENTS.md`](../AGENTS.md) binds this folder without exception.
+
+If you cannot write a sentence in the present tense about how the system behaves today, it is not a
+structure doc.
+
+## Layout rules
+
+- File names are kebab-case, start with a letter, and sit at most one directory deep:
+  `providers/google.md`, not `providers/google/wire.md`, and not `04_transports.md` or `04-transports.md`.
+- **Ordering lives in `manifest.json`, never in a filename.** Leading digits are rejected outright.
+  The old `NN_topic.md` scheme produced two `09_` files and made splitting a doc cost a renumber, which
+  is how `04_transports-and-sidecars.md` reached 1,860 lines before this folder was reorganised.
+- A doc stays under the line budget in `manifest.json`. Over budget, split it along a topic boundary
+  and give each half its own manifest entry. A `grace.oversizeDocs` entry is for a split already
+  planned; the gate drops it again once the doc is back under budget.
+- **Stage a new file before running the gate.** Repository paths are resolved through the git index,
+  so a file you have written but not `git add`ed does not exist as far as the check is concerned. That
+  is deliberate: CI runs on a clean checkout, and a gate that passed on untracked local files would
+  disagree with it.
+- Know what the budget does and does not do: it is a line count, so a doc written as a wide table can
+  carry far more prose per line than one written as paragraphs. It bounds the runaway-file failure,
+  not density.
+
+## The source-to-doc map
+
+Each doc lists the source areas it describes, in its `documents` array. [`INDEX.md`](INDEX.md) publishes
+the inverse.
+
+- **An area can be described by more than one doc, and usually is.** These docs are organised by
+  topic; `src/` is organised by module. `src/server/` is genuinely described by the management-API doc,
+  the Responses transport doc and the Images doc. An earlier revision of this folder demanded exactly
+  one owner per area, and that rule was simply false here — a false rule is worse than none, because
+  the gate reports green while the map sends a maintainer to the wrong doc.
+- **Changing an area obliges the same change to update every doc listed for it.** Not a follow-up,
+  not a later cleanup pass.
+- Describing an area means naming a path inside it. If a doc explains a subsystem without ever citing
+  a path, the map cannot see it, and the area lands in `grace.undocumentedSourceAreas` instead — which
+  is a signal to add the path reference, not a place to park work.
+  The gate checks the weak form of this: a `documents` entry is rejected when the doc never names the
+  area or any path under it. Naming the directory itself passes, which a table of directory names
+  does, so the check catches an invented claim but does not prove the doc says anything useful about
+  the area. That part is review.
+- A new `src/<area>/` or top-level `src/*.ts` either joins a doc's `documents` list or is recorded in
+  `grace.undocumentedSourceAreas` with a reason. The gate rejects one that is neither.
+
+What the map still does not do: it cannot tell you that two docs describe the same behavior in
+contradictory words. Avoiding that is a review judgement. Prefer one statement and a link over two
+statements that will drift apart.
+
+## Decision records
+
+`decisions/ADR-NNNN-<slug>.md` holds the reasoning: intent, prior constraints, alternatives, the
+choice, why, and consequences.
+
+- One record has exactly one owning doc, which links it with a `> Decision record:` line.
+- Numbers are permanent and unique. They are deliberately **not** required to be contiguous: two
+  branches that each add a record would otherwise both take the next number and collide on merge.
+- Records are historical. When the contract changes, edit the doc body and add a new record; do not
+  rewrite an old one to match. For the same reason the gate does not validate the repository paths a
+  record names — a record describes a past tree, and holding it against the present one would force
+  you to falsify it.
+- A record's title names the doc section it was recorded under, not the decision it contains. That is
+  why every title reads `decision recorded under "<section>"`: the records extracted during the
+  2026-09-11 reorganisation took their heading from the section they sat in, and a title that looked
+  like a decision name but was not would send a maintainer to the wrong record. Read the body.
+- Ownership is the `> Decision record:` link, and nothing else. A record path mentioned in prose or
+  shown inside a fenced example is not a claim, so an illustration cannot make a doc a second owner.
+  The link has to land inside `decisions/`; pointing it elsewhere is rejected rather than matched on
+  the filename.
+
+## Invariants
+
+[`overview.md`](overview.md) is the invariant index. Each entry needs a stable `INV-<AREA>-NN` id, and a
+bound entry adds an `Enforced by` line naming exactly one `tests/**.test.ts` path, with that id repeated
+in a comment inside the test.
+
+Be precise about the strength of that binding, because it is easy to overstate:
+
+- It proves the test file exists and claims the id. Deleting or renaming the file fails the gate.
+- It does **not** prove the assertions inside still cover the rule. Moving the assertions to another
+  file while leaving the comment behind passes. Only review catches that.
+
+An invariant with no honest test goes in the index **without** an `Enforced by` line and with an entry
+in `grace.unboundInvariants` explaining why. Naming a test that would pass while the rule was
+violated is worse than admitting the gap: it converts an open question into false assurance.
+
+## Adding or changing a doc
+
+1. Write or move the file.
+2. Add or update its `manifest.json` entry: `path`, `tier`, `title`, `scope`, `documents`.
+3. `bun run structure:index` to regenerate [`INDEX.md`](INDEX.md).
+4. `bun run structure:check` until it is green.
+
+## What the gate checks
+
+`bun run structure:check` — also run by `tests/ci-workflows/structure-ssot.test.ts`, so it blocks CI —
+verifies that:
+
+- every doc on disk is in the manifest and every manifest doc exists, exactly once;
+- file names are kebab-case, letter-initial, and at most one directory deep;
+- no doc exceeds the line budget, and no grace entry outlives the split it promised;
+- every relative link resolves, including its `#anchor`;
+- a fragment-only link resolves against its own document, which is where one broken anchor was hiding;
+- every backticked repository path a doc names is real, checked against the **git index** rather than
+  the filesystem — `existsSync` cannot tell a tracked file from untracked local leftovers, and it is
+  case-insensitive on Windows and case-sensitive on Linux CI, which would make the gate mean
+  something different on each machine;
+- no doc body carries either inline decision-log marker: the bracketed Decision-Log heading that the
+  old layout used, or the Korean bullet template that followed it. Reasoning written as ordinary
+  prose is not detectable and stays a review judgement. The check is a literal match, which is why
+  this line describes the marker instead of quoting it;
+- every decision record is linked from exactly one doc, and no number is reused;
+- every bound invariant names an existing test that names the id back, and every unbound one is
+  recorded with a reason;
+- every `src/` directory and top-level module is described by a doc or recorded as undescribed;
+- the manifest itself parses and has the shape the gate expects, reported as a failure rather than a
+  stack trace;
+- `overview.md` exists, because its absence would otherwise silence every invariant check at once;
+- `INDEX.md` matches what the manifest generates, compared after newline normalisation so a CRLF
+  checkout is not a failure.
+
+Checks are scanned with fenced code blocks removed, so an example inside a fence does not trip a rule
+it is only illustrating.
+
+One boundary worth stating, because it looks like a gap and is a deliberate one: a backticked token is
+treated as a repository path only when its first segment is a top-level entry this repository has or
+used to have. That covers root files too, so `package.json` and `MAINTAINERS.md` are checked directly,
+not only through the links that point at them. What is NOT checked is a bare filename that was never
+a top-level entry, because these docs name runtime files that live in a user's home rather than in
+the repository — `config.toml`, `models_cache.json`, `ocx.pid` — and validating every filename-shaped
+token would reject them.
+
+The top-level set deliberately includes roots that no longer exist, such as `go/`. Deriving it from
+the current tree alone would make every reference to a deleted directory invisible at exactly the
+moment those references go stale.
diff --git a/structure/INDEX.md b/structure/INDEX.md
new file mode 100644
index 0000000000..cb8b9250e5
--- /dev/null
+++ b/structure/INDEX.md
@@ -0,0 +1,149 @@
+# opencodex Structure Index
+
+This folder is the maintainer source of truth for the current system shape. Public user workflows
+belong in `docs-site/`. Development work is recorded in `devlog/` units — `_plan/` while open,
+`_fin/` once closed — while `docs/` keeps investigations and diagnostic notes worth retaining for
+archaeology, debugging, or source research.
+
+Generated from `structure/manifest.json` by `bun run structure:index`. Do not edit by hand; `bun run structure:check` fails when this file and the manifest disagree. The rules for changing anything
+in this folder are in [`AGENTS.md`](AGENTS.md).
+
+## Reading order
+
+### Tier 1 — Foundation
+
+What opencodex is, what it owns on disk, and the invariants nothing may break.
+
+| Doc | Scope |
+| --- | --- |
+| [`overview.md`](overview.md) | Product boundary, local state ownership, and the non-negotiable invariants index. |
+| [`runtime.md`](runtime.md) | Entrypoints, process lifecycle, CLI surface, and provider/adapter selection. |
+
+### Tier 2 — Configuration and catalog
+
+Persisted config, the Codex home it writes into, and the model catalog it publishes.
+
+| Doc | Scope |
+| --- | --- |
+| [`config.md`](config.md) | Persisted config schema, both injection forms, provider validation, and restore. |
+| [`codex-home.md`](codex-home.md) | CODEX_HOME resolution, the files opencodex manages there, and Codex-home diagnostics. |
+| [`catalog.md`](catalog.md) | Shared Codex catalog assembly, account namespaces, pool rotation, and effort ladders. |
+| [`subagents.md`](subagents.md) | Multi-agent surface mode and subagent roster ordering. |
+
+### Tier 3 — Data planes and transports
+
+The wire surfaces a client actually talks to.
+
+| Doc | Scope |
+| --- | --- |
+| [`transports/responses.md`](transports/responses.md) | The Responses HTTP/SSE data plane, combo failover, and streaming commit boundaries. |
+| [`transports/streaming-health.md`](transports/streaming-health.md) | Heartbeat and stall deadlines, plus the opt-in WebSocket transport. |
+| [`transports/inventory.md`](transports/inventory.md) | The per-provider transport table and diagnostic outbound safety. |
+| [`data-planes/images.md`](data-planes/images.md) | Standalone image generation and edit relay. |
+| [`data-planes/search.md`](data-planes/search.md) | Hosted search relay and exact account selectors. |
+| [`data-planes/inbound-compat.md`](data-planes/inbound-compat.md) | Chat Completions inbound, Anthropic-shaped clients, and JSON-upstream streaming clients. |
+| [`remote-workspace.md`](remote-workspace.md) | Inactive workspace protocol, cryptographic identity primitives, and bounded framing. |
+
+### Tier 4 — Providers and adapters
+
+Per-vendor contracts and the adapter authority that constructs them.
+
+| Doc | Scope |
+| --- | --- |
+| [`providers/openai-tiers.md`](providers/openai-tiers.md) | Pool/Direct account modes, API-key separation, wire identity, and quota evidence. |
+| [`providers/cursor.md`](providers/cursor.md) | Cursor native exec, parameterized models, checkpoints, and active-context usage. |
+| [`providers/google.md`](providers/google.md) | Gemini thought-text, response parts, thought-signature replay, and adjacency repair. |
+| [`providers/kiro.md`](providers/kiro.md) | Kiro parallel-tool hints, Responses text controls, and reasoning round-trip. |
+| [`providers/xai-grok.md`](providers/xai-grok.md) | Grok Build contract parity and hardening. |
+| [`providers/chat-compat.md`](providers/chat-compat.md) | Cross-vendor Chat Completions behavior: reasoning, tool results, structured output, parallel tools. |
+| [`adapters/registry.md`](adapters/registry.md) | The single adapter construction authority and contract inheritance. |
+| [`adapters/compatibility-contracts.md`](adapters/compatibility-contracts.md) | Versioned provider compatibility claims and fixture-evidence boundaries. |
+| [`adapters/compatibility-lab.md`](adapters/compatibility-lab.md) | Optional Lab evidence, automation, and its core-runtime isolation boundary. |
+
+### Tier 5 — Surfaces and clients
+
+The dashboard, the management API, and third-party client config ownership.
+
+| Doc | Scope |
+| --- | --- |
+| [`gui-and-management-api.md`](gui-and-management-api.md) | Dashboard serving, authentication boundaries, /api/* ownership, and usage accounting. |
+| [`clients/integrations.md`](clients/integrations.md) | Third-party client config ownership, snapshots, refresh, disable, and restore. |
+| [`clients/claude-desktop.md`](clients/claude-desktop.md) | Claude Desktop profile ownership and config-library resolution. |
+
+### Tier 6 — Operations and process
+
+Background service, docs, release, and design discipline.
+
+| Doc | Scope |
+| --- | --- |
+| [`ops/service-and-sidecars.md`](ops/service-and-sidecars.md) | Service install/repair, platform launchers, tray, and sidecar processes. |
+| [`ops/docs-and-release.md`](ops/docs-and-release.md) | Docs site, workflow map, branch policy, release flow, and cross-platform CI. |
+| [`design-methodology.md`](design-methodology.md) | Stage ordering for new GUI, CLI, and user-facing surfaces. |
+
+## Which doc describes which source
+
+A source area can be described by more than one doc, because these docs are organised by topic and
+`src/` is organised by module. Changing an area obliges the same change to update every doc listed
+for it; see [`AGENTS.md`](AGENTS.md).
+
+| Source path | Described by |
+| --- | --- |
+| `.github/` | [`ops/docs-and-release.md`](ops/docs-and-release.md) |
+| `bin/` | [`runtime.md`](runtime.md)<br>[`ops/docs-and-release.md`](ops/docs-and-release.md) |
+| `docs-site/` | [`ops/docs-and-release.md`](ops/docs-and-release.md) |
+| `gui/` | [`overview.md`](overview.md)<br>[`gui-and-management-api.md`](gui-and-management-api.md)<br>[`design-methodology.md`](design-methodology.md) |
+| `scripts/` | [`overview.md`](overview.md)<br>[`ops/docs-and-release.md`](ops/docs-and-release.md) |
+| `src/adapters/` | [`runtime.md`](runtime.md)<br>[`transports/responses.md`](transports/responses.md)<br>[`transports/inventory.md`](transports/inventory.md)<br>[`data-planes/inbound-compat.md`](data-planes/inbound-compat.md)<br>[`providers/cursor.md`](providers/cursor.md)<br>[`providers/chat-compat.md`](providers/chat-compat.md)<br>[`adapters/registry.md`](adapters/registry.md) |
+| `src/chat/` | [`runtime.md`](runtime.md)<br>[`transports/inventory.md`](transports/inventory.md)<br>[`data-planes/inbound-compat.md`](data-planes/inbound-compat.md) |
+| `src/claude/` | [`runtime.md`](runtime.md)<br>[`clients/claude-desktop.md`](clients/claude-desktop.md) |
+| `src/cli.ts` | [`runtime.md`](runtime.md)<br>[`ops/docs-and-release.md`](ops/docs-and-release.md) |
+| `src/cli/` | [`runtime.md`](runtime.md)<br>[`config.md`](config.md)<br>[`clients/claude-desktop.md`](clients/claude-desktop.md)<br>[`ops/docs-and-release.md`](ops/docs-and-release.md) |
+| `src/client/` | [`runtime.md`](runtime.md)<br>[`clients/claude-desktop.md`](clients/claude-desktop.md) |
+| `src/clients/` | [`clients/integrations.md`](clients/integrations.md) |
+| `src/codex/` | [`runtime.md`](runtime.md)<br>[`config.md`](config.md)<br>[`codex-home.md`](codex-home.md)<br>[`catalog.md`](catalog.md)<br>[`subagents.md`](subagents.md)<br>[`providers/openai-tiers.md`](providers/openai-tiers.md)<br>[`gui-and-management-api.md`](gui-and-management-api.md)<br>[`ops/docs-and-release.md`](ops/docs-and-release.md) |
+| `src/combos/` | [`runtime.md`](runtime.md) |
+| `src/compatibility/` | [`runtime.md`](runtime.md)<br>[`adapters/compatibility-contracts.md`](adapters/compatibility-contracts.md) |
+| `src/config.ts` | [`overview.md`](overview.md)<br>[`runtime.md`](runtime.md)<br>[`config.md`](config.md)<br>[`providers/openai-tiers.md`](providers/openai-tiers.md) |
+| `src/config/` | [`runtime.md`](runtime.md)<br>[`config.md`](config.md) |
+| `src/generated/` | [`runtime.md`](runtime.md) |
+| `src/github/` | [`runtime.md`](runtime.md) |
+| `src/grok/` | [`runtime.md`](runtime.md) |
+| `src/images/` | [`runtime.md`](runtime.md)<br>[`transports/inventory.md`](transports/inventory.md) |
+| `src/index.ts` | [`runtime.md`](runtime.md) |
+| `src/integrations/` | [`clients/integrations.md`](clients/integrations.md) |
+| `src/lab/` | [`runtime.md`](runtime.md)<br>[`adapters/compatibility-lab.md`](adapters/compatibility-lab.md) |
+| `src/lib/` | [`overview.md`](overview.md)<br>[`runtime.md`](runtime.md)<br>[`transports/responses.md`](transports/responses.md)<br>[`transports/inventory.md`](transports/inventory.md)<br>[`gui-and-management-api.md`](gui-and-management-api.md)<br>[`clients/integrations.md`](clients/integrations.md)<br>[`ops/docs-and-release.md`](ops/docs-and-release.md) |
+| `src/oauth/` | [`runtime.md`](runtime.md)<br>[`transports/inventory.md`](transports/inventory.md)<br>[`providers/xai-grok.md`](providers/xai-grok.md) |
+| `src/providers/` | [`runtime.md`](runtime.md)<br>[`subagents.md`](subagents.md)<br>[`transports/inventory.md`](transports/inventory.md)<br>[`providers/xai-grok.md`](providers/xai-grok.md) |
+| `src/reasoning-effort.ts` | [`runtime.md`](runtime.md) |
+| `src/remote-control/` | [`remote-workspace.md`](remote-workspace.md) |
+| `src/remote/` | [`runtime.md`](runtime.md) |
+| `src/responses/` | [`runtime.md`](runtime.md)<br>[`transports/responses.md`](transports/responses.md)<br>[`providers/kiro.md`](providers/kiro.md)<br>[`providers/xai-grok.md`](providers/xai-grok.md)<br>[`providers/chat-compat.md`](providers/chat-compat.md) |
+| `src/router.ts` | [`runtime.md`](runtime.md) |
+| `src/routing/` | [`catalog.md`](catalog.md) |
+| `src/server/` | [`runtime.md`](runtime.md)<br>[`catalog.md`](catalog.md)<br>[`subagents.md`](subagents.md)<br>[`transports/responses.md`](transports/responses.md)<br>[`transports/streaming-health.md`](transports/streaming-health.md)<br>[`transports/inventory.md`](transports/inventory.md)<br>[`data-planes/images.md`](data-planes/images.md)<br>[`data-planes/inbound-compat.md`](data-planes/inbound-compat.md)<br>[`providers/xai-grok.md`](providers/xai-grok.md)<br>[`adapters/registry.md`](adapters/registry.md)<br>[`gui-and-management-api.md`](gui-and-management-api.md)<br>[`clients/claude-desktop.md`](clients/claude-desktop.md)<br>[`ops/service-and-sidecars.md`](ops/service-and-sidecars.md) |
+| `src/service.ts` | [`runtime.md`](runtime.md)<br>[`ops/docs-and-release.md`](ops/docs-and-release.md) |
+| `src/stall-timeout.ts` | [`runtime.md`](runtime.md) |
+| `src/storage/` | [`runtime.md`](runtime.md) |
+| `src/tray/` | [`runtime.md`](runtime.md) |
+| `src/types.ts` | [`runtime.md`](runtime.md)<br>[`config.md`](config.md) |
+| `src/update/` | [`runtime.md`](runtime.md) |
+| `src/usage/` | [`runtime.md`](runtime.md)<br>[`gui-and-management-api.md`](gui-and-management-api.md) |
+| `src/vision/` | [`runtime.md`](runtime.md)<br>[`gui-and-management-api.md`](gui-and-management-api.md) |
+| `src/web-search/` | [`runtime.md`](runtime.md) |
+
+### Not described by any doc
+
+| Source path | Why |
+| --- | --- |
+| `src/bridge.ts` | no doc names this file; it is the legacy adapter bridge entry and its behavior is described under the adapter registry without a path reference |
+| `src/quota/` | no doc names a path here; quota evidence is described in providers/openai-tiers.md in prose only |
+| `src/service-manager-probe.ts` | no doc names this file; service probing is described in ops/service-and-sidecars.md without a path reference |
+| `src/sidecar/` | no doc names a path here; ops/service-and-sidecars.md describes sidecar behavior in prose only |
+| `src/types/` | shared declarations plus the tool-name and wire-pin resolvers, which no doc currently describes |
+
+## Decision records
+
+Superseded reasoning lives in `decisions/` as numbered records. A doc states the contract that holds now and
+links the record that explains why; it never carries the reasoning inline.
+
diff --git a/structure/11_compatibility-contracts.md b/structure/adapters/compatibility-contracts.md
similarity index 62%
rename from structure/11_compatibility-contracts.md
rename to structure/adapters/compatibility-contracts.md
index c503cc0991..ef60067797 100644
--- a/structure/11_compatibility-contracts.md
+++ b/structure/adapters/compatibility-contracts.md
@@ -1,4 +1,4 @@
-# Compatibility Contracts SOT
+# Compatibility Contracts
 
 ## Purpose
 
@@ -52,21 +52,9 @@ This is destination-scoped compatibility behavior. Key-auth public Responses pro
 forward gateways keep both extensions unchanged because their contracts may accept or interpret
 them independently.
 
-[Decision Log]
-- 목적과 의도: Preserve Posit Assistant tool continuation semantics while preventing canonical ChatGPT Codex forwarding from sending client-only cache markers or unresolvable stored-item references.
-- 기존 구현 및 제약 조건: The existing `store: false` sanitizer removed item ids but left `item_reference` shells, and no bounded pass recognized markers nested inside content; tool `call_id` pairing and reasoning effort are continuation-critical.
-- 검토한 주요 대안: Strip the extensions for every Responses destination; delete only reference ids; expand references from local state; or normalize only the canonical forward destination with bounded recursive marker removal.
-- 선택한 방식: Apply the bounded marker pass only to canonical forward `input`, and omit `item_reference` rows only when `store` is exactly `false`.
-- 다른 대안 대신 이 방식을 선택한 이유: Public and custom gateways may implement these extensions, while id-only deletion creates an invalid reference shell and local expansion would invent unavailable persistence authority.
-- 장점, 단점 및 영향: Posit continuations retain tool pairing and reasoning controls without widening public-provider behavior; hostile nesting fails closed to the original input, so an over-limit request may still be rejected upstream rather than partially rewritten.
-
-[Decision Log]
-- 목적과 의도: Make provider compatibility explicit and machine-readable before larger routing or Responses refactors.
-- 기존 구현 및 제약 조건: Adapter-wide conformance tests already protect tool translation, and Compatibility Lab owns broader protocol evidence, but neither publishes an exact provider/destination/auth/model claim table. Lab must remain outside the ordinary request import graph.
-- 검토한 주요 대안: Infer capabilities directly from registry flags; publish prose only; add a broad all-provider matrix immediately; introduce the schema with one exact fixture-backed subject.
-- 선택한 방식: Add a passive versioned schema and one exact `openai`/canonical Codex URL/forward/`gpt-5.6-sol` manifest whose claims reference assertion-level fixtures executed against the production adapter.
-- 다른 대안 대신 이 방식을 선택한 이유: Registry flags do not capture transformations such as local continuation expansion or orphan-output degradation. A broad first matrix would turn unverified assumptions into public promises.
-- 장점, 단점 및 영향: The first contract is small but trustworthy and can feed future CLI/GUI surfaces. Coverage expands only as fixtures are added; no request behavior changes in this slice.
+> Decision record: [ADR-0094](../decisions/ADR-0094-canonical-forward-continuation-extensions.md)
+
+> Decision record: [ADR-0095](../decisions/ADR-0095-canonical-forward-continuation-extensions.md)
 
 ## Routed code-mode patch completion
 
diff --git a/structure/09_compatibility-lab.md b/structure/adapters/compatibility-lab.md
similarity index 99%
rename from structure/09_compatibility-lab.md
rename to structure/adapters/compatibility-lab.md
index 6634a08e84..a1633860a0 100644
--- a/structure/09_compatibility-lab.md
+++ b/structure/adapters/compatibility-lab.md
@@ -1,4 +1,4 @@
-# Compatibility Lab SOT
+# Compatibility Lab
 
 ## CL-03 live-route execution boundary
 
diff --git a/structure/10_adapter-registry.md b/structure/adapters/registry.md
similarity index 53%
rename from structure/10_adapter-registry.md
rename to structure/adapters/registry.md
index 2c36481f54..9e869c4f7a 100644
--- a/structure/10_adapter-registry.md
+++ b/structure/adapters/registry.md
@@ -1,4 +1,4 @@
-# Adapter registry authority
+# Adapter Registry Authority
 
 ## Decision
 
@@ -13,6 +13,20 @@ Some adapters share another adapter's routed-tool semantics while retaining inde
 - `azure` and `azure-openai` inherit the `openai-responses` contract.
 - `mimo-free` inherits the `openai-chat` contract.
 - `cursor` stays direct because its `runTurn` transport and gated native-file fallback are distinct.
+- `devin-cli` stays direct for the same reason, one layer further out: it has no HTTP transport at
+  all. The turn runs as an Agent Client Protocol session against a local `devin acp` child process,
+  so `buildRequest` returns a placeholder and `parseStream` is disabled. Its registry `baseUrl` is a
+  canonical identity URL rather than a destination anything connects to, which is what keeps the
+  generated configuration loadable: `providerBaseUrlConfigError` accepts only `http(s)` schemes.
+- `devin` is the cloud half of the same family and is also direct. It streams Cognition's
+  `ApiServerService/GetChatMessage` over Connect-RPC from `runTurn` with hand-written protobuf
+  framing, so like Cursor and `devin-cli` it never travels the `buildRequest`/`parseStream` path.
+  The `devin-cli` PRESET streams over this same adapter: the installed CLI's own
+  `credentials.toml` holds an ordinary `devin-session-token`, so that provider imports the token
+  rather than spawning a child, and the two rows differ only in where the credential came from —
+  a browser sign-in versus a signed-in local CLI. The ACP adapter above remains registered and is
+  selected by a custom-named row, never by the `devin-cli` id, because `routedProviderConfig` pins
+  the adapter from the registry for any registry id.
 
 The registry records those relationships with `contractParent`. A parent relationship does **not** mean the registry recursively constructs a parent adapter and injects it into the child. Azure and MiMo keep owning their existing internal composition. This avoids making production constructors depend on test/conformance needs and keeps this authority refactor behavior-neutral.
 
@@ -41,27 +55,18 @@ Moonshot/Kimi enforce the draft-07 reading where `$ref` must stand alone and 400
 request when a node carries both. Codex's own deferred tool catalog emits exactly that shape,
 so the schema is not something a user can fix from configuration (issue #2673).
 
-[Decision Log]
-- 목적과 의도: Codex가 내보내는 `$ref` + 형제 키워드 스키마를 Moonshot이 받아들이는 형태로
-  바꾸되, 도구가 실제로 요구하는 제약을 잃지 않는다.
-- 기존 구현 및 제약 조건: JSON Schema 2020-12에서 `$ref`는 in-place applicator라 형제
-  키워드와 함께 적용된다. Moonshot은 이를 거부하므로 참조 대상을 노드 아래로 인라인해야 하고,
-  재귀 스키마는 유한해야 하며, 어댑터는 요청 경로에 있으므로 지연이 그대로 사용자에게 간다.
-- 검토한 주요 대안: (1) 형제 키워드를 버리고 순수 `$ref`만 남긴다. (2) 참조를 인라인하되
-  형제 키워드가 대상을 덮어쓴다. (3) 인라인하되 집합형 어서션은 합집합으로 합치고 나머지는
-  좁히는 쪽이 이긴다. (4) `allOf`로 감싼다.
-- 선택한 방식: (3). `required`는 합집합, `properties`는 병합, 나머지 키워드는 노드가 이긴다.
-  해석 불가능한 참조는 순수 `$ref`로 남기고, 깊이·노드·확장 예산을 각각 둔다.
-- 다른 대안 대신 이 방식을 선택한 이유: (1)은 노드가 좁힌 제약을 통째로 버린다. (2)는 대상이
-  요구하던 `a`를 형제의 `b`가 덮어써서, 양쪽 어느 쪽도 요청하지 않은 더 약한 계약을 조용히
-  내보냈다 — 리뷰가 지적한 정확한 결함이다. (4)는 Moonshot이 `allOf`를 어떻게 다루는지
-  확인된 근거가 없어 검증되지 않은 가정을 계약으로 만든다.
-- 장점, 단점 및 영향: 도구 계약이 보존된 채 Moonshot을 통과한다. 인라인은 대상을 복제하므로
-  큰 정의를 여러 노드가 참조하면 출력이 커질 수 있고, 예산이 소진되면 해당 노드는 빈 객체나
-  순수 `$ref`로 닫힌다 — 약해진 스키마를 절반만 내보내는 것보다 낫다. Moonshot 계열
-  `openai-chat` baseUrl에만 적용되고 다른 provider는 손대지 않는다.
-
-예산은 세 가지다. 확장 횟수만으로는 참조가 하나도 없는 깊은 스키마를 막지 못해서, 깊이와
-노드 수를 따로 둔다 — `google-tool-schema.ts`가 이미 쓰는 형태다. 두 가드 모두 제거했을 때
-실제로 red가 되는지 확인했고, 예산을 풀면 20k 깊이에서 `RangeError: Maximum call stack size
-exceeded`가 난다.
+> Decision record: [ADR-0093](../decisions/ADR-0093-moonshot-ref-with-siblings-normalization.md)
+
+## Truncated tool finalization
+
+The bridge keeps an open function, custom, or tool-search call incomplete when an adapter ends with a recognized truncated stop reason. Streaming emits no argument/input completion frame for that open call, and buffered JSON applies the same status. A call already closed by its own tool-call end retains its completed state. The response remains incomplete, partial output is preserved, and truncated compaction never replaces history.
+
+Chat helper admission in `src/server/responses/core.ts` follows the
+[deferred stored-main contract](../providers/openai-tiers.md): only a needed Direct OpenAI helper
+claims stored main, after terminal vision, routed vision and search exclusions.
+
+The management quota DTO keeps Combo editing aligned with scoped inference evidence;
+see [Combo editor routing quota](../gui-and-management-api.md#combo-editor-routing-quota).
+
+Claude replay carries [Go conversation affinity](../data-planes/inbound-compat.md#claude-affinity-at-final-go-dispatch)
+privately to final dispatch; preliminary route selection does not inject Go-only headers.
diff --git a/structure/catalog.md b/structure/catalog.md
new file mode 100644
index 0000000000..0ba4acca3e
--- /dev/null
+++ b/structure/catalog.md
@@ -0,0 +1,280 @@
+# Model Catalog
+
+## Shared catalog
+
+`src/codex/catalog.ts` builds a shared Codex-shaped catalog for CLI, TUI, App, and SDK. It:
+
+- preserves native OpenAI entries from the live catalog or static fallback, and emits
+  gpt-5.6 natives from the pinned upstream models.json snapshot
+  (`src/codex/data/upstream-models.json` — exact per-slug ladders: luna has no ultra);
+- upgrades either an observed selector-qualified `*/gpt-daybreak-blue-latest` account row or an
+  explicitly configured canonical `openai/gpt-daybreak-blue-latest` Codex-forward row from the
+  pinned Sol capability metadata while preserving its selector and Daybreak wire identity;
+  this never expands the bare/API-key model lists or rewrites the wire model to `gpt-5.6-sol`;
+- clones a native template for routed `provider/model` entries;
+- forces strict Codex catalog fields required by the current parser;
+- hides `disabledModels` without blocking direct routing (routed provider ids are excluded;
+  account-qualified native ids hide only that selector row; BARE native slugs hide the bare row
+  and all account-selector clones and drop that model family from raw `/v1/models`);
+- applies exact provider/model compatibility exclusions after live discovery and metadata
+  augmentation, so upstream-advertised but uncallable rows never enter dashboard or Codex pickers;
+- strips native-only service tier and WebSocket metadata unless the final routed provider/model
+  explicitly enables the verified OpenAI-compatible service tier;
+- backs up the pristine catalog once per catalog: the copy is keyed by a hash of the catalog path
+  (`catalog-backup-<id>.json`), and the legacy unsuffixed `catalog-backup.json` is retained in
+  addition for the default catalog, so a restore resolves the backup for the catalog it is restoring
+  rather than assuming a single file;
+- invalidates `$CODEX_HOME/models_cache.json` when model visibility changes.
+
+On the default `opencodex-catalog.json` path, sync deliberately uses two catalog sources: Codex's
+bundled catalog supplies a current native entry template, while the actual on-disk catalog supplies
+the rows being merged. This split is required because empty or partial provider discovery must
+preserve routed entries and genuine user-native rows from the file that will be overwritten; a
+bundled catalog never contains those rows. Retained sync and evidence-bound convergence share an
+explicit observed-state merge policy and restore native priorities from the once-only pristine
+backup rather than from a catalog whose priorities may already have been rewritten. A configured
+custom catalog remains the native metadata/template authority even when a bundled-catalog memo is
+warm. Both paths may use an admitted matching bundled memo only as installed-runtime capability
+evidence to remove unsupported reasoning efforts; convergence never probes Codex itself.
+
+Custom Astra and Daybreak rows acquire native reasoning capability only through the existing
+canonical `openai` forward destination and explicit capability-source predicate. The shared
+custom-row producer bounds their merged effort lists against pinned per-model Codex metadata,
+preserves an explicit empty list without a default, and recovers an incompatible nonempty list
+to the native default singleton. A default must belong to the projected list. Other custom rows
+keep their declaration precedence; a GPT model name, display alias, or arbitrary gateway is not
+native provenance. Stored configuration and native capability maps are unchanged.
+
+The observed-state merge tracks the current invocation's freshly generated custom row objects
+after detaching its inputs. Those rows already own their complete reasoning projection, so the
+merge does not append `max` again. This also keeps a generic none-only custom row none-only;
+ordinary retained provider rows still receive the existing mock-tier policy. A persisted custom
+marker alone never grants this exemption. Both gather entry points, retained sync, management
+convergence and direct Codex model discovery use the same producer. The legacy runtime effort
+union clamp remains separate; it is not a per-model or per-client-version grammar oracle.
+Existing thread settings and the reported Desktop 0.153.4 gateway rejection require separate
+runtime evidence. Codex's native `ultra` mode is preserved and is not a literal API wire promise.
+
+When account selectors are enabled, the sync path may also observe exact, visible, API-supported
+OpenAI-family ids from Codex's user-owned catalog/cache. Only rows with native catalog provenance
+are trusted; unknown ids are carried through startup cache invalidation as hidden observations and
+are emitted only as selector-qualified rows whose account provenance matches. They never expand
+the bare native or API-key model list. This keeps account-scoped upstream ids such as
+`gpt-daybreak-blue-latest` callable without treating them as a static release allowlist.
+
+Account-gated native ids are a stricter subset. Their authenticated ChatGPT `/models` roster is
+cached per credential generation with a bounded timeout. A bare gated row is emitted only when at
+least one confirmed eligible account reports it; a selector-qualified row is emitted only when the
+mapped account reports it. A failed or malformed discovery is not positive evidence and therefore
+hides the gated row until a later refresh. The same snapshot gates Pool selection, so the catalog
+and runtime cannot disagree by advertising through one account and dispatching through another.
+
+The app-server's model list comes from this shared catalog, not from patching the App. Codex Desktop
+may still apply its remote native-only allowlist after `model/list`; an explicitly configured combo
+`nativeAlias` is the bounded compatibility path. It replaces one supported bare native row with a
+routed, labeled row, routes the bare id before canonical OpenAI, and keeps account-qualified native
+selectors genuine. Missing target discovery capabilities inherit the replaced native row's metadata,
+while explicit target limits remain authoritative. Because the affected renderer ignores `visibility: "hide"`, the presence of any
+native alias also omits disabled bare native rows from the effective catalog. Dashboard rows remain
+derived from the static native set, and sync retains bundled/pristine native recovery sources so a
+later re-enable or alias removal restores native metadata.
+
+Provider live-model lists are cached with a configured TTL (`src/codex/model-cache.ts`). Adding,
+deleting, or editing a provider's shape clears that per-provider cache; a disabled-only change
+deliberately does not, because a disabled provider is already excluded from the catalog gather
+instead. Codex's own `models_cache.json` is a different cache, invalidated by catalog refresh.
+
+For `liveModels: false`, a static provider publishes the ordered union of `models` and
+`retainModels`. When `models` is absent or empty, its configured `defaultModel` seeds that
+union before retained ids; a nonempty explicit list does not import a different default.
+Without any default or configured/retained ids, the static result stays empty. The existing
+forward-auth native path remains separate. Static gathering does not refresh OAuth or call
+the provider's model endpoint, and normal selection and visibility filters still apply.
+
+The provider workspace uses the existing `/api/models` projection for displayed rows,
+model identity and inventory counts. Counts cover distinct non-disabled selectors within
+each provider, before search or the render cap; they are not selected-model or live-discovery
+counts. The full available list and discovery provenance remain separate inputs.
+
+Deleting a custom definition uses its stable record id and does not also hide the underlying
+model. Native or discovered metadata can therefore reappear without changing the inventory
+count. Hide uses the represented row's native/routed identity and changes visibility only.
+The Models page can restore existing hidden rows; adding a definition does not implicitly
+clear a previous hide or provider allowlist. Actions wait for current row and custom-ownership
+observations, and mutations reconcile those observations instead of retaining browser-only
+removal markers. These presentation operations do not grant routing or account entitlement.
+
+### Windows request-path catalog-state discovery
+
+> Decision record: [ADR-0021](decisions/ADR-0021-shared-catalog.md)
+
+## Startup readiness
+
+Each `startServer` invocation owns a private, one-shot readiness gate created before the listener
+binds. `handleStart` supplies its gate and transitions it only after the shared catalog sync and
+best-effort Claude Code roster reconciliation have both settled. The catalog sync remains the
+authority for ready versus failed; a roster warning does not make an otherwise healthy proxy fail.
+Calls without a supplied gate receive a fresh private gate that intentionally remains pending. Only
+`ok: true` with no nonempty warning becomes ready; `null`, a throw, `ok !== true`, or a nonempty
+warning becomes failed. State is isolated per server instance.
+
+Exact unauthenticated `GET /readyz` returns sanitized identity fields plus pending, ready, or failed:
+`200` for ready, or `503` with `Retry-After: 1` for pending and terminal failed. The full CLI syntax
+is `ocx ready [--json] [--wait [--timeout <seconds>]]`. The probe validates the service, version,
+uptime, PID, port, status, and HTTP/status pairing. The default is one probe. With `--wait`, it
+applies one absolute deadline (45 seconds by default) across discovery, readiness probes, polling,
+and sleeps, but exits immediately on terminal failed. `--timeout <seconds>` requires `--wait` and
+accepts positive integer seconds from 1–300. CLI `--json` emits
+`{ready, status, pid, port}`, with status in `ready|pending|failed|unreachable`. Exit 0 means ready;
+exit 1 covers not-ready, pending, failed, timeout, and unreachable; exit 64 means invalid arguments.
+Older proxies without `/readyz` fail closed as unreachable. `/healthz` remains the separate
+liveness contract.
+
+## Entry shape
+
+Routed entries keep Codex-required metadata such as reasoning levels, shell type, API support flags,
+base instructions, modalities, auto-compact fields, and strict parser booleans. The public slug uses
+the canonical `provider/model`. Its display name uses the provider's exact `modelDisplayNames` override first,
+then trusted catalog metadata such as a configured qualified provider/model alias, then the public slug.
+This overlay never changes route identity or the upstream wire model, and its catalog fingerprint makes
+a label edit refresh Codex output.
+
+Supported bare native GPT rows also consume `providers.openai.modelDisplayNames`. Retained sync
+and convergence pass the same map to the observed-state merge. After native normalization and
+ordering, the merge applies the exact nonblank trimmed label and saves
+`opencodex_native_display_name: { slug, original, applied }` in the local catalog only. The next
+merge detaches its inputs, removes that marker, and restores `original` only if the native slug
+still matches and the current name equals `applied`. Removing or blanking the override therefore
+restores the owned name before normal native metadata upgrades. Divergent external names remain
+subject to those upgrades: Astra still replaces non-pinned names with its pinned native name.
+Template-derived rows discard the marker. The overlay leaves model IDs, metadata (including
+capabilities), ordering, routed combo aliases, custom rows and account-qualified rows unchanged;
+it does not relabel HTTP model listings or virtual `*-pro` rows.
+
+## Native passthrough
+
+Astra has its own pinned native row: 272,000 default context, 872,000 opt-in ceiling,
+low-through-ultra effort, low default, and native multi-agent effort `xhigh`. The native-alias
+fallback passes the same configured limits to context, max input and compaction. Unrelated routed
+templates clear the native multi-agent effort; canonical Astra-forward custom rows retain it and
+the pinned Fast speed description. Sync repairs only the exact old built-in Astra Fast description,
+preserving custom descriptions and other stored row fields.
+
+The API registry separately owns Astra's 1,050,000 context / 922,000 input / 128,000 output and
+five API effort levels. Trusted discovery snapshots carry the output ceiling as well as input
+and context, so reconstruction cannot drop it. User output limits may only lower that ceiling.
+Pricing remains provider-scoped and API-referenced for every built-in dollar estimate, including
+Codex-login routes. Both OpenAI identities use the same Astra/Sol API base and cache prices,
+API Fast multipliers and published long-context bands; Fast stacks with long context for Astra,
+GPT-5.6 and the Daybreak Blue selectors. No subscription-specific exception or credit multiplier
+enters the estimate. Explicit user price overrides remain authoritative. See the public provider
+reference for the dated source table.
+
+Native bare OpenAI entries form one `openai` group. The provider's Pool(default)/Direct option
+changes account selection without changing those ids; `openai-apikey/<model>` creates the separate
+API-key identity. The API GPT-5.6 rows use 1,050,000 context / 922,000 max input; their `*-pro` virtual rows
+rewrite to the base upstream model with `reasoning.mode: "pro"` while public state keeps the virtual
+slug. Routed non-OpenAI models must not
+inherit native-only service tier or WebSocket metadata unless the user explicitly enables that
+capability. Detailed invariants live in [`openai-tiers.md`](providers/openai-tiers.md).
+
+Native passthrough entries depend on the enabled provider set. With at least one enabled provider,
+they appear only while an enabled canonical OpenAI forward provider exists — disabling every such
+provider removes the native rows rather than leaving entries that resolve to no credential. With no
+enabled provider at all, the native rows remain as bootstrap so a fresh install still has something
+to route.
+
+## Accounts, namespaces, and pool rotation
+
+Pool mode routes across main plus added Codex credentials. Key rules:
+
+- **A namespace is a public selector mapped to an internal target.** Generated selectors are how a
+  caller names an account — the main login's selector is `main` (collision-suffixed if taken),
+  which maps to the config-only sentinel `@main`; the sentinel deliberately sits outside the
+  pool-account id grammar. Selector initialization requires an explicit opt-in and fills only an
+  absent or empty map; a non-empty user map keeps its object identity and insertion order. Generated
+  selectors avoid provider, combo, routing-policy, and slash-qualified routing-profile namespaces.
+  Collision checks normalize provider and reserved namespace keys, while account and
+  routing-profile selector prefixes are exact-case (`src/codex/account-namespaces.ts`,
+  `src/codex/account-namespace-match.ts`, `src/routing/profile-namespace.ts`).
+- **Selector labels carry no account-role semantics.** When at least one selector is advertisable,
+  the Codex catalog clones each supported native row per selector and hides the bare picker rows;
+  bare ids remain routable and stay in raw `/v1/models` unless explicitly disabled. Missing stored
+  account targets are not advertised, and private account ids never become catalog labels.
+  `codexAccountPickerEnabled: false` hides generated rows without deleting exact routing bindings;
+  an omitted flag preserves the established behavior of a nonempty hand-written selector map.
+- **Rotation is sticky.** A conversation stays on its selected account while that account is
+  usable; failure moves it, success does not (`src/codex/pool-rotation.ts`).
+- **The credential store is generation-guarded.** A refresh takes a lock and persists only if the
+  generation it started from still holds; a lost race raises a generation-conflict error rather
+  than overwriting the newer credential (`src/codex/account-store.ts`). Callers handle that error;
+  they do not assume a silent retry.
+
+Warmup issues a bounded request with a fallback model so a cold account reports usability before a
+real turn depends on it (`src/codex/warmup.ts`).
+
+## Routed tool discovery and hosted search
+
+All routed catalog rows advertise `supports_search_tool: true` together with
+`tool_mode: "code_mode_only"` — the pair is load-bearing. The field selects Codex's deferred
+tool-discovery surface; it does not describe the hosted web-search sidecar. Under code mode,
+deferred MCP tools remain callable through exec's `tools` global / `ALL_TOOLS` without a
+`tool_search` round-trip (upstream codex-rs code_mode suite; live canary 2026-08-13: routed
+kimi/k3 executed `tools.mcp__node_repl__js`, devlog `260813_tool_catalog_deferral/010+020`).
+Stamping `false` instead forces every MCP declaration into `exec.description` — a measured 2.7x
+turn-1 payload regression (96,699 → 258,929 chars). For Cursor this can also make the unified
+`exec` exceed the 120,000-byte serialized `McpTools` ceiling; the budget then drops `exec` and
+its companion `wait` (#1830). Hosted search remains independent: non-Cursor routes keep
+`web_search_tool_type: "text_and_image"`, while Cursor omits it because runTurn bypasses the
+search sidecar.
+
+> Decision record: [ADR-0022](decisions/ADR-0022-routed-tool-discovery-and-hosted-search.md)
+
+## Ultra reasoning level
+
+Ultra is always advertised in the catalog regardless of the `multi_agent_v2` toggle. The v2 toggle
+controls only the multi-agent collab surface, not ultra visibility. The `nativeEffortClamp` function
+wire-clamps ultra/max to each model's real top rung (e.g. gpt-5.5 ultra → xhigh on the wire).
+
+`effortCap` and `subagentEffortCap` are hard ceilings applied on the V2 path
+(`src/server/effort-policy.ts`): they lower or preserve the requested effort rather than rejecting
+the request, and they never raise it.
+
+The `ocx effort` CLI accepts only the same canonical cap ladder before live probing or persistence.
+Its status output preserves unsupported legacy cap values and reports that those fields are ignored;
+the read does not normalize or migrate them, and an ignored subagent field does not disable a valid
+main cap. Injection-effort input remains a separate contract.
+
+Operator-owned `pinnedReasoningEffort`, `modelPinnedReasoningEfforts`, and root
+`modelPinnedEfforts` resolve before applicable effort caps at the final destination.
+Provider model pins precede provider-wide pins, then global selector/destination pins.
+A pin can raise the effective caller effort; the later cap can still lower or omit it.
+`none` means explicit-effort omission (provider default), not guaranteed reasoning disablement.
+Compaction maintenance is exempt. Pins are user overlays and do not alter registry seeds,
+model discovery or advertised ladders. Native Chat normalizes newly pinned values through
+provider wire mapping; unpinned native requests retain their existing pass-through contract.
+
+> Decision record: [ADR-0023](decisions/ADR-0023-ultra-reasoning-level.md)
+
+> Decision record: [ADR-0024](decisions/ADR-0024-ultra-reasoning-level.md)
+
+> Decision record: [ADR-0025](decisions/ADR-0025-ultra-reasoning-level.md)
+
+> Decision record: [ADR-0026](decisions/ADR-0026-ultra-reasoning-level.md)
+
+Codex display-cache expiry, retained main-policy evidence, and reset history follow the
+[quota cache contract](providers/openai-tiers.md#quota-cache-and-short-window-history).
+
+Chat helper admission in `src/server/responses/core.ts` follows the
+[deferred stored-main contract](providers/openai-tiers.md): only a needed Direct OpenAI helper
+claims stored main, after terminal vision, routed vision and search exclusions.
+
+The management quota DTO keeps Combo editing aligned with scoped inference evidence;
+see [Combo editor routing quota](gui-and-management-api.md#combo-editor-routing-quota).
+
+## Paginated history writer boundary
+
+`src/codex/history-provider.ts` refuses external writes to paginated or migration-capable history. `src/codex/inject.ts` checks affected rows and manifest-owned restore targets before artifact changes and compensates detected migration. Failed config restore stops later catalog/history work. See the [history writer contract](codex-home.md#paginated-history-writer-boundary) for guarantees and concurrent-writer limits.
+
+Claude replay carries [Go conversation affinity](data-planes/inbound-compat.md#claude-affinity-at-final-go-dispatch)
+privately to final dispatch; preliminary route selection does not inject Go-only headers.
diff --git a/structure/clients/claude-desktop.md b/structure/clients/claude-desktop.md
new file mode 100644
index 0000000000..37b7eeef4c
--- /dev/null
+++ b/structure/clients/claude-desktop.md
@@ -0,0 +1,95 @@
+# Claude Desktop Integration
+
+## Connected Claude Desktop profiles
+
+Connected `ocx claude desktop apply` reads the hub's Desktop snapshot and writes the hub origin
+and exact hub-issued IDs to the local Desktop configuration. Static/hybrid embed the entries;
+discovery-only keeps discovery on the hub. The hub owns family assignments and defaults; local
+show/edit/import/export operations do not manage that profile. After hub changes or historical
+client-only aliases, apply again and reselect the model. Connected `import --apply` is explicitly
+unsupported and refuses before saving the import.
+
+`src/claude/desktop-discovery-inputs.ts` owns the shared Desktop discovery projection used by
+startup registry initialization and server discovery. `src/server/index.ts` exposes the explicit
+`GET /v1/models?ids=desktop&format=desktop-config` snapshot, shaped as `{version:1,models:[...]}`
+and sent with `Cache-Control: no-store`. `src/client/hub-client.ts` downloads it with the existing
+data credential; `src/cli/claude-desktop.ts` selects connected apply, and `src/claude/desktop-3p.ts`
+writes the resulting local Desktop configuration. No admin token, hub-profile upload or local
+alias regeneration is part of this flow. Unsupported old hubs, invalid snapshots and unavailable
+Desktop models fail apply without a local-catalog or loopback fallback.
+
+Date-shaped Desktop IDs can overlap genuine native model IDs. When available discovery and
+mapping evidence cannot resolve one, Messages and count-tokens return HTTP 503 with the fixed
+`desktop_model_mapping_unavailable` error rather than classifying it as invalid. Unknown legacy hash aliases
+remain HTTP 400; neither case reaches date-stripping or fallback routing. Known/registered IDs,
+exact operator mappings and recognized native IDs keep their existing handling. Discovery refresh
+or reapplying the connected hub profile may supply the missing mapping; retry alone does not
+guarantee resolution.
+
+The remote-alias slice does not change thinking/redacted-thinking replay or prompt-cache
+behavior. Those remain the separate request tracked in #3719; proxy admission alone does not
+establish native Anthropic passthrough or imply that translated Anthropic caching is disabled.
+
+### Desktop ownership across the connection lifecycle
+
+`src/claude/desktop-remote-store.ts` owns the first protected restoration baseline and the
+connection-owned Desktop fields. `src/cli/claude-desktop.ts` handles connected apply, while
+`src/client/connect.ts` coordinates key rotation/recovery and disconnect. Reapply and rotation retain the original
+baseline. Restoration merges into current user fields, preserves unrelated profiles, and restores
+the previous selection only while the managed profile is still selected. A later valid user
+selection is not changed. A newly created profile with user additions is retained in readable
+standard mode instead of deleting those additions.
+
+A proven legacy current-hub/recognized-key profile without an original baseline can be adopted
+by apply, rotation/recovery or direct disconnect without a new flag or prerequisite reapply.
+Its explicit standard-fallback outcome is distinct from original restoration: only owned gateway
+settings are removed, with user fields and independent valid selection preserved. Unknown keys,
+changed managed fields or damaged restoration records remain conflicts, not permission to capture
+new originals or overwrite user data.
+
+Rotation changes credentials without changing model IDs, family/default choices or selecting the
+managed profile again. The CLI reports `rotation: "committed"` only for the new active generation;
+`rotation: "rolled_back"` means the previous generation was retained/restored and must not claim
+revocation of that previous key. Incomplete recovery keeps the operation unresolved. Disconnect
+restores Desktop even with `--keep-catalog`; retries preserve the original catalog choice and must
+not clear a newer connection. Authorized uninstall completes or resumes owned Desktop cleanup
+before removing OpenCodex state, and preserves recovery state when cleanup conflicts or fails.
+
+These guarantees concern files on disk. Fully quitting and reopening Desktop is required after
+apply, rotation/recovery or restoration; there is no automatic process restart or guarantee that
+a running app discarded a key. Local disconnect does not revoke the hub key or remove arbitrary
+external copies. Model-list snapshot version 1 remains a read-only contract, not a new lifecycle
+or profile-upload API. Thinking replay and prompt caching remain separate in #3719.
+
+## Claude Desktop config-library resolution
+
+The Desktop profile writer and the management status probe share
+`resolveDesktop3pConfigLibraryPath`. The resolver reproduces Desktop's own rule rather than a guess:
+an explicit `CLAUDE_USER_DATA_DIR` (or the opencodex override) wins; on Windows
+`%LOCALAPPDATA%\Claude-3p` wins; otherwise the Electron user-data path gains a `-3p` suffix if it
+does not already have one. `configLibrary` is appended to that root.
+
+`Claude-3p` is Desktop's real directory name, assembled at runtime from `"Claude" + "-3p"`, which is
+why searching the app bundle for the literal string finds nothing. It is not a legacy path to migrate
+away from. Resolution stays a pure function of (env, platform, home) so the Windows branch is
+testable on any host: stubbing `process.platform` does not propagate to `os.platform()` under Bun.
+
+> Decision record: [ADR-0046](../decisions/ADR-0046-claude-desktop-config-library-resolution.md)
+
+Chat helper admission in `src/server/responses/core.ts` follows the
+[deferred stored-main contract](../providers/openai-tiers.md): only a needed Direct OpenAI helper
+claims stored main, after terminal vision, routed vision and search exclusions.
+
+The management quota DTO keeps Combo editing aligned with scoped inference evidence;
+see [Combo editor routing quota](../gui-and-management-api.md#combo-editor-routing-quota).
+
+Claude replay carries [Go conversation affinity](../data-planes/inbound-compat.md#claude-affinity-at-final-go-dispatch)
+privately to final dispatch; preliminary route selection does not inject Go-only headers.
+
+The explicit sync coordinator also accepts Cline CLI as a separate file integration. Its [paired-file recovery](integrations.md#cline-paired-files) is owned by the generic integration journal, independently of Desktop profile snapshots.
+
+`claudeCode.stabilizePromptCache` is a default-off operator setting for
+[translated instruction stabilization](../data-planes/inbound-compat.md#opt-in-claude-instruction-stabilization).
+Config JSON preserves the boolean; only literal true activates the role-changing transform.
+
+The lightweight top-level CLI help counts Cline CLI among the fifteen registered export clients; registry parity remains covered by the client help and integration tests.
diff --git a/structure/09_client-integrations.md b/structure/clients/integrations.md
similarity index 57%
rename from structure/09_client-integrations.md
rename to structure/clients/integrations.md
index 8e8c458580..33d877b5e5 100644
--- a/structure/09_client-integrations.md
+++ b/structure/clients/integrations.md
@@ -75,13 +75,7 @@ non-empty list without `image` becomes `false`; an absent or empty modality list
 model object so Hermes receives no guessed capability. OpenCodex does not emit `supports_video`
 because its authoritative input-modality vocabulary currently has no video value.
 
-[Decision Log]
-- 목적과 의도: Preserve catalog-backed image routing when Hermes uses OpenCodex as a custom provider.
-- 기존 구현 및 제약 조건: A string array preserved model selection but normalized to empty metadata in Hermes, while OpenCodex has authoritative text/image/audio facts but no video fact.
-- 검토한 주요 대안: Keep the array; mark every model vision-capable; infer video from model names; emit a per-model metadata map from declared modalities.
-- 선택한 방식: Emit a stable per-model map and include only the `supports_vision` boolean that the catalog can prove.
-- 다른 대안 대신 이 방식을 선택한 이유: The map is the Hermes-supported capability boundary, while guesses would misroute attachments or advertise unsupported video.
-- 장점, 단점 및 영향: Vision-capable custom models route correctly and text-only rows stay explicit; unknown rows remain unknown, and video routing waits for authoritative source metadata.
+> Decision record: [ADR-0090](../decisions/ADR-0090-hermes-model-capabilities.md)
 
 ## Ownership Axes
 
@@ -94,13 +88,7 @@ fall back to comparing the recorded generated contribution when the catalog has
 keeps old records readable while preventing a client's formatting-only key reorder from
 masquerading as a protected edit.
 
-[Decision Log]
-- 목적과 의도: Treat JSON object-key order as formatting while retaining safe ownership proof across upgrades.
-- 기존 구현 및 제약 조건: Existing records contain order-sensitive hashes, and replacing their hash format in place would make every installed integration look foreign-edited.
-- 검토한 주요 대안: Replace the hash format globally; ignore key order only for ZCode; store a semantic companion beside the existing exact hash.
-- 선택한 방식: Preserve the exact hashes for compatibility and add object-key-independent semantic companions to new records, with a bounded desired-contribution fallback for old records.
-- 다른 대안 대신 이 방식을 선택한 이유: A global replacement cannot validate old records, while a ZCode-only exception would leave the shared JSON ownership rule inconsistent.
-- 장점, 단점 및 영향: New records tolerate key normalization even across catalog refreshes; old records recover when the recorded catalog is still reconstructible, and ambiguous old-record drift remains fail-closed.
+> Decision record: [ADR-0091](../decisions/ADR-0091-ownership-axes.md)
 
 Clients normally protect every field in every recorded fragment. A client that writes documented,
 runtime-derived fields back into an owned fragment may additionally record:
@@ -130,13 +118,7 @@ only while the desired contribution is still identical to the one recorded at ap
 catalog also changed, the old record cannot distinguish catalog drift from a foreign edit and must
 fail closed. A successful refresh writes the new operation-scoped policy.
 
-[Decision Log]
-- 목적과 의도: Allow ZCode's documented runtime normalization without turning genuine provider or connection edits into refreshable drift.
-- 기존 구현 및 제약 조건: The classifier hashed the whole `provider.opencodex` fragment. That was safe for ordinary JSON clients but made every ZCode save a permanent foreign edit. Refresh and disable both depend on the same ownership proof.
-- 검토한 주요 대안: Ignore all model metadata; compare only the provider connection envelope; hard-code a ZCode branch directly in `state.ts`; store explicit operation-scoped mutable paths and a protected fingerprint.
-- 선택한 방식: Keep the strict generated contribution hash, add a separate protected fingerprint, and persist the exact ZCode-derived paths with each ownership record through a client-scoped policy module.
-- 다른 대안 대신 이 방식을 선택한 이유: Ignoring all model metadata would allow user model edits to be overwritten. Comparing only the connection envelope would stop protecting model membership and capabilities. A state-only special case would disagree with writer behavior. Operation-scoped paths preserve the original grant across later catalog changes.
-- 장점, 단점 및 영향: Normal ZCode saves become refreshable, connection edits still fail closed, and later catalog refreshes remain possible. Legacy records with simultaneous catalog drift still require a conservative manual recovery because the old schema did not store enough evidence.
+> Decision record: [ADR-0092](../decisions/ADR-0092-zcode-runtime-metadata.md)
 
 ## Verification
 
@@ -174,67 +156,6 @@ credential — the `OPENCODEX_API_AUTH_TOKEN` / service-token-file / `apiKeys` l
 admin token — or logs that it is degrading. Composing `http://127.0.0.1:<public port>` by hand is
 what produced a dead socket on a tailnet-bound hub in the first place.
 
-## Connected Claude Desktop profiles
-
-Connected `ocx claude desktop apply` reads the hub's Desktop snapshot and writes the hub origin
-and exact hub-issued IDs to the local Desktop configuration. Static/hybrid embed the entries;
-discovery-only keeps discovery on the hub. The hub owns family assignments and defaults; local
-show/edit/import/export operations do not manage that profile. After hub changes or historical
-client-only aliases, apply again and reselect the model. Connected `import --apply` is explicitly
-unsupported and refuses before saving the import.
-
-`src/claude/desktop-discovery-inputs.ts` owns the shared Desktop discovery projection used by
-startup registry initialization and server discovery. `src/server/index.ts` exposes the explicit
-`GET /v1/models?ids=desktop&format=desktop-config` snapshot, shaped as `{version:1,models:[...]}`
-and sent with `Cache-Control: no-store`. `src/client/hub-client.ts` downloads it with the existing
-data credential; `src/cli/claude-desktop.ts` selects connected apply, and `src/claude/desktop-3p.ts`
-writes the resulting local Desktop configuration. No admin token, hub-profile upload or local
-alias regeneration is part of this flow. Unsupported old hubs, invalid snapshots and unavailable
-Desktop models fail apply without a local-catalog or loopback fallback.
-
-Date-shaped Desktop IDs can overlap genuine native model IDs. When available discovery and
-mapping evidence cannot resolve one, Messages and count-tokens return HTTP 503 with the fixed
-`desktop_model_mapping_unavailable` error rather than classifying it as invalid. Unknown legacy hash aliases
-remain HTTP 400; neither case reaches date-stripping or fallback routing. Known/registered IDs,
-exact operator mappings and recognized native IDs keep their existing handling. Discovery refresh
-or reapplying the connected hub profile may supply the missing mapping; retry alone does not
-guarantee resolution.
-
-The remote-alias slice does not change thinking/redacted-thinking replay or prompt-cache
-behavior. Those remain the separate request tracked in #3719; proxy admission alone does not
-establish native Anthropic passthrough or imply that translated Anthropic caching is disabled.
-
-### Desktop ownership across the connection lifecycle
-
-`src/claude/desktop-remote-store.ts` owns the first protected restoration baseline and the
-connection-owned Desktop fields. `src/cli/claude-desktop.ts` handles connected apply, while
-`src/client/connect.ts` coordinates key rotation/recovery and disconnect. Reapply and rotation retain the original
-baseline. Restoration merges into current user fields, preserves unrelated profiles, and restores
-the previous selection only while the managed profile is still selected. A later valid user
-selection is not changed. A newly created profile with user additions is retained in readable
-standard mode instead of deleting those additions.
-
-A proven legacy current-hub/recognized-key profile without an original baseline can be adopted
-by apply, rotation/recovery or direct disconnect without a new flag or prerequisite reapply.
-Its explicit standard-fallback outcome is distinct from original restoration: only owned gateway
-settings are removed, with user fields and independent valid selection preserved. Unknown keys,
-changed managed fields or damaged restoration records remain conflicts, not permission to capture
-new originals or overwrite user data.
-
-Rotation changes credentials without changing model IDs, family/default choices or selecting the
-managed profile again. The CLI reports `rotation: "committed"` only for the new active generation;
-`rotation: "rolled_back"` means the previous generation was retained/restored and must not claim
-revocation of that previous key. Incomplete recovery keeps the operation unresolved. Disconnect
-restores Desktop even with `--keep-catalog`; retries preserve the original catalog choice and must
-not clear a newer connection. Authorized uninstall completes or resumes owned Desktop cleanup
-before removing OpenCodex state, and preserves recovery state when cleanup conflicts or fails.
-
-These guarantees concern files on disk. Fully quitting and reopening Desktop is required after
-apply, rotation/recovery or restoration; there is no automatic process restart or guarantee that
-a running app discarded a key. Local disconnect does not revoke the hub key or remove arbitrary
-external copies. Model-list snapshot version 1 remains a read-only contract, not a new lifecycle
-or profile-upload API. Thinking replay and prompt caching remain separate in #3719.
-
 ## Aside profile ownership
 
 Aside discovery projects only registered numeric account IDs, labels and current status. Catalog
@@ -247,3 +168,26 @@ pin one legacy root owner before changing it. Sibling stores remain independent.
 precede coordinated writes under one scoped flight, and actual file state/refusals remain
 separate. Restore reconciles target intent from validated snapshot ownership without changing
 sibling policy. Profile journal views retain source-store provenance for older legacy entries.
+
+## Cline paired files
+
+Cline CLI uses `providers.json` for connection settings and sibling `models.json` for its
+catalog. `src/integrations/cline-document.ts` separates native documents from raw-byte snapshot
+bundles; `src/integrations/cline-io.ts` projects both files onto the existing writer/journal.
+Only each file's `providers.opencodex` entry is owned. Schema envelopes and the user's default
+provider remain user-owned. Cline's selected model and update timestamp can change during normal
+use; refresh preserves a selection only while its model remains routed. Connection fields and
+catalog membership remain protected.
+
+Each file replacement is atomic; the pair is recoverable, not simultaneously visible. Stop Cline
+before explicit enable/sync/disable/restore and restart afterward. Unattended refresh excludes
+Cline. A private pending record precedes replacement and survives partial failure. Read-only
+status reports an unfinished pair as unsafe; explicit mutation recovers only unchanged original
+or intended bytes and compatible ownership. A journaled pair must match both intended files and
+final ownership before pending cleanup. Foreign edits retain the pending evidence and refuse.
+Undo restores both original byte strings, including individual file absence; drift requires the
+existing explicit confirmation. The journal endpoint evaluates Undo against the same pair.
+
+Recovery reads commit history and ownership through strict store methods. Unreadable or malformed
+metadata is uncertainty, never evidence that a transaction did not commit. Pending records validate
+complete ownership, exact Cline paths and result fingerprints before either native file is replaced.
diff --git a/structure/codex-home.md b/structure/codex-home.md
new file mode 100644
index 0000000000..03eee35aa2
--- /dev/null
+++ b/structure/codex-home.md
@@ -0,0 +1,243 @@
+# Codex Home
+
+## Codex home
+
+`src/codex/paths.ts` resolves Codex state from `CODEX_HOME` when set and valid, otherwise from
+`~/.codex`. An unset `CODEX_HOME` falls back to `~/.codex`, including WSL discovery. An explicitly
+set path that is unreadable or not a directory is an error, not a fallback: silently using a
+different home than the operator named would write provider state where nobody is looking for it.
+The managed files are:
+
+```text
+$CODEX_HOME/config.toml
+$CODEX_HOME/opencodex.config.toml
+$CODEX_HOME/opencodex-catalog.json
+$CODEX_HOME/opencodex-journal.json
+$CODEX_HOME/models_cache.json
+$CODEX_HOME/.opencodex-native-main-profiles/
+```
+
+Never assume macOS-only paths. Windows, service installs, and app-launched Codex can all depend on
+the resolved `CODEX_HOME`.
+
+Journal restoration compares config and profile independently against their saved originals and
+recorded injected hashes. If either changed artifact lacks its injected hash, the config/profile
+pair and journal remain untouched and the result is explicitly unverified; callers must not
+convert that refusal into successful fallback cleanup. Already-original bytes need no rewrite,
+and absence is distinct from an empty file. The injector checks a retained hashless journal against
+the same `baselineContent` it snapshots, plus the current profile, before writing or assigning a new
+injected hash. Native content can establish a fresh snapshot; routed content cannot promote an
+unverified older original. Existing hash-backed edit preservation and external-provider opt-out
+remain separate paths.
+
+The source-built Docker image explicitly keeps `CODEX_HOME=/home/bun/.codex` separate
+from `OPENCODEX_HOME=/home/bun/.opencodex`. Compose persists them in `codex-state` and
+`ocx-state` respectively, retaining a read-only root. The image creates owner-only
+writable homes for `bun`; existing volume ownership and permissions are not repaired.
+The catalog resolver is unchanged; a writable empty home is not a materialized catalog.
+
+> Decision record: [ADR-0005](decisions/ADR-0005-codex-home.md)
+
+`docker compose down` retains both volumes. `docker compose down --volumes` deletes
+both `ocx-state` and `codex-state`, including their credentials and catalog/state;
+treat it as destructive, not as an upgrade or restart command.
+
+Service install-state ownership uses this same resolver. In WSL, an unset `CODEX_HOME` may resolve
+to the single discoverable Windows Desktop home; recording Linux `~/.codex` instead would make a
+later repair or uninstall look foreign even though the service and runtime were started from the
+same environment. An explicit `CODEX_HOME` remains authoritative, and existing foreign ownership
+records are never migrated implicitly.
+
+> Decision record: [ADR-0006](decisions/ADR-0006-codex-home.md)
+
+SQLite-backed thread state may live outside `CODEX_HOME`. The one resolver in `src/codex/paths.ts`
+uses Codex's precedence: root `sqlite_home` in the effective `config.toml`, then
+`CODEX_SQLITE_HOME`, then the effective `CODEX_HOME`; relative SQLite homes resolve from the current
+working directory. History jobs resolve the database and its hashed backup identity together at
+call time, and admission/residue checks consume the same database path. Storage retention still
+owns the Codex-home tree separately and does not gain deletion authority over an external SQLite
+root from this resolver alone. Durable service launchers preserve an explicitly supplied
+`CODEX_SQLITE_HOME` so a background service resolves the same split state as the installing shell.
+An absent `config.toml` or absent root `sqlite_home` permits the environment/home fallback. Any
+other read failure, malformed TOML, wrong-typed or blank `sqlite_home` is indeterminate and fails
+closed so history code cannot select a different database by accident. This strict parse is scoped
+to SQLite ownership; the tolerant root-string helper used by injection and catalog reads is unchanged.
+
+> Decision record: [ADR-0007](decisions/ADR-0007-codex-home.md)
+
+Native-main profile ownership is bound to the real `CODEX_HOME`, not to an OpenCodex instance.
+Its encrypted vault, transaction journal, recovery marker, and referenced quarantine files live in
+the owner-only `.opencodex-native-main-profiles` directory. The unchanged
+`.opencodex-native-profile.lock.sqlite` beside that directory serializes every process sharing the
+home. Only plaintext login staging is instance-local under
+`$OPENCODEX_HOME/native-main-profile-staging`; a stage from one instance is invalid in another.
+These paths and the OS keyring are owner-only: the operating-system account that owns them is the
+trust boundary and already has direct access to active native credentials. OpenCodex detects and
+fails closed on file identities that change during an operation, but it does not claim isolation
+from a malicious process already running as that same trusted OS account.
+
+Startup and the periodic stage cleaner do not acquire the profile transaction lock when both the
+stage registry and this instance's staging tree are proven absent. This keeps an unused profile
+subsystem from fencing native traffic or creating lock contention. Presence, an unsafe entry type,
+or any observation error still takes the locked sweep and fails closed; the fast path is based only
+on proven absence, never on an unreadable path.
+
+> Decision record: [ADR-0008](decisions/ADR-0008-codex-home.md)
+
+The native-write coordinator is keyed by the canonical `CODEX_HOME` in the effective-user runtime
+namespace. A pathname alone is not authority: SQLite can expose a zero-byte file before its first
+schema write, and a terminated process can leave that remnant behind. Eligibility treats the file
+as non-authoritative only after an immutable SQLite read proves version zero with no tables, the
+filesystem identity remains unchanged, and the file has been settled for at least one second; a
+fresh zero-byte creator stays on the coordinated path so its lock cannot be bypassed. `ocx doctor` inspects the
+coordinator with immutable read-only SQLite flags so diagnosis never creates WAL/SHM sidecars. It
+distinguishes absent, zero-byte, unversioned, rowless, valid, unsupported, changed, unsafe, and
+unreadable states and prints the exact path. Explicit recovery is available only after the proxy is
+stopped and only for a proven zero-byte state. The command revalidates the same private
+regular-file identity under a non-blocking SQLite write lock and moves it to a same-directory
+backup; it never deletes or auto-adopts legacy routed residue.
+
+> Decision record: [ADR-0009](decisions/ADR-0009-codex-home.md)
+
+OpenCodex never overrides an explicit `CODEX_HOME`. On Windows, `ocx doctor` and `ocx status`
+nevertheless diagnose the high-confidence Orca dual-home case: both `CODEX_HOME` and
+`ORCA_CODEX_HOME` select Orca's `orca/codex-runtime-home/home`, while the ChatGPT/Codex app uses the
+default `%USERPROFILE%\\.codex`. Sync and restore output always prints the exact target Codex home;
+display and JSON paths redact the OS username. The diagnostic tells users to invoke OpenCodex with
+the app home explicitly rather than silently claiming that an unrelated app was configured. If a
+service was installed under the Orca home, it must first be uninstalled from that original Orca
+environment and then reinstalled under the app home; changing only the current shell cannot migrate
+the recorded service ownership.
+
+> Decision record: [ADR-0010](decisions/ADR-0010-codex-home.md)
+
+`atomicWriteFile` uses a temp file named `{path}.ocx.{pid}.{seq}.tmp` (process ID + incrementing
+sequence number) to avoid collisions when concurrent writers (e.g. `ocx stop` and the proxy's own
+shutdown handler) both restore Codex config simultaneously. The temp is renamed atomically into place.
+Storage cleanup run metadata uses the field-scoped persisted-config mutation path, so a background
+Worker cannot restore unrelated API keys or provider settings from a snapshot read before the lock.
+If that metadata write is unavailable after cleanup has already completed, the job retains the
+cleanup outcome and exposes a bounded persistence error instead of relabeling the run as a Worker failure.
+
+Cleanup manifests and satellite backups share the stage-local atomic publisher: an exclusive
+private temporary file is fully written and file-synced before the existing Windows-tolerant
+rename replaces the destination. Handled publication failures retain the previous record;
+directory syncing remains best-effort. This does not make a partial permanent purge reversible:
+restore still fails closed when a recorded logical entry has no surviving file.
+
+Windows secret-file hardening resolves the effective token SID through an absolute, trusted
+PowerShell path before granting the owner and removing inherited broad ACL entries. The normal
+path obtains System32 from `GetSystemDirectoryW`. Windows ARM64 Bun builds that cannot execute
+`bun:ffi` use a narrower ACL-only fallback to the fixed protected default installation path
+`C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe`. The fallback never applies to UAC or
+Task Scheduler launch, never consults environment variables or `PATH`, and fails closed when the
+fixed executable is absent.
+
+Direct PowerShell children rely on the process launcher's `windowsHide`/hidden-host mechanism and
+must not also receive the PowerShell CLI pair `-WindowStyle Hidden`. On affected Windows 11 systems,
+Bun 1.3.14 exits that direct invocation before the command runs, which turns a valid SID or process
+lookup into `EACLIDENTITY` or a failed sync. This does not apply to `Start-Process -WindowStyle
+Hidden` inside an already-running PowerShell script, nor to .NET/VBS process-window settings.
+
+> Decision record: [ADR-0011](decisions/ADR-0011-codex-home.md)
+
+> Decision record: [ADR-0012](decisions/ADR-0012-codex-home.md)
+
+The durable response-spill directory `~/.opencodex/responses-state-spill/` is bounded in
+aggregate, not only per file. Continuation state demoted out of the in-memory cap
+(`MAX_STORED_RESPONSE_BYTES`) is written there, and eviction past
+`MAX_SPILLED_RESPONSE_BYTES` removes oldest-first through the same deletion point that serves
+TTL and count eviction, so an evicted entry unlinks its file. One function owns that ceiling and
+three callers drive it: mutation pruning, the lazy load that follows a restart, and the periodic
+sweep. The periodic caller is not redundant — the mutation path runs only when traffic arrives, so a
+process that comes up over budget from a snapshot written under a larger ceiling would otherwise
+stay over it while idle.
+
+The ceiling bounds what the store can account for, which is every entry in the map plus the
+superseded generations queued for unlink, and deliberately not the directory as a whole. Spill files
+orphaned by a crash are absent from the map, so this accounting can neither see nor price them; they
+remain with the `recoverOrphanedResponseSpills` grace sweep described below, which is the only
+mechanism that reclaims them. A host that crashes repeatedly can therefore hold spill bytes above
+this ceiling for up to `RESPONSE_SPILL_ORPHAN_GRACE_MS` past each crash. Without that aggregate bound the
+directory was limited only per file (256 MiB) and per entry (1000) — a 250 GiB product — which
+left `RESPONSE_TTL_MS` as the only effective limit and made disk use a function of client
+request rate rather than of anything the process controls.
+
+> Decision record: [ADR-0013](decisions/ADR-0013-codex-home.md)
+
+Response-state loading performs a bounded recovery pass for interrupted snapshot writes. It only
+matches regular files named `responses-state.json.ocx.<pid>.<sequence>.tmp`, waits at least 15
+minutes, and skips the current or any live PID. Eligible files are truncated before unlinking so a
+matching stale path is unlinked without following it. Path-based truncation is intentionally avoided:
+a same-user replacement could otherwise turn cleanup into a write through a symlink. Unrelated
+temporary files, symlinks, directories, and young/active writes are never touched; directory entries
+are consumed incrementally and at most 512 stale files are attempted per process start.
+
+> Decision record: [ADR-0014](decisions/ADR-0014-codex-home.md)
+
+Windows runtime response spills never wait on `icacls` through `Bun.spawnSync`. Linux and macOS
+retain the immediate synchronous publication path. On Windows, the resident continuation enters one
+serialized publication queue and remains replayable while `hardenSecretDirAsync` and
+`hardenSecretPathAsync` run. Publication installs a spill stub only when the map still contains the
+same resident object; a superseded job deletes its newly published file instead of overwriting newer
+state. Pending payloads are pinned and capped at 256 MiB, so an ACL outage cannot grow an unbounded
+queue or be misreported as evictable memory. One caller-owned retry is allowed after a real
+`ETIMEDOUT`; the first timeout does not install a `spill-failed` tombstone. Required ACL failures
+remain fail-closed after that bounded recovery. Optional config-directory hardening uses a separate
+per-directory async single-flight, while required config mutation writers retain their existing
+awaited or synchronous fail-closed boundary.
+
+Each ordinary async spill write attempt owns one 30-second ACL budget shared across directory, temp,
+and exclusive-copy destination hardening; the single timeout retry receives one fresh whole-attempt
+budget. No harden step may reopen an independent 30-second window inside either attempt.
+Both icacls and effective-principal subprocess waits are settlement-bounded: at deadline the child is
+killed, unref'd, and abandoned without awaiting `proc.exited`. The caller-level deadline also bounds
+injected/shared runners, so a child that ignores termination cannot pin the serialized spill queue.
+
+Graceful shutdown drains that serialized publication queue to a stable fixed point before snapshot
+serialization. The drain has a wall-clock cap with a reserved synchronous fallback budget; expiry
+supersedes the async writer, claims and removes any temp or destination it still owns, and only then
+starts fallback publication. The writer rechecks supersession before no-replace publication, while
+the fallback splits its reserve across the directory and file ACL hardens. This ordering is
+load-bearing because resident entries over 2 MiB are deliberately excluded from
+`responses-state.json`: serializing first could omit the resident before its durable spill stub
+exists, losing the continuation on restart. Cleanup is attempted for every abandoned writer; any
+failure is retained while fallback and snapshot persistence continue, then returned through the
+shutdown status so process exit is non-zero without sacrificing unrelated replay state.
+If the fallback reserve expires, every remaining resident candidate is terminalized as a bounded
+`spill-failed` tombstone before pruning, so no payload remains eligible for shutdown requeue and the
+snapshot flush always regains control.
+The terminalization pass itself is hard-capped at `MAX_STORED_RESPONSES + 1`; exceeding that
+structural bound records a bounded failure, fail-closes every remaining resident, and returns control
+to snapshot persistence instead of relying on the progress argument alone.
+
+> Decision record: [ADR-0015](decisions/ADR-0015-codex-home.md)
+
+## Codex-home diagnostics
+
+Some Codex-home conditions are reported rather than repaired, because repairing them would overwrite
+a deliberate user choice:
+
+- Bundled-plugin marketplace state on Windows (`src/codex/plugins-doctor.ts`), surfaced by
+  `ocx status`.
+- Project-level Codex config that bypasses managed routing
+  (`src/codex/project-config-warnings.ts`), surfaced by `ocx doctor` as a warning rather than an
+  override.
+
+Codex display-cache expiry, retained main-policy evidence, and reset history follow the
+[quota cache contract](providers/openai-tiers.md#quota-cache-and-short-window-history).
+
+## Paginated history writer boundary
+
+`src/codex/history-provider.ts` rejects provider-history changes with `history_paginated_requires_native_writer` when a target begins with an ordinal-bearing record or declares `history_mode=paginated`. Apply, manifest-backed restore, and explicit legacy recovery preflight all selected targets before changing database rows or manifests. The append boundary checks again. Codex owns ordinal allocation and the live projection cursor; reading the last ordinal and appending N+1 is not safe concurrent coordination. Legacy unnumbered rollouts retain their existing behavior. This guard prevents the observed stable-format corruption; it does not implement native-writer integration or guarantee a concurrent legacy-to-paginated conversion is excluded.
+
+Injection preflights affected history using the normalized config candidate before writing config/profile/journal, then checks again after the complete artifact write. Detected migration restores all three preimages before returning a structured refusal, including on legacy-uncoordinated homes. A failed config restore stops catalog/history work; coordinated restore rolls back its published remove transition. Legacy first-line provider patches are bound to the validated file identity before and after writing. These compensating checks do not provide a native-writer lock or authorize external ordinal allocation.
+
+The legacy external writer is now refused for affected rows in any store whose schema includes history_mode, even while their row mode is still legacy. This deliberately sacrifices automatic relabeling on migration-capable stores rather than racing native conversion. Synchronous/asynchronous restore, inline journal restore, and direct config removal preserve all artifacts on the same refusal.
+
+Native restore preflight also checks manifest-owned targets whose rows already returned to `openai`, including interrupted restores. Preimage capture distinguishes absent files from unreadable artifacts and aborts before mutation when a complete snapshot cannot be read.
+
+A config restoration that was attempted and failed retains its failed artifact in the restore
+result; unattempted catalog and history artifacts remain skipped. Successful preimage compensation
+preserves config/profile/journal bytes without relabeling the failure as a skipped operation.
+Incomplete compensation still raises the explicit partial-write error.
diff --git a/structure/config.md b/structure/config.md
new file mode 100644
index 0000000000..4f532e789e
--- /dev/null
+++ b/structure/config.md
@@ -0,0 +1,209 @@
+# Config Surface
+
+## Config surface
+
+### OpenCodex home and live process state
+
+`initializePersistedConfigIfMissing` in `src/config.ts` is the create-only path consumed by
+`src/cli/init.ts`. It rechecks absence under the existing config-mutation lock and publishes through
+`src/config/initialize.ts`: a private descriptor is hardened before secret bytes are written, then
+linked without replacing an occupied destination. Existing invalid or unsafe entries are preserved.
+The initializer never truncates a staged inode or rolls back by unlinking the destination; cleanup
+only removes its own temporary name. Unsupported/denied links and incomplete cleanup fail explicitly,
+and publication followed by a later failure can leave a complete config or private residue. Ordinary
+`saveConfig` replacement behavior remains unchanged. This protects init-time config bytes, not a
+foreign winner's ownership under future uninstall; the existing ownership manifest and global CLI
+shim preflight keep their separate contracts.
+
+Initial publication diagnostics distinguish required permission-hardening failures from denied
+hard-link publication without exposing raw filesystem causes. Both identify `OPENCODEX_HOME`
+as the supported-location recovery path; uncertain publication and cleanup warnings remain in
+the CLI. The quickstart documents inspection before retry, private-permission requirements,
+and fresh-location examples. Diagnostics do not introduce a fallback or alter file I/O ordering.
+
+`src/config/paths.ts` is the single owner of `OPENCODEX_HOME` expansion and resolution. It exposes
+the config directory and `config.json` path and retains the existing cache rule: a relative home is
+resolved once for each distinct raw environment value, so a later working-directory change cannot
+silently move the active installation.
+
+`src/config/process-state.ts` derives `ocx.pid` and `runtime-port.json` from that resolved directory.
+It owns their byte-compatible writes, parsing, expected-PID filters, cheap liveness, full OCX command
+identity, and snapshot-guarded removal. `RuntimePortState.attestationSecret` remains optional,
+owner-only state and is validated before a record is returned. `src/config.ts` re-exports the same
+symbols for compatibility, but new lifecycle-only callers import the process-state leaf directly.
+
+Replacing config and process-state writes use `src/config/atomic-write.ts`. The leaf preserves the shared
+process-wide temp sequence, symlink target resolution, real-home test guard, owner manifest,
+Windows ACL hardening, scrub-before-unlink failure path, and explicit residual-temp errors. A caller
+must not replace it with a local temp-and-rename shortcut.
+
+> Decision record: [ADR-0016](decisions/ADR-0016-config-surface.md)
+
+`src/types.ts` is the shape and `src/config.ts` is the loader; neither is reproduced here. What
+matters for maintainers is which groups exist and who resolves them:
+
+| Group | Keys | Resolution rule |
+| --- | --- | --- |
+| Listener | `port`, `hostname` | The listener owns the port; `runtime-port.json` reports where it actually landed. |
+| Routing | `defaultProvider`, `providers`, per-provider `selectedModels` | Explicit `provider/model` wins over `defaultProvider`. |
+| Catalog | `disabledModels`, `customModels`, `modelCacheTtlMs`, `providerContextCaps`, `contextCapValue`, per-provider `modelDisplayNames`, `codexAccountNamespaces`, `codexAccountPickerEnabled` | Catalog state is derived; config only records intent. Exact provider model display names are durable display only overlays. The picker flag is an explicit visibility override, while selector mappings remain the durable exact-routing contract. |
+| Retained state | `appOwnedMemoryBudgetMb` | Process-wide eviction target for app-owned logs, caches, blobs, and continuation payloads. Default 256 MiB, valid 64..4096; pinned state may temporarily exceed the target, but every pin-capable store has a finite local cap and their documented aggregate stays below `APP_OWNED_WORST_CASE_PINNED_BYTES` (512 MiB). Neither value caps RSS or native runtime memory. |
+| Transport | stream mode, timeouts, proxy settings, `websockets`, `emptyCompletionRetry` | `streamMode` persists in config.json; Windows services need a persisted input, and macOS uses it for explicit eager-relay opt-in. Empty-completion replay is an explicit top-level opt-in because its second upstream request may be billable. |
+| Credentials | `apiKeys` | Data-plane only; never admitted to `/api/*`. |
+| Lifecycle | `codexAutoStart`, shim/start behavior, resume-history sync, storage cleanup | Startup safety reads these; see [`gui-and-management-api.md`](gui-and-management-api.md). |
+
+Env values are resolved through `src/config.ts`, so a config value naming an env var never persists
+the secret itself.
+
+## Config injection
+
+`src/codex/inject.ts` writes one of two forms. The choice is not cosmetic: it decides whether Codex
+keeps its native provider id, which decides whether existing thread history still resolves.
+
+**Loopback (default).** A single marker-owned root override, no provider table:
+
+```toml
+model_catalog_json = "/absolute/path/to/opencodex-catalog.json"
+openai_base_url = "http://127.0.0.1:10100/v1"
+```
+
+Codex keeps the native `openai` provider id, so new threads stay under that identity instead of
+being re-tagged. History restore is manifest-authoritative: only rows whose original provider,
+source, and event marker were backed up for the same state database are restored exactly. A bare
+`opencodex` row is never assumed to have originated at OpenAI; it stays unchanged unless the user
+explicitly runs legacy OpenAI recovery. A user-owned root `openai_base_url` is preserved instead of
+overwritten, and that case also blocks managed sub-agent defaults rather than fighting the user for
+ownership.
+
+Client-compaction mode can retain that user-owned root URL alongside an injected provider table.
+Its status must distinguish ownership from destination: an unmarked user-owned line may already
+point to this proxy. Report that existing `openai` threads follow the configured root URL and new
+threads use the injected table, without inferring a foreign endpoint or prescribing URL removal.
+This diagnostic distinction does not change URL ownership, journal entries, or session history.
+
+**API auth header (non-loopback).** The built-in `openai` provider cannot carry the
+`x-opencodex-api-key` env header, so this form re-tags the root provider and appends the table:
+
+```toml
+model_provider = "opencodex"
+model_catalog_json = "/absolute/path/to/opencodex-catalog.json"
+
+[model_providers.opencodex]
+name = "OpenCodex Proxy"
+base_url = "http://<host>:<port>/v1"
+wire_api = "responses"
+requires_openai_auth = true
+env_key = "OPENCODEX_API_AUTH_TOKEN"
+```
+
+Root TOML keys must be written before the first `[table]`. Re-injection strips the stale form of
+both shapes — opencodex blocks, injected root base-url overrides, stale root context-window
+overrides, and stale catalog paths — before rewriting, so switching between forms leaves no residue.
+
+Read-only doctor and project-routing diagnostics use a lightweight root/table TOML reader rather
+than mutating or normalizing the user's file. That reader must lexically skip both basic and literal
+multiline string bodies: instruction prose can contain key-shaped examples and `[table]` snippets,
+which are data rather than configuration. Diagnostic result objects may retain the real path for
+local correlation, but every formatted doctor line must pass it through the shared user-path
+redaction boundary before display.
+
+> Decision record: [ADR-0017](decisions/ADR-0017-config-injection.md)
+
+Native Codex sub-agent defaults are a separate, explicit opt-in. When
+`syncCodexSubagentDefaults` is true and `injectionModel` is set, injection writes marker-owned
+`agents.default_subagent_model` and, when configured,
+`agents.default_subagent_reasoning_effort`. Unmarked values are user-owned and must never be
+overwritten. Disabling the option and fallback restore remove only marker-owned values; journal
+restore must preserve later user edits while stripping those managed values.
+
+### History backup manifest contract
+
+`src/codex/history-manifest.ts` is the pure schema-and-identity leaf for the versioned history
+backup manifest. It owns the accepted provider/source provenance tuples, platform-aware database
+path identity, backup filename id, and validation from unknown JSON to a typed manifest. It does
+not read files, inspect rollouts, open SQLite, retry, fingerprint, write, or delete anything.
+
+`history-provider.ts` remains the strict mutation owner and maps shared validation failures to its
+restore/no-op integrity states. `native-residue.ts` remains a read-only observer and maps the same
+result to clean, residue, or indeterminate before inspecting referenced rollout files.
+
+> Decision record: [ADR-0018](decisions/ADR-0018-config-injection.md)
+
+If the root config selects a provider other than `openai` or `opencodex`, injection must leave the
+config byte-for-byte unchanged and skip profile creation/updates and history metadata restoration. External
+provider managers own that routing configuration, and replacing their provider id can hide
+otherwise intact Codex sessions. This ownership check must run before catalog/cache refresh,
+journal creation, and the background history restoration guardian.
+
+`ocx sync` and `ocx restore back` run the injector's non-writing preflight before provider
+discovery or catalog/cache replacement. Deterministic config and ownership refusals therefore
+leave the existing catalog and cache untouched, and their concrete messages are emitted on stderr.
+The real injection still revalidates under its normal write boundary after catalog convergence;
+the preflight is an early no-write guard, not an authorization token for a later write.
+
+> Decision record: [ADR-0019](decisions/ADR-0019-config-injection.md)
+
+`supports_websockets = true` is appended to the provider table only when `websocketsEnabled(config)`
+returns true.
+
+## Profile and fast tier
+
+When opencodex owns routing, it also writes `$CODEX_HOME/opencodex.config.toml` as an explicit profile
+target. Codex config uses `service_tier = "fast"` and `[features].fast_mode = true`;
+catalog/request tier metadata may use `priority`. Do not collapse these spellings into one value.
+
+## Provider output defaults
+
+`OcxProviderConfig.defaultMaxOutputTokens` and `modelMaxOutputTokens` are OpenAI Chat wire defaults,
+not context-window metadata. They are applied only when a Responses request omits
+`max_output_tokens`; an explicit request value wins, then a model-specific configured value, then
+the provider default, then the adapter omits `max_tokens`.
+
+Both fields must stay positive finite integers at disk-config and management validation boundaries.
+Registry entries may seed them through `providerConfigSeed`, key-login derivation, OAuth reconcile,
+and `routeModel`, but user config overrides registry defaults per field/key.
+
+## Provider validation ownership
+
+`src/config/provider-validation.ts` owns the pure provider payload checks shared by persisted config,
+CLI writes, and management DTO validation. `src/config.ts` imports those checks for Zod refinement
+and re-exports them as a compatibility facade; it must not grow a second copy. Validation error text,
+ordering, and cross-field rules are part of the write/load contract because management requests and
+hand-edited `config.json` must accept and reject the same provider shapes.
+
+> Decision record: [ADR-0020](decisions/ADR-0020-provider-validation-ownership.md)
+
+## Restore
+
+`ocx stop`, `ocx restore` / `ocx eject`, `ocx service stop`, and `ocx service uninstall` must strip
+opencodex config and routed catalog entries without damaging native Codex state.
+
+Full `ocx uninstall` config cleanup is ownership-manifest based. A fresh config directory receives a
+root-bound owner marker and an uninstall manifest before its first atomic config write. Uninstall
+validates both bounded metadata files, rejects path traversal and a symlink/junction config root,
+and removes only normalized manifest entries. Manifest-owned directory links are unlinked without
+traversing their targets. Unknown files remain in place and make the command report a partial
+uninstall with their exact paths.
+
+Legacy nonempty config directories are deliberately not retroactively claimed. If either ownership
+file is missing, malformed, or bound to another root, uninstall refuses config deletion and reports
+the residual directory for manual review; there is no recursive-delete fallback.
+
+## Remote client key files
+
+Client connection metadata stores a stable `apiKeyId` and a non-secret rotation `pendingOperation`. The current data secret remains only in `service-api-token`; a bounded rotation temporarily keeps the old secret in owner-only `service-api-token.prev`. Commit or recovery clears the marker before orphan cleanup. `ocx disconnect` is local-only and leaves remote revocation to the hub's **Integrations → API Keys** page. Hub and local usage stores are not mirrored.
+
+Codex display-cache expiry, retained main-policy evidence, and reset history follow the
+[quota cache contract](providers/openai-tiers.md#quota-cache-and-short-window-history).
+
+## Paginated history writer boundary
+
+`src/codex/history-provider.ts` refuses external writes to paginated or migration-capable history. `src/codex/inject.ts` checks affected rows and manifest-owned restore targets before artifact changes and compensates detected migration. Failed config restore stops later catalog/history work. See the [history writer contract](codex-home.md#paginated-history-writer-boundary) for guarantees and concurrent-writer limits.
+
+The Cline client keeps connection settings and models in a separate native file pair; client path overrides and reversible writes follow [Cline paired files](clients/integrations.md#cline-paired-files).
+
+`claudeCode.stabilizePromptCache` is a default-off operator setting for
+[translated instruction stabilization](data-planes/inbound-compat.md#opt-in-claude-instruction-stabilization).
+Config JSON preserves the boolean; only literal true activates the role-changing transform.
+
+The lightweight top-level CLI help counts Cline CLI among the fifteen registered export clients; registry parity remains covered by the client help and integration tests.
diff --git a/structure/data-planes/images.md b/structure/data-planes/images.md
new file mode 100644
index 0000000000..25646c7de4
--- /dev/null
+++ b/structure/data-planes/images.md
@@ -0,0 +1,81 @@
+# Images Data Plane
+
+## Standalone Images
+
+Codex's local `image_gen.imagegen` tool makes a second Images request after the model calls it:
+`POST /v1/images/generations` for generation or `POST /v1/images/edits` for reference-image edits.
+These are standalone Images API routes, not the hosted Responses `image_generation` tool.
+
+`src/server/images.ts` uses the existing ChatGPT/OpenAI fallback unless `images.provider` explicitly
+selects a custom API-key `openai-responses` provider. Explicit selection fails closed when the
+provider is missing, disabled, registry-managed, incompatible, or lacks a usable key; it never
+falls through to another paid upstream. The relay accepts bounded JSON generation and edit requests,
+then forwards the decoded JSON without rewriting Codex's edit schema. Each paid Images POST receives
+one upstream attempt; client cancellation aborts the upstream and pool-only failures update the
+existing account-health state. Unknown Images subpaths still reach the JSON `/v1/*` 404 guard.
+
+When the OpenAI credential path is unavailable or its authentication fails, `generations` (not
+`edits`) may fall back to Google Antigravity if that provider is logged in. The fallback is
+credential-driven: it exists so an image request reaches a real upstream answer rather than dying on a
+local credential error, and it does not apply when the caller selected an explicit keyed custom
+provider, because a configured pool owns its own authentication failure rather than hiding it behind
+separately billed generation.
+
+On non-loopback binds, data-plane authentication and origin policy cover both Images routes. An
+explicit keyed Images provider accepts the proxy admission secret as either an OpenAI-style bearer
+or `x-opencodex-api-key` because the provider key replaces caller authorization before fetch. The
+ChatGPT forward path still requires the dedicated header so its upstream bearer remains distinct.
+The keyed path never enters `handleResponses`, so `src/server/images.ts` repeats
+`selectProactiveApiKeyTransport` inside the keyed branch and rebuilds Authorization from the
+returned clone rather than the earlier snapshot.
+
+The API-key `openai-responses` path also adapts Codex's private standalone image tool to the public
+Responses tool surface. A complete `image_gen` namespace is lowered to safe
+`image_gen__<inner-name>` function aliases even when no hosted image tool is present, because public
+Responses runtimes may reserve the namespace itself and reject dotted function names. Native and
+legacy dotted calls replayed in `body.input` are encoded to the same aliases. When any client
+image-gen declaration is replaced by a usable `image_gen__<inner-name>` alias, the adapter also drops
+hosted `image_generation` and deduplicates aliases in stable container order. Empty or malformed
+namespaces do not remove the hosted fallback. Discovery and normalization span both top-level
+`body.tools` and Codex Desktop Responses Lite `input[].type = "additional_tools"` containers.
+
+For a model explicitly listed in `modelPreferHostedTools`, a non-forward Responses provider may opt
+to remove colliding client `image_gen` declarations before this normalization and rewrite their
+selectors to hosted `image_generation`, so a provider-reserved hosted tool takes precedence without
+loosening a caller's tool-choice restriction. The opt-in is intentionally model-scoped: the default
+alias path remains safest for ordinary public Responses endpoints.
+
+For OpenAI API virtual `-pro` models, preference lookup checks the selected public ID first and
+uses the resolved base wire-model ID as a fallback. `modelAdapters` resolves the public ID first and
+the base ID second; the second pass selects the final adapter, and configuration validation mirrors
+both steps.
+
+Client-facing API-key responses perform the inverse mapping: JSON output and SSE function-call
+items restore `{ namespace: "image_gen", name: "<inner-name>" }` so Codex can dispatch the local
+extension. When item-id repair is also enabled, both transforms compose in one SSE parse/stringify
+pass (`src/server/sse-payload-rewrite.ts`) rather than chaining separate JS pull wrappers.
+Inspection and continuation-cache branches keep the raw upstream alias, allowing stored
+replays to return upstream without leaking a client-only namespace shape. The image-gen layer itself
+leaves malformed and empty image-gen namespaces untouched, but on a noncanonical route the general
+namespace boundary above runs after it and lowers whatever remains, so no private group reaches the
+wire. ChatGPT forward mode preserves the private namespace and hosted tool because that backend
+understands their native semantics.
+
+Per-model `modelReasoningSummaryDelivery` is a narrow compatibility layer for
+`openai-responses` gateways whose summary capability is real but whose accepted delivery enum
+differs from Codex. Presence advertises reasoning summaries in the routed catalog and rewrites only
+an already-present `stream_options.reasoning_summary_delivery` at the adapter boundary. It never
+injects summary generation into a request, and config validation rejects a delivery map that
+conflicts with `modelSupportsReasoningSummaries: false` for the same model.
+
+> Decision record: [ADR-0045](../decisions/ADR-0045-standalone-images.md)
+
+Chat helper admission in `src/server/responses/core.ts` follows the
+[deferred stored-main contract](../providers/openai-tiers.md): only a needed Direct OpenAI helper
+claims stored main, after terminal vision, routed vision and search exclusions.
+
+The management quota DTO keeps Combo editing aligned with scoped inference evidence;
+see [Combo editor routing quota](../gui-and-management-api.md#combo-editor-routing-quota).
+
+Claude replay carries [Go conversation affinity](inbound-compat.md#claude-affinity-at-final-go-dispatch)
+privately to final dispatch; preliminary route selection does not inject Go-only headers.
diff --git a/structure/data-planes/inbound-compat.md b/structure/data-planes/inbound-compat.md
new file mode 100644
index 0000000000..ee1e7b69c0
--- /dev/null
+++ b/structure/data-planes/inbound-compat.md
@@ -0,0 +1,139 @@
+# Inbound Compatibility Surfaces
+
+## Chat Completions inbound native path
+
+`POST /v1/chat/completions` sends eligible `openai-chat` routes directly to the provider's Chat
+Completions endpoint. Route selection reads the raw Chat body and the native request keeps that body
+as its wire source; a Responses projection is constructed only after the native route is declined
+and is never converted back into Chat. Request construction remains owned by `src/adapters/openai-chat.ts`, including model
+normalization, credential and provider headers, capability-specific fields, and the send URL: the
+canonical `openaiChatCompletionsUrl()` path, or `chatCompletionsPath` when the provider declares one.
+That field is the `openai-chat` mirror of `responsesPath` and exists because a per-model wire
+override swaps the adapter without touching `baseUrl`, so an upstream serving the two wires under
+different prefixes cannot be reached by the swap alone. The passthrough builder uses an explicit Chat-field whitelist so
+messages (including `name` and separate `system`/`developer` entries), Chat token controls,
+sampling/logprob fields, caller identity/metadata, and caller stream options retain their wire
+shape. For streams, caller `stream_options` are merged with mandatory `include_usage: true`. On
+the native passthrough there is no canonical Fast injection and no wire mapping: every caller
+`service_tier` — canonical or foreign — is forwarded raw and only under `chatServiceTier: true`,
+and `fastMode` injects nothing here. Resolved-Fast-policy injection applies only to routes that
+take the Chat -> Responses -> Chat bridge below. `parallel_tool_calls` is emitted only for providers opted into
+parallel tools (or pinned false by the existing provider opt-out contract).
+Combo/policy routes and requests that need Responses-only hosted tools, continuation, background,
+or storage semantics retain the existing Chat -> Responses -> Chat bridge.
+
+The direct SSE relay accepts CRLF and arbitrary transport chunk boundaries while retaining at most
+one bounded event. EOF with an unterminated event and an event above the translator limit are typed
+upstream failures, never successful partial completions. Provider-controlled structured error
+messages are redacted before either JSON or SSE reaches the client. The native path uses the same
+request-attempt logging, reset retry, same-key 429 replay, key rotation, usage extraction, and
+request-signal cancellation contracts as routed Responses transport. Because
+`src/server/chat-completions.ts` never enters Responses core,
+`src/server/chat-native.ts` repeats the pre-dispatch `selectProactiveApiKeyTransport`
+call before it binds the adapter; the pick remains inert unless a strategy is configured
+and the committed key is cooling. See [`responses.md`](../transports/responses.md).
+
+## Chat conversation identity forwarding
+
+`src/server/chat-completions.ts` preserves caller `prompt_cache_key` on the Chat-to-Responses
+bridge. Canonical ChatGPT Responses forwarding preserves `session_id`, `session-id`, `thread-id`
+and per-request `x-client-request-id` under their original names. Missing conversation identity
+stays missing; a shared prefix/cache key is not converted into a session. The direct-mode
+outbound contract is covered by `tests/responses/chat-conversation-affinity.test.ts`.
+This transport contract does not prove a client's emission, Pool selection stability or cache hits.
+
+## Chat streaming client with a JSON upstream result
+
+The translated inbound path in `src/server/chat-completions.ts` may receive a complete JSON
+Responses result even when the Chat client requested SSE. Its synthetic stream reuses
+`responsesJsonToChatCompletion` as the semantic authority: converted text, reasoning, available
+refusal content, tool calls, finish reason, and usage must survive this final delivery conversion.
+Tool calls gain their array-order stream `index`; the stream retains one assistant-role frame,
+one terminal choice, and one `[DONE]`. Both native and translated JSON fallbacks share
+`jsonCompletionSse`; its temporary frame strings and final body ownership are charged to the
+existing translator budget. Known incomplete limits take precedence over tool finish reasons;
+unmapped incomplete boundaries remain errors. The existing response-body lifecycle owns translation-budget
+release on consumption or cancellation. Actual upstream SSE and native Chat bypass this fallback.
+
+> Decision record: [ADR-0062](../decisions/ADR-0062-chat-streaming-client-with-a-json-upstream-resul.md)
+
+### Chat refusal projection
+
+`src/chat/outbound.ts` keeps Responses refusal parts separate from ordinary content. JSON output
+and the stream collector expose nullable `message.refusal`; `jsonCompletionSse` preserves it as
+`delta.refusal`, while the native SSE relay remains opaque. The translated live stream keys refusal
+state by raw `output_index` / `content_index`, validates present item IDs as correlation constraints,
+and emits buffered parts in that order only at a valid completed/incomplete terminal. Deltas append;
+equal, empty, absent, and shorter-prefix snapshots preserve existing text; extending snapshots add
+only new text. Non-string or contradictory snapshots fail with a content-free typed error.
+
+The existing turn budget accounts for refusal text and map metadata, including empty entries, and
+releases that state on terminal, failure, or cancellation. Pending role/tool/refusal/finish/`[DONE]`
+frames form one terminal batch: all serialized strings and encoded frames must be admitted before
+any batch frame is enqueued. Admission failure releases the batch and refusal state, cancels upstream,
+and emits only the bounded overflow error. Collector processing failures cancel their reader before
+releasing its lock, so upstream translation cannot continue after failed JSON collection. The outer
+response finalizer continues to own retained response bytes. These are projection rules, not new
+refusal policy or changes to ordinary content/tool semantics.
+
+## MiniMax Anthropic-compatible clients
+
+The MiniMax platform CLI's text resource posts Anthropic Messages to
+`/anthropic/v1/messages`. `ocx mmx` adapts that hard-coded client path with a temporary
+loopback bridge instead of adding another server route. The bridge accepts only POSTs to the
+messages and count-tokens paths, rewrites them to the existing `/v1/messages` data plane,
+preserves the query and streaming body, strips all incoming credential headers, and pins the
+public loopback placeholder. It stops as soon as the MMX child exits, so the server's
+`AUTH_MATRIX` and authentication surface remain unchanged.
+
+`ocx mmx` exposes only the text resource because the other MMX resources use MiniMax-specific
+image, video, speech, music, vision, search, quota and file endpoints. The launcher isolates
+`~/.mmx` credentials behind a temporary config, removes ambient proxy variables so loopback
+traffic cannot be sent off-machine, owns the temporary bridge lifecycle, and refuses
+destination, region and credential overrides. It is
+loopback-only because MMX cannot carry the dedicated remote-admission header. MiniMax Code uses
+the separate reversible `custom_provider.opencodex` file integration and is likewise
+loopback-only; its generated block never changes `defaultModel`. Each generated MCode model
+copies an authoritative catalog context window into `limit.context` and a nonempty canonical
+reasoning ladder into `thinking.effortOptions`. Missing capabilities stay absent instead of
+falling back to OpenCodex guesses, and the integration does not write the removed
+`thinking.effort` / `defaultEffort` fields because MCode owns the active effort per session.
+
+Chat helper admission in `src/server/responses/core.ts` follows the
+[deferred stored-main contract](../providers/openai-tiers.md): only a needed Direct OpenAI helper
+claims stored main, after terminal vision, routed vision and search exclusions.
+
+The management quota DTO keeps Combo editing aligned with scoped inference evidence;
+see [Combo editor routing quota](../gui-and-management-api.md#combo-editor-routing-quota).
+
+## Claude affinity at final Go dispatch
+
+`src/server/claude-messages.ts` carries validated conversation affinity privately through
+Responses options. Configured Go headers win; otherwise explicit session/thread identity,
+then an explicit Go header, then valid Claude metadata, then the original request-scoped
+allocation supplies the lane. `src/server/responses/core.ts` applies it only at the final
+canonical Go transport, including combo selection and failover. No Go-only replay header
+reaches non-Go destinations. Shared system cache keys never become conversation identity.
+The request-scoped fallback is stable across retries and distinct across client requests.
+
+Claude metadata also supplies a private native-session value. Only the final canonical ChatGPT
+attempt receives it, in copied forwarding headers; an explicit underscore session, hyphenated
+session or thread header suppresses synthesis. Refresh and alternate-account retries retain
+that value. Original request headers stay unchanged so policy fallback cannot promote a generated
+native identifier into a noncanonical replay. Go preliminary selection does not suppress the
+final native affinity, and shared-system keys do not provide either conversation value.
+
+## Opt-in Claude instruction stabilization
+
+`src/claude/inbound.ts` reads only literal `claudeCode.stabilizePromptCache: true` from
+its existing configuration argument. The default is off for every translated Messages caller.
+`src/claude/inbound-cache-stabilize.ts` relocates only exact single-line trailing unfenced harness notices
+into a trailing user input message; unmatched and fenced text is preserved, including an open
+fence through EOF. Native passthrough never enters this translator. Without opt-in the original
+system-parts cache-key derivation remains unchanged; with opt-in the metadata-less key uses
+stabilized instructions. Metadata-derived keys retain their existing derivation. This configuration
+changes prompt roles, not conversation identity, and cannot guarantee upstream cache reuse.
+
+Instruction notice extraction scans fence ranges once and walks original lines backwards with
+a decreasing cursor. It accepts exactly one ASCII space inside the token notice, preserves
+unmatched prefix bytes, and does not repeatedly scan or copy shrinking prompt prefixes.
diff --git a/structure/data-planes/search.md b/structure/data-planes/search.md
new file mode 100644
index 0000000000..de35b28ea9
--- /dev/null
+++ b/structure/data-planes/search.md
@@ -0,0 +1,19 @@
+# Search Data Plane
+
+## Standalone Search and exact account selectors
+
+`POST /v1/alpha/search` retains the selected model in its request body. When that value is an
+account-qualified native selector, the server resolves the public namespace, uses only the mapped
+stored Codex credential, and sends the bare native model upstream. That exact path is fail-closed:
+it does not consult Pool active state or affinity when selecting, and its outcomes cannot rotate
+the active Pool account. An account-wide credential failure still quarantines that credential and
+clears stale ordinary Pool affinities so they cannot reappear after reauthentication. Quota and
+transient outcomes from an exact request leave Pool affinities untouched. Ordinary search requests
+keep the normal Direct/Pool sidecar behavior.
+
+Standalone Images and Live requests currently carry neither the account-qualified model selector
+nor a trustworthy thread correlation from the Codex client. They therefore retain normal provider
+routing. Do not infer an exact account from caller-supplied account headers, process-global last
+selection, connection identity, or other ambient state; concurrent threads could cross-route
+credentials. Extending exact routing to those endpoints requires an opaque client correlation that
+can be bound server-side to a previously validated selector.
diff --git a/structure/decisions/ADR-0001-product-boundary.md b/structure/decisions/ADR-0001-product-boundary.md
new file mode 100644
index 0000000000..ade62886a4
--- /dev/null
+++ b/structure/decisions/ADR-0001-product-boundary.md
@@ -0,0 +1,12 @@
+# ADR-0001 — decision recorded under "Product boundary"
+
+- Contract owner: [overview.md](../overview.md#product-boundary)
+
+## Decision record
+
+- 목적과 의도: Add two widely used API-key providers through the canonical registry so CLI, GUI, login, routing, and documentation remain in parity.
+- 기존 구현 및 제약 조건: Tencent Coding Plan is OpenAI-compatible but contractually restricted to interactive coding tools and has a dynamic, text-only model set. SiliconFlow exposes a dynamic OpenAI-compatible catalog whose reasoning controls vary by model.
+- 검토한 주요 대안: Treat both as custom providers only; freeze a large SiliconFlow model list and reasoning map; expose Tencent without a usage warning.
+- 선택한 방식: Add registry-derived key presets, keep live discovery enabled, seed only Tencent's currently documented coding-plan models, and surface Tencent's usage restriction in both the preset note and public docs.
+- 다른 대안 대신 이 방식을 선택한 이유: Registry presets remove setup friction while live discovery avoids claiming that mutable catalogs are permanent. Avoiding speculative SiliconFlow reasoning metadata prevents invalid vendor-specific parameters.
+- 장점, 단점 및 영향: Both providers appear consistently across supported setup surfaces. Tencent users receive an explicit policy warning; SiliconFlow reasoning controls remain conservative until model-specific limits can be represented safely.
diff --git a/structure/decisions/ADR-0002-lifecycle.md b/structure/decisions/ADR-0002-lifecycle.md
new file mode 100644
index 0000000000..aab461c049
--- /dev/null
+++ b/structure/decisions/ADR-0002-lifecycle.md
@@ -0,0 +1,12 @@
+# ADR-0002 — decision recorded under "Lifecycle"
+
+- Contract owner: [runtime.md](../runtime.md#lifecycle)
+
+## Decision record
+
+- 목적과 의도: Give a headless hub a browser management ingress without widening its data plane or trusting spoofable forwarding headers on the public listener.
+- 기존 구현 및 제약 조건: `startServer` is synchronous through Lab activation, already owns an optional-listener transaction, and the service installer already has an owner-only token-file flow.
+- 검토한 주요 대안: Add management routes to the public listener; infer trusted ingress from `Host`/`Forwarded`/Tailscale headers; create a separate service manager; extend the existing composition root.
+- 선택한 방식: Bind a third socket exactly to `127.0.0.1`, select trust by receiving `Bun.serve` instance, keep a fixed route allowlist, and reuse the current launchd/systemd definitions.
+- 다른 대안 대신 이 방식을 선택한 이유: Headers do not prove which transport received a request, while a kernel loopback bind plus Tailscale Serve supplies a concrete ingress boundary without duplicating lifecycle or secret delivery.
+- 장점, 단점 및 영향: Public/default behavior stays unchanged and management can use Tailscale identity; operators must provide a co-located HTTPS frontend and pairing remains necessary for generic TLS proxies.
diff --git a/structure/decisions/ADR-0003-lifecycle.md b/structure/decisions/ADR-0003-lifecycle.md
new file mode 100644
index 0000000000..6ae9b51b9c
--- /dev/null
+++ b/structure/decisions/ADR-0003-lifecycle.md
@@ -0,0 +1,12 @@
+# ADR-0003 — decision recorded under "Lifecycle"
+
+- Contract owner: [runtime.md](../runtime.md#lifecycle)
+
+## Decision record
+
+- 목적과 의도: Separate proxy process ownership from persisted configuration without changing lifecycle behavior.
+- 기존 구현 및 제약 조건: `src/config.ts` mixed config transactions with cross-platform PID identity, runtime-port attestation, and stale-state cleanup; process writes still require the same config-home and atomic-write protections.
+- 검토한 주요 대안: Keep the mixed module; create a process-state module that imports `config.ts`; duplicate atomic writes inside the new module; split the minimal path and atomic-write foundations first.
+- 선택한 방식: `paths.ts` and `atomic-write.ts` are dependency leaves, `process-state.ts` depends only on those leaves, and `config.ts` remains a compatibility facade.
+- 다른 대안 대신 이 방식을 선택한 이유: Importing the facade would create a cycle, while duplicated writes could drift on ACL, symlink, residual-secret, and atomic-sequence behavior.
+- 장점, 단점 및 영향: Lifecycle callers have a narrow owner and behavior remains characterized; the temporary facade and three small config modules add files but preserve downstream imports.
diff --git a/structure/decisions/ADR-0004-lifecycle.md b/structure/decisions/ADR-0004-lifecycle.md
new file mode 100644
index 0000000000..8ddea07f23
--- /dev/null
+++ b/structure/decisions/ADR-0004-lifecycle.md
@@ -0,0 +1,12 @@
+# ADR-0004 — decision recorded under "Lifecycle"
+
+- Contract owner: [runtime.md](../runtime.md#lifecycle)
+
+## Decision record
+
+- 목적과 의도: Prevent repository dotenv data from becoming a durable executable or an OAuth-bearing Claude destination.
+- 기존 구현 및 제약 조건: Bun auto-loads project dotenv before OpenCodex TypeScript evaluates, while provider interpolation still depends on that behavior and cannot be disabled globally.
+- 검토한 주요 대안: Reject only relative Bun paths; disable Bun dotenv; trust a plain environment marker; capture provenance in the Node launcher and bind it to an argv proof.
+- 선택한 방식: The Node launcher selects Bun and snapshots Anthropic credential/destination slots before Bun starts. Durable runtime selection uses only the stamped current executable, while Claude accepts the snapshot only when its random argv proof matches.
+- 다른 대안 대신 이 방식을 선택한 이유: Absolute dotenv expansion bypasses a relative-path check, global dotenv removal breaks supported configuration, and an environment-only marker can itself come from dotenv.
+- 장점, 단점 및 영향: Normal npm launches preserve genuine shell overrides. Direct Bun or legacy launches have no provenance signal and fail closed for all three ambient Anthropic slots — credentials included, because subscription mode leaves `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` unset by design (#253) and a `settings.env` merge can still replace the destination after launch, so a preserved key would travel with it. The cost is that `bun src/cli/index.ts` loses ambient Anthropic values; the escape hatch is running through the published `ocx` bin, where genuine shell exports are preserved by proof. Durable artifacts use the running or bundled Bun.
diff --git a/structure/decisions/ADR-0005-codex-home.md b/structure/decisions/ADR-0005-codex-home.md
new file mode 100644
index 0000000000..2af6fd2cc2
--- /dev/null
+++ b/structure/decisions/ADR-0005-codex-home.md
@@ -0,0 +1,12 @@
+# ADR-0005 — decision recorded under "Codex home"
+
+- Contract owner: [codex-home.md](../codex-home.md#codex-home)
+
+## Decision record
+
+- 목적과 의도: Make the container's catalog location persistent and writable without changing native home semantics.
+- 기존 구현 및 제약 조건: Compose persisted only the OCX home, leaving Codex state on a read-only root; both products use incompatible auth.json formats.
+- 검토한 주요 대안: Merge the homes, nest Codex under an existing volume with a new startup initializer, or persist the existing separate Codex home.
+- 선택한 방식: Add a separate codex-state volume and create both owner-only directories in the image.
+- 다른 대안 대신 이 방식을 선택한 이유: It preserves existing paths, avoids credential-file collisions, and works when an older ocx-state volume hides the image's seeded directory tree.
+- 장점, 단점 및 영향: Two volumes must be backed up, but no automatic credential migration or runtime resolver change is needed. Catalog import/materialization remains an explicit prerequisite.
diff --git a/structure/decisions/ADR-0006-codex-home.md b/structure/decisions/ADR-0006-codex-home.md
new file mode 100644
index 0000000000..748fb322b4
--- /dev/null
+++ b/structure/decisions/ADR-0006-codex-home.md
@@ -0,0 +1,12 @@
+# ADR-0006 — decision recorded under "Codex home"
+
+- Contract owner: [codex-home.md](../codex-home.md#codex-home)
+
+## Decision record
+
+- 목적과 의도: Keep service ownership metadata aligned with the Codex home the proxy actually uses.
+- 기존 구현 및 제약 조건: The runtime performed narrow WSL Windows-home discovery, while service state used `CODEX_HOME || ~/.codex`.
+- 검토한 주요 대안: Bake `CODEX_HOME` into every service, migrate old state automatically, or reuse the runtime resolver.
+- 선택한 방식: Resolve service install and comparison state through the existing runtime Codex-home resolver.
+- 다른 대안 대신 이 방식을 선택한 이유: It preserves explicit overrides and the existing WSL ambiguity rules without rewriting user environment or foreign state.
+- 장점, 단점 및 영향: New installs and same-environment repairs agree with runtime targeting; genuinely foreign or ambiguous state remains fail-closed.
diff --git a/structure/decisions/ADR-0007-codex-home.md b/structure/decisions/ADR-0007-codex-home.md
new file mode 100644
index 0000000000..7da1c8244a
--- /dev/null
+++ b/structure/decisions/ADR-0007-codex-home.md
@@ -0,0 +1,12 @@
+# ADR-0007 — decision recorded under "Codex home"
+
+- Contract owner: [codex-home.md](../codex-home.md#codex-home)
+
+## Decision record
+
+- 목적과 의도: Make every history safety check and mutation address the SQLite database Codex actually opened.
+- 기존 구현 및 제약 조건: History code rebuilt `CODEX_HOME/state_5.sqlite`, while Codex supports a config or environment-selected SQLite root for split Windows/WSL layouts.
+- 검토한 주요 대안: Copy the database into CODEX_HOME, teach only the writer about the override, or centralize the call-time target.
+- 선택한 방식: Add one Codex-compatible SQLite resolver, fail closed when its authoritative config is unreadable or its present `sqlite_home` cannot be parsed as a non-empty string, and share it across history jobs, provider defaults, admission, and residue classification.
+- 다른 대안 대신 이 방식을 선택한 이유: A writer-only override would let ownership checks authorize one database while the mutation touched another.
+- 장점, 단점 및 영향: Split-home history remains correct and backup identities stay database-specific; storage cleanup of an external root remains out of scope.
diff --git a/structure/decisions/ADR-0008-codex-home.md b/structure/decisions/ADR-0008-codex-home.md
new file mode 100644
index 0000000000..a64ff2ccec
--- /dev/null
+++ b/structure/decisions/ADR-0008-codex-home.md
@@ -0,0 +1,12 @@
+# ADR-0008 — decision recorded under "Codex home"
+
+- Contract owner: [codex-home.md](../codex-home.md#codex-home)
+
+## Decision record
+
+- 목적과 의도: Keep zero-profile and zero-stage installations out of the native-profile transaction path without weakening staged-credential cleanup.
+- 기존 구현 및 제약 조건: Every live server swept stages at startup and every minute, and a failed sweep closed the global native-main gate even when no stage artifact existed.
+- 검토한 주요 대안: Disable native-main ownership entirely when the vault is empty, add a stale-lock deletion command, or skip only the stage sweep when both artifact paths are absent.
+- 선택한 방식: Preserve owner and claim protection, but bypass `sweepStages()` only after proving the registry and staging tree are both absent.
+- 다른 대안 대신 이 방식을 선택한 이유: Physical credential ownership remains cross-process safe, while an inert optional subsystem can no longer create the reported lock/recovery catch-22.
+- 장점, 단점 및 영향: Fresh installs avoid the SQLite profile lock; any present or uncertain stage state retains the existing locked fail-closed cleanup and recovery behavior.
diff --git a/structure/decisions/ADR-0009-codex-home.md b/structure/decisions/ADR-0009-codex-home.md
new file mode 100644
index 0000000000..3ef1eb69df
--- /dev/null
+++ b/structure/decisions/ADR-0009-codex-home.md
@@ -0,0 +1,12 @@
+# ADR-0009 — decision recorded under "Codex home"
+
+- Contract owner: [codex-home.md](../codex-home.md#codex-home)
+
+## Decision record
+
+- 목적과 의도: Recover a crashed zero-byte coordinator without mistaking SQLite's normal creation window for stale authority.
+- 기존 구현 및 제약 조건: Eligibility treated every existing pathname as coordinated, while initialization correctly refused a missing row over routed residue; catalog sync could therefore succeed before config injection failed permanently.
+- 검토한 주요 대안: Delete zero-byte files automatically, initialize a new row over residue, require a manual filesystem command, or add observe-only classification plus explicit guarded quarantine.
+- 선택한 방식: Treat only a settled, identity-stable, immutably verified zero-byte database like the existing legacy-uncoordinated boundary; keep fresh creators coordinated, diagnose all other database states immutably, and expose an opt-in zero-byte-only same-directory backup move with identity, ownership, sidecar, liveness, and SQLite-lock checks.
+- 다른 대안 대신 이 방식을 선택한 이유: Automatic deletion or adoption can race a live creator or erase transition evidence; a guarded backup preserves evidence and makes the operator action reproducible.
+- 장점, 단점 및 영향: A stale zero-byte file no longer wedges sync, valid/unrecognized databases remain fail-closed, and recovery requires the proxy to be stopped before `ocx sync` retries injection.
diff --git a/structure/decisions/ADR-0010-codex-home.md b/structure/decisions/ADR-0010-codex-home.md
new file mode 100644
index 0000000000..659feee442
--- /dev/null
+++ b/structure/decisions/ADR-0010-codex-home.md
@@ -0,0 +1,12 @@
+# ADR-0010 — decision recorded under "Codex home"
+
+- Contract owner: [codex-home.md](../codex-home.md#codex-home)
+
+## Decision record
+
+- 목적과 의도: Make multi-home injection truthful without taking ownership of user environment variables.
+- 기존 구현 및 제약 조건: CODEX_HOME is an intentional override, but Orca exports it for its own bundled runtime and the Windows app reads a different home.
+- 검토한 주요 대안: Rewrite CODEX_HOME automatically, warn for every custom home, or detect only the Orca-owned signature and report the target path.
+- 선택한 방식: Preserve the override, add a narrow Windows/Orca diagnostic, and qualify sync/restore success output with the effective home.
+- 다른 대안 대신 이 방식을 선택한 이유: It fixes the silent failure while avoiding destructive or noisy behavior for intentional custom homes.
+- 장점, 단점 및 영향: Orca users get an actionable warning; other multi-home products remain unchanged until they have an equally reliable signature.
diff --git a/structure/decisions/ADR-0011-codex-home.md b/structure/decisions/ADR-0011-codex-home.md
new file mode 100644
index 0000000000..447575066d
--- /dev/null
+++ b/structure/decisions/ADR-0011-codex-home.md
@@ -0,0 +1,12 @@
+# ADR-0011 — decision recorded under "Codex home"
+
+- Contract owner: [codex-home.md](../codex-home.md#codex-home)
+
+## Decision record
+
+- 목적과 의도: keep trusted Windows identity and process probes console-less without triggering Bun's direct PowerShell `-WindowStyle Hidden` failure.
+- 기존 구현 및 제약 조건: the calls already used `windowsHide: true` or a hidden VBS host, but redundantly passed PowerShell's window-style CLI option; the same option remains valid inside `Start-Process` and must not be removed there.
+- 검토한 주요 대안: decode the generic failure specially, retry after failure, remove all hidden-window controls, or remove only the redundant direct CLI pair.
+- 선택한 방식: retain trusted executable resolution, non-interactive flags, timeouts, and process-level hiding; remove `-WindowStyle Hidden` only from direct PowerShell argv.
+- 다른 대안 대신 이 방식을 선택한 이유: the command executes on affected Bun/Windows combinations, no console window is introduced, and working elevated/detached child-process behavior stays unchanged.
+- 장점, 단점 및 영향: SID, process-owner, tray, update, and sync probes share the compatible launch contract; a future call must use launcher-level hiding rather than reintroducing the PowerShell CLI pair.
diff --git a/structure/decisions/ADR-0012-codex-home.md b/structure/decisions/ADR-0012-codex-home.md
new file mode 100644
index 0000000000..1cedeb17dc
--- /dev/null
+++ b/structure/decisions/ADR-0012-codex-home.md
@@ -0,0 +1,12 @@
+# ADR-0012 — decision recorded under "Codex home"
+
+- Contract owner: [codex-home.md](../codex-home.md#codex-home)
+
+## Decision record
+
+- 목적과 의도: Preserve required Windows ACL hardening on the bundled Windows ARM64 runtime without weakening executable trust.
+- 기존 구현 및 제약 조건: The effective-SID query depended on the shared `GetSystemDirectoryW` FFI resolver; Bun 1.3.14 Windows ARM64 has no working `bun:ffi`, so config mutation reached `EACLIDENTITY` before PowerShell could start.
+- 검토한 주요 대안: Restore `USERDOMAIN\\USERNAME`; trust `SystemRoot`, `WINDIR`, or `PATH`; weaken required ACL writes; broaden the shared elevation resolver; or add a fixed-path fallback only for the non-elevated SID query.
+- 선택한 방식: Keep FFI authoritative, then allow only Windows ARM64 to use the existing default `C:\Windows\System32` PowerShell binary for the SID query when that exact file exists.
+- 다른 대안 대신 이 방식을 선택한 이유: Names and environment paths are caller-controlled, required secret writes must not silently skip ACLs, and elevation has a larger authority boundary that should remain FFI-only.
+- 장점, 단점 및 영향: Default Windows ARM64 installations can start and harden secrets; non-default Windows roots continue to fail closed until Bun exposes a trustworthy native system-directory API without FFI.
diff --git a/structure/decisions/ADR-0013-codex-home.md b/structure/decisions/ADR-0013-codex-home.md
new file mode 100644
index 0000000000..770d4c7d50
--- /dev/null
+++ b/structure/decisions/ADR-0013-codex-home.md
@@ -0,0 +1,12 @@
+# ADR-0013 — decision recorded under "Codex home"
+
+- Contract owner: [codex-home.md](../codex-home.md#codex-home)
+
+## Decision record
+
+- 목적과 의도: Bound the durable spill directory in aggregate so demoted continuation state cannot consume the host disk.
+- 기존 구현 및 제약 조건: The resident map has an unconditional byte cap and demotes past it, but the disk it demotes onto had only a per-file ceiling and the shared 1000-entry count cap. Retention itself worked — the hour-long TTL did evict — so the gap was a missing budget, not a leak.
+- 검토한 주요 대안: Lower the per-file ceiling; shorten the TTL; sweep the directory on a timer; add a configurable budget key; carry a running byte counter.
+- 선택한 방식: A constant aggregate ceiling checked at the end of the existing prune, evicting oldest-first, with the total recomputed per prune rather than carried as a counter.
+- 다른 대안 대신 이 방식을 선택한 이유: Per-file or TTL changes alter retention semantics other bounds depend on; a timer adds a second owner for eviction; a config key would surface a knob the sibling bounds (count, TTL, per-file) do not have; and a running counter could silently disable the cap if any of the several insertion paths missed an increment, where a walk over at most 1000 entries cannot drift.
+- 장점, 단점 및 영향: Disk use stops tracking client request rate. Ordinary traffic is unaffected because the count cap binds at a comparable point for median-sized payloads; a workload of unusually large continuations loses its oldest spills earlier than the TTL would, surfacing as the existing `previous_response_not_found` continuation miss.
diff --git a/structure/decisions/ADR-0014-codex-home.md b/structure/decisions/ADR-0014-codex-home.md
new file mode 100644
index 0000000000..6d55a28668
--- /dev/null
+++ b/structure/decisions/ADR-0014-codex-home.md
@@ -0,0 +1,12 @@
+# ADR-0014 — decision recorded under "Codex home"
+
+- Contract owner: [codex-home.md](../codex-home.md#codex-home)
+
+## Decision record
+
+- 목적과 의도: Bound disk and conversation-state retention after abrupt process termination.
+- 기존 구현 및 제약 조건: Ordinary write failures clean up immediately, but a killed process cannot run that path and Windows may temporarily lock files.
+- 검토한 주요 대안: Delete every `.tmp`, rely on manual cleanup, or recover only exact response-state remnants with age and PID guards.
+- 선택한 방식: Run a capped, best-effort, unlink-only sweep on lazy response-state startup.
+- 다른 대안 대신 이 방식을 선택한 이유: It repairs known remnants without broad authority over unrelated temp files or active writers.
+- 장점, 단점 및 영향: Old dead-PID files are reclaimed automatically; locked or conservatively classified files remain for a later retry.
diff --git a/structure/decisions/ADR-0015-codex-home.md b/structure/decisions/ADR-0015-codex-home.md
new file mode 100644
index 0000000000..85868fde79
--- /dev/null
+++ b/structure/decisions/ADR-0015-codex-home.md
@@ -0,0 +1,12 @@
+# ADR-0015 — decision recorded under "Codex home"
+
+- Contract owner: [codex-home.md](../codex-home.md#codex-home)
+
+## Decision record
+
+- 목적과 의도: Keep `/healthz` and unrelated requests responsive during intermittent Windows ACL stalls without publishing an unhardened continuation.
+- 기존 구현 및 제약 조건: Response demotion called the synchronous spill writer from request-time state mutations; `Bun.spawnSync(icacls)` could block the only Bun event loop for the full timeout and immediately replace replayable state with a tombstone.
+- 검토한 주요 대안: Increase the ACL timeout, weaken required ACL checks, publish before hardening, move every platform to async state mutation, or isolate only the Windows ACL-dependent publication boundary.
+- 선택한 방식: Preserve non-Windows behavior; serialize Windows publications through async ACL APIs, retain the exact resident generation until compare-before-swap succeeds, cap pending bytes, and retry one proven timeout.
+- 다른 대안 대신 이 방식을 선택한 이유: Longer waits worsen liveness, early publication weakens secret-file ACLs, and a cross-platform async rewrite would disturb mature immediate memory and crash-ordering contracts that do not cause this incident.
+- 장점, 단점 및 영향: Windows health stays schedulable and transient ACL stalls retain continuation replay; pending payloads can temporarily exceed the 64 MiB resident target but are pinned under a 256 MiB local ceiling and remain inside the documented 512 MiB process-owned worst case.
diff --git a/structure/decisions/ADR-0016-config-surface.md b/structure/decisions/ADR-0016-config-surface.md
new file mode 100644
index 0000000000..01d5359b5c
--- /dev/null
+++ b/structure/decisions/ADR-0016-config-surface.md
@@ -0,0 +1,12 @@
+# ADR-0016 — decision recorded under "Config surface"
+
+- Contract owner: [config.md](../config.md#config-surface)
+
+## Decision record
+
+- 목적과 의도: Make persisted config, path resolution, atomic file publication, and live process state distinct ownership boundaries.
+- 기존 구현 및 제약 조건: All four concerns lived in `src/config.ts`; process-state extraction could not safely import the facade without a cycle and could not copy the atomic writer without creating two security/correctness contracts.
+- 검토한 주요 대안: Keep one file, tolerate the cycle, duplicate only PID/runtime writes, or extract the minimal dependency leaves.
+- 선택한 방식: Preserve one implementation per concern under `src/config/` and keep facade re-exports for downstream compatibility.
+- 다른 대안 대신 이 방식을 선택한 이유: The dependency graph stays acyclic and every existing path, serialized shape, error, identity probe, and cleanup guard remains reusable from one owner.
+- 장점, 단점 및 영향: Internal lifecycle imports become narrow and testable; review must still treat changes to `atomic-write.ts` and `process-state.ts` as shared cross-platform runtime changes.
diff --git a/structure/decisions/ADR-0017-config-injection.md b/structure/decisions/ADR-0017-config-injection.md
new file mode 100644
index 0000000000..464e99ed5a
--- /dev/null
+++ b/structure/decisions/ADR-0017-config-injection.md
@@ -0,0 +1,12 @@
+# ADR-0017 — decision recorded under "Config injection"
+
+- Contract owner: [config.md](../config.md#config-injection)
+
+## Decision record
+
+- 목적과 의도: Keep strict-config diagnostics useful without interpreting instruction prose as TOML or exposing OS account names in shareable output.
+- 기존 구현 및 제약 조건: The diagnostic reader intentionally covers only Codex root keys and tables; a full TOML dependency is not otherwise required.
+- 검토한 주요 대안: Add a full TOML parser, scan raw lines for one legacy key, or preserve the lightweight parser with multiline lexical state.
+- 선택한 방식: Preserve the bounded reader, skip multiline string bodies before key/table matching, and redact paths only at the formatting boundary.
+- 다른 대안 대신 이 방식을 선택한 이유: All consumers keep one root/table interpretation while internal diagnostics retain actionable local paths.
+- 장점, 단점 및 영향: False positives and username disclosure are removed; unsupported exotic TOML syntax remains outside this diagnostic reader's contract.
diff --git a/structure/decisions/ADR-0018-config-injection.md b/structure/decisions/ADR-0018-config-injection.md
new file mode 100644
index 0000000000..379e91be51
--- /dev/null
+++ b/structure/decisions/ADR-0018-config-injection.md
@@ -0,0 +1,12 @@
+# ADR-0018 — decision recorded under "Config injection"
+
+- Contract owner: [config.md](../config.md#config-injection)
+
+## Decision record
+
+- 목적과 의도: Make restore and native-residue inspection accept and reject exactly the same versioned history provenance contract.
+- 기존 구현 및 제약 조건: Both modules independently checked version, database identity, entry ids, absolute rollout paths, provider/source tuples, and event markers; drift could make one module restore a manifest that the other refused to classify.
+- 검토한 주요 대안: Keep duplicate validators synchronized through review, import the mutation-heavy history provider into residue inspection, or extract a pure shared leaf.
+- 선택한 방식: Extract only types, path identity, filename id, provenance, and unknown-data validation; keep all filesystem, rollout, SQLite, retry, and mutation policy in the existing callers.
+- 다른 대안 대신 이 방식을 선택한 이유: A pure leaf removes schema drift without pulling write-side effects or database ownership into the read-only startup inspection graph.
+- 장점, 단점 및 영향: Format changes now have one validator and shared invalid fixtures; callers still intentionally own different user-facing failure mappings, so contract changes require updating both mappings and this document.
diff --git a/structure/decisions/ADR-0019-config-injection.md b/structure/decisions/ADR-0019-config-injection.md
new file mode 100644
index 0000000000..a72d7559e1
--- /dev/null
+++ b/structure/decisions/ADR-0019-config-injection.md
@@ -0,0 +1,12 @@
+# ADR-0019 — decision recorded under "Config injection"
+
+- Contract owner: [config.md](../config.md#config-injection)
+
+## Decision record
+
+- 목적과 의도: Prevent a refused Codex config injection from degrading a previously usable model catalog and make the refusal actionable from the CLI.
+- 기존 구현 및 제약 조건: Catalog discovery and replacement ran before injection, while the injector alone owned the authoritative TOML transforms and write-coordination eligibility checks.
+- 검토한 주요 대안: Roll back catalog and cache bytes after a later refusal, duplicate a partial TOML validator in the CLI, or run the injector's existing planning path without committing before discovery.
+- 선택한 방식: Add a non-writing mode to the injector and call it before catalog work; keep the normal injector call as the final under-lock authority check.
+- 다른 대안 대신 이 방식을 선택한 이유: Post-hoc rollback can overwrite a concurrent catalog writer, and a second validator would drift from the real refusal rules. Reusing the injector keeps one policy path and avoids compensating writes.
+- 장점, 단점 및 영향: Deterministic refusals preserve catalog/cache bytes and print their reason on stderr. A concurrent state change can still make the final injection refuse, but catalog and injection retain their existing independent revalidation and serialization boundaries.
diff --git a/structure/decisions/ADR-0020-provider-validation-ownership.md b/structure/decisions/ADR-0020-provider-validation-ownership.md
new file mode 100644
index 0000000000..d46b58c8ef
--- /dev/null
+++ b/structure/decisions/ADR-0020-provider-validation-ownership.md
@@ -0,0 +1,12 @@
+# ADR-0020 — decision recorded under "Provider validation ownership"
+
+- Contract owner: [config.md](../config.md#provider-validation-ownership)
+
+## Decision record
+
+- 목적과 의도: Separate reusable provider payload validation from config file persistence without changing accepted configuration or error behavior.
+- 기존 구현 및 제약 조건: The Zod schema, CLI, and management API shared helpers defined inside `src/config.ts`, so callers needing one pure check depended on the full persistence module.
+- 검토한 주요 대안: Keep validation in the persistence module; duplicate checks per caller; extract one leaf and retain compatibility re-exports.
+- 선택한 방식: Use one pure validation leaf, consume it from config refinement and direct DTO callers, and keep `src/config.ts` re-exports during migration.
+- 다른 대안 대신 이 방식을 선택한 이유: One implementation preserves load/write parity while reducing dependency breadth and avoiding a flag-day import rewrite.
+- 장점, 단점 및 영향: Validation can be characterized independently and config persistence becomes smaller; a temporary facade remains until all internal callers migrate.
diff --git a/structure/decisions/ADR-0021-shared-catalog.md b/structure/decisions/ADR-0021-shared-catalog.md
new file mode 100644
index 0000000000..ddeb8d1feb
--- /dev/null
+++ b/structure/decisions/ADR-0021-shared-catalog.md
@@ -0,0 +1,12 @@
+# ADR-0021 — decision recorded under "Shared catalog"
+
+- Contract owner: [catalog.md](../catalog.md#shared-catalog)
+
+## Decision record
+
+- 목적과 의도: Prevent Windows PowerShell/CIM process discovery from blocking Bun's event loop while v2 sub-agent guidance is assembled.
+- 기존 구현 및 제약 조건: The stale-catalog check is advisory on the request path, but CLI/service lifecycle operations use the same process evidence before warning or terminating narrowly matched app-servers.
+- 검토한 주요 대안: Remove stale-catalog guidance, move every platform collector into workers, or isolate only the Windows request path behind asynchronous child processes.
+- 선택한 방식: Keep the synchronous fail-closed collector for explicit lifecycle operations; v2 requests use asynchronous trusted-System32 PowerShell, one identity-scoped in-flight refresh, and the existing short cache. Cache invalidation advances a generation so a pre-write CIM result cannot repopulate post-write state.
+- 다른 대안 대신 이 방식을 선택한 이유: This preserves process ownership and matching invariants while preventing a slow CIM query from starving `/healthz` and unrelated proxy traffic.
+- 장점, 단점 및 영향: Concurrent v2 turns do not multiply CIM walks and the event loop remains responsive. A cold request can still await the bounded advisory check, and collection failure suppresses OpenCodex-authored model guidance as `unknown`.
diff --git a/structure/decisions/ADR-0022-routed-tool-discovery-and-hosted-search.md b/structure/decisions/ADR-0022-routed-tool-discovery-and-hosted-search.md
new file mode 100644
index 0000000000..8c3a4984ac
--- /dev/null
+++ b/structure/decisions/ADR-0022-routed-tool-discovery-and-hosted-search.md
@@ -0,0 +1,12 @@
+# ADR-0022 — decision recorded under "Routed tool discovery and hosted search"
+
+- Contract owner: [catalog.md](../catalog.md#routed-tool-discovery-and-hosted-search)
+
+## Decision record
+
+- 목적과 의도: keep routed plugin/MCP tools reachable without paying the full-catalog turn-1 payload tax or starving Cursor's unified execution bridge.
+- 기존 구현 및 제약 조건: #1596 restored deferred discovery only for non-Cursor rows because Cursor bypasses the hosted-search sidecar; codex-rs treats deferred exposure and hosted search as separate capabilities, and Cursor independently enforces a 120,000-byte serialized tool-catalog limit.
+- 검토한 주요 대안: keep Cursor opted out, raise/disable Cursor's transport ceiling, synthesize another execution bridge, or enable Cursor-native local exec only when the bridge disappears.
+- 선택한 방식: enable Codex deferred exposure for Cursor code-mode rows too, while continuing to omit Cursor's hosted `web_search_tool_type`.
+- 다른 대안 대신 이 방식을 선택한 이유: it removes the known exec-description inflation before Cursor budgeting without weakening the measured transport limit, inventing caller tools, or turning bridge absence into local-execution authority.
+- 장점, 단점 및 영향: Cursor keeps a compact Responses-owned `exec` path under rich tool catalogs and hosted-search behavior remains unchanged; the existing Cursor budget and native-local-exec fail-closed policy remain authoritative.
diff --git a/structure/decisions/ADR-0023-ultra-reasoning-level.md b/structure/decisions/ADR-0023-ultra-reasoning-level.md
new file mode 100644
index 0000000000..c6fddcb6c8
--- /dev/null
+++ b/structure/decisions/ADR-0023-ultra-reasoning-level.md
@@ -0,0 +1,19 @@
+# ADR-0023 — decision recorded under "Ultra reasoning level"
+
+- Contract owner: [catalog.md](../catalog.md#ultra-reasoning-level)
+
+## Decision record
+
+- 목적과 의도: Xiaomi MiMo의 공식 OpenAI Chat endpoint가 실제로 받지 않는 `max`/
+  `ultra` reasoning tier를 catalog에 노출하지 않도록 한다.
+- 기존 구현 및 제약 조건: `xiaomi`는 Anthropic endpoint, `mimo`는 token-plan endpoint를
+  소유하며, 공식 `https://api.xiaomimimo.com/v1`은 generic custom provider로 처리됐다.
+- 검토한 주요 대안: 기존 `xiaomi`/`mimo` contract를 확장하기, 모든 custom provider의 ladder를
+  일괄 축소하기, 공식 public endpoint만을 별도 registry row로 소유하기.
+- 선택한 방식: `xiaomi-mimo`를 고정 목적지의 `openai-chat` preset으로 등록하고
+  `low`/`medium`/`high`만 노출하며 높은 direct request는 `high`로 clamp한다.
+- 다른 대안 대신 이 방식을 선택한 이유: 서로 다른 auth/wire/host를 하나의 preset으로
+  합치지 않으면서 upstream error로 확인된 계약만 적용할 수 있다.
+- 장점, 단점 및 영향: 공식 endpoint에서 안전한 picker/wire 계약을 제공하고,
+  `preserveCustomDestination`으로 같은 이름의 다른 host/key를 보호한다. 대신 새 preset 표면을
+  문서와 registry parity에서 함께 유지해야 한다.
diff --git a/structure/decisions/ADR-0024-ultra-reasoning-level.md b/structure/decisions/ADR-0024-ultra-reasoning-level.md
new file mode 100644
index 0000000000..0577753a32
--- /dev/null
+++ b/structure/decisions/ADR-0024-ultra-reasoning-level.md
@@ -0,0 +1,19 @@
+# ADR-0024 — decision recorded under "Ultra reasoning level"
+
+- Contract owner: [catalog.md](../catalog.md#ultra-reasoning-level)
+
+## Decision record
+
+- 목적과 의도: Xiaomi token-plan에서 image input을 거부하는 `mimo-v2.5-pro`만 vision
+  sidecar로 우회하고, 실제 image input을 받는 `mimo-v2.5`는 native vision 경로에 남긴다.
+- 기존 구현 및 제약 조건: upstream `/v1/models`는 input modality를 제공하지 않으며,
+  `noVisionModels`는 text-only 모델을 sidecar로 보내면서 Codex catalog에는 image input을
+  광고하는 provider-scoped 계약이다.
+- 검토한 주요 대안: MiMo 전체를 text-only로 분류하기, live discovery에서 modality를
+  추측하기, `mimo-v2.5-pro` 하나만 registry에 고정 분류하기.
+- 선택한 방식: canonical `mimo` preset의 `noVisionModels`에 `mimo-v2.5-pro`만 추가한다.
+- 다른 대안 대신 이 방식을 선택한 이유: live endpoint 검증으로 확인된 최소 범위만
+  적용하며, 정상 동작하는 `mimo-v2.5`의 native image 경로를 훼손하지 않는다.
+- 장점, 단점 및 영향: Pro image 요청의 404를 sidecar 설명 경로로 바꾸고 base 모델은
+  그대로 유지한다. `preserveCustomDestination` guard 때문에 같은 provider id를 다른 host에
+  연결한 사용자 설정에는 이 capability 분류가 전파되지 않는다.
diff --git a/structure/decisions/ADR-0025-ultra-reasoning-level.md b/structure/decisions/ADR-0025-ultra-reasoning-level.md
new file mode 100644
index 0000000000..65683e224e
--- /dev/null
+++ b/structure/decisions/ADR-0025-ultra-reasoning-level.md
@@ -0,0 +1,19 @@
+# ADR-0025 — decision recorded under "Ultra reasoning level"
+
+- Contract owner: [catalog.md](../catalog.md#ultra-reasoning-level)
+
+## Decision record
+
+- 목적과 의도: GitHub Copilot의 live model catalog가 명시하는 모델별 image-input 지원을
+  Codex catalog에 정확히 보존한다.
+- 기존 구현 및 제약 조건: 공용 discovery parser는 직접 `capabilities.vision`과 표준 modality
+  필드는 읽었지만 Copilot의 `capabilities.supports.vision` 중첩 boolean은 읽지 않아 모든
+  Copilot 모델이 text-only fallback으로 축소되었다.
+- 검토한 주요 대안: 모든 Copilot 모델에 정적 vision seed를 추가하기, 모델 이름을 외부
+  metadata alias에 연결하기, live 모델별 boolean을 공용 parser에서 해석하기.
+- 선택한 방식: 직접 vision boolean이 없을 때만 중첩 `supports.vision`의 명시적 boolean을
+  사용하고, `false`도 보존하며 malformed 값은 추론하지 않는다.
+- 다른 대안 대신 이 방식을 선택한 이유: live 응답이 모델별 capability의 가장 좁은 근거라서
+  새 모델에도 적용되며 text-only 모델을 image-capable로 과장하지 않는다.
+- 장점, 단점 및 영향: Copilot vision 모델은 image attachment를 받을 수 있고 명시적 text-only
+  모델은 계속 차단된다. Capability를 제공하지 않는 모델은 기존 fallback을 유지한다.
diff --git a/structure/decisions/ADR-0026-ultra-reasoning-level.md b/structure/decisions/ADR-0026-ultra-reasoning-level.md
new file mode 100644
index 0000000000..7b7829aebe
--- /dev/null
+++ b/structure/decisions/ADR-0026-ultra-reasoning-level.md
@@ -0,0 +1,21 @@
+# ADR-0026 — decision recorded under "Ultra reasoning level"
+
+- Contract owner: [catalog.md](../catalog.md#ultra-reasoning-level)
+
+## Decision record
+
+- 목적과 의도: bare `defaultModel` selectors that route into third-party providers must keep their
+  adapter-owned effort ladder; only true ChatGPT-native requests should receive the mock-max repair.
+- 기존 구현 및 제약 조건: `nativeEffortClamp` already needed the original request id because
+  routing strips `provider/`, but bare third-party selectors like `glm-5.2-fast-preview` still look
+  native after that strip.
+- 검토한 주요 대안: (1) infer nativeness from the bare slug prefix alone, (2) gate clamping by the
+  resolved provider identity, (3) disable the clamp for all off-snapshot slugs.
+- 선택한 방식: request-time clamp entry is allowed only when the resolved route is the canonical
+  built-in OpenAI/Codex forward provider and the original request id is still bare.
+- 다른 대안 대신 이 방식을 선택한 이유: provider identity is the only durable signal that
+  distinguishes true native ChatGPT traffic from third-party `defaultModel` routes when both share a
+  bare model id shape.
+- 장점, 단점 및 영향: preserves `gpt-5.5 max -> xhigh` repair for native traffic, removes false
+  clamps for bare routed models, and keeps adapter-specific effort mapping as the single source of
+  truth for third-party providers.
diff --git a/structure/decisions/ADR-0027-subagents.md b/structure/decisions/ADR-0027-subagents.md
new file mode 100644
index 0000000000..a915436ce1
--- /dev/null
+++ b/structure/decisions/ADR-0027-subagents.md
@@ -0,0 +1,24 @@
+# ADR-0027 — decision recorded under "Subagents"
+
+- Contract owner: [subagents.md](../subagents.md#subagents)
+
+## Decision record
+
+- 목적과 의도: keep generated Claude Code `ocx-*.md` roster files synchronized when the proxy is
+  started or ensured on Linux, Windows, and macOS, including background service restarts.
+- 기존 구현 및 제약 조건: explicit `ocx claude` launches and Management API writes reconciled the
+  files, while the startup call inside `injectSystemEnv` ran only on macOS with system-env enabled.
+  `startServer` is also used as an in-process library/test primitive and cannot safely mutate the
+  real user home on every invocation.
+- 검토한 주요 대안: write from `startServer`; duplicate hooks in each OS service manager; reconcile
+  once from the owning CLI lifecycle after the listener becomes available.
+- 선택한 방식: the foreground/service start and live-proxy ensure paths call one best-effort helper
+  after bind, using the live Management API context-window map and the existing marker-verified
+  atomic roster writer. macOS system-env startup keeps its existing shared-window sync and skips the
+  duplicate call.
+- 다른 대안 대신 이 방식을 선택한 이유: it covers every supported service entrypoint without
+  adding home-directory side effects to server-library consumers or creating a second roster format.
+- 장점, 단점 및 영향: stale OpenCodex-owned definitions converge on every daemon start, disabled integration
+  prunes them without provider discovery, and catalog failure falls back to unmarked definitions so
+  startup remains available. A later dashboard save or `ocx claude` launch restores missing context
+  markers after a transient failure.
diff --git a/structure/decisions/ADR-0028-background-service-command-selection.md b/structure/decisions/ADR-0028-background-service-command-selection.md
new file mode 100644
index 0000000000..fca08d8238
--- /dev/null
+++ b/structure/decisions/ADR-0028-background-service-command-selection.md
@@ -0,0 +1,12 @@
+# ADR-0028 — decision recorded under "Background service command selection"
+
+- Contract owner: [ops/service-and-sidecars.md](../ops/service-and-sidecars.md#background-service-command-selection)
+
+## Decision record
+
+- 목적과 의도: Make a bare service refresh safe and idempotent without converting a localized or transient Windows status failure into an elevated re-registration.
+- 기존 구현 및 제약 조건: The command defaulted to install and later used a boolean diagnostic whose scheduler query fallback could collapse unknown into absent; repair must preserve the existing Windows launcher and Bun stability workarounds.
+- 검토한 주요 대안: Always repair; keep a boolean installed check; infer presence from saved state alone; use a tri-state live registration probe.
+- 선택한 방식: Validate arguments first, then use a narrow tri-state platform probe only for a bare backend-neutral invocation; route installed to repair, absent to install, and unknown to a refusal.
+- 다른 대안 대신 이 방식을 선택한 이유: Saved state can be stale and unconditional repair breaks first install, while a boolean cannot represent the exact uncertainty that must fail closed.
+- 장점, 단점 및 영향: Healthy existing services avoid UAC and registration churn; stale Windows scheduler definitions may be refreshed and require elevation. Invalid input performs no status I/O, and uncertain Windows hosts require one explicit status/installation decision instead of risking a destructive guess.
diff --git a/structure/decisions/ADR-0029-windows-startup-ownership-listing-reuse.md b/structure/decisions/ADR-0029-windows-startup-ownership-listing-reuse.md
new file mode 100644
index 0000000000..4281ffdffd
--- /dev/null
+++ b/structure/decisions/ADR-0029-windows-startup-ownership-listing-reuse.md
@@ -0,0 +1,12 @@
+# ADR-0029 — decision recorded under "Windows startup ownership listing reuse"
+
+- Contract owner: [ops/service-and-sidecars.md](../ops/service-and-sidecars.md#windows-startup-ownership-listing-reuse)
+
+## Decision record
+
+- 목적과 의도: Preserve the race-sensitive Windows ownership recheck while paying for an unchanged locale-neutral full task listing only once during synchronous startup.
+- 기존 구현 및 제약 조건: Localized `schtasks /query /tn ... /xml` failures need a full listing to prove absence, the listing may legitimately take more than two seconds, and `unknown` must never become `absent` merely to reduce latency.
+- 검토한 주요 대안: Delete the second ownership check; lower the listing timeout; keep a process-wide or TTL cache; reuse an earlier absence regardless of the fresh targeted result; or scope a memo to the two pre-listen checks and key it to the complete targeted result.
+- 선택한 방식: Create one cache inside `startServer`, run every targeted query, and reuse its listing result only when status, timeout/spawn flags, stdout, and stderr are byte-identical. Runtime ownership retries do not receive the startup cache.
+- 다른 대안 대신 이 방식을 선택한 이유: Removing or weakening revalidation widens the install race, while a global/TTL cache can outlive startup and stale absence can authorize the wrong home. Exact targeted-result identity lets the ordinary no-task locale fallback coalesce without hiding changed evidence.
+- 장점, 단점 및 영향: The reported stable zh-CN absence path performs two cheap targeted queries and one full listing. A task that appears is detected by the second targeted query; changed or failed evidence triggers a fresh fail-closed decision, so unusual churn may still pay for two listings rather than guess.
diff --git a/structure/decisions/ADR-0030-stable-service-launcher-launchd-and-systemd.md b/structure/decisions/ADR-0030-stable-service-launcher-launchd-and-systemd.md
new file mode 100644
index 0000000000..60bf5fa0b5
--- /dev/null
+++ b/structure/decisions/ADR-0030-stable-service-launcher-launchd-and-systemd.md
@@ -0,0 +1,12 @@
+# ADR-0030 — decision recorded under "Stable service launcher (launchd and systemd)"
+
+- Contract owner: [ops/service-and-sidecars.md](../ops/service-and-sidecars.md#stable-service-launcher-launchd-and-systemd)
+
+## Decision record
+
+- 목적과 의도: Keep systemd services upgrade-stable without losing an explicitly trusted Bun override or accepting a non-executable PATH placeholder.
+- 기존 구현 및 제약 조건: Version managers replace package trees but retain lexical shims; Bun dotenv makes ambient override values untrustworthy unless the Node launcher already stamped matching runtime provenance.
+- 검토한 주요 대안: Bake the package Bun and CLI forever; resolve the shim target; accept the first existing PATH entry; drop every runtime override in launcher mode; or preserve only a proof-bound override.
+- 선택한 방식: Require a regular executable lexical launcher, resolve it once during installation, preserve only `durableBunRuntime().source === "override"`, and keep token loading in the existing file-backed shell preamble.
+- 다른 대안 대신 이 방식을 선택한 이유: Resolving or pinning package paths recreates upgrade restart loops, existence-only selection can name a directory or non-executable file, and dropping a trusted override silently changes an operator's runtime.
+- 장점, 단점 및 영향: Mise/asdf-style upgrades keep working and explicit Bun selection survives; source installs still use the direct pair, while a removed or non-executable launcher requires `ocx service repair`.
diff --git a/structure/decisions/ADR-0031-responses-http-sse.md b/structure/decisions/ADR-0031-responses-http-sse.md
new file mode 100644
index 0000000000..765cf9e447
--- /dev/null
+++ b/structure/decisions/ADR-0031-responses-http-sse.md
@@ -0,0 +1,12 @@
+# ADR-0031 — decision recorded under "Responses HTTP/SSE"
+
+- Contract owner: [transports/responses.md](../transports/responses.md#responses-httpsse)
+
+## Decision record
+
+- 목적과 의도: Keep long but progressing client-driven tool continuations valid while locating repository-semantic loop detection at the layer that owns the workspace and continuation policy.
+- 기존 구현 및 제약 조건: Issue #2600 recorded 18 persisted Cursor continuations whose transcript and tool counters grew while the worktree did not. Every proxy-local liveness and capacity bound was therefore satisfied, but the proxy had no workspace delta to compare.
+- 검토한 주요 대안: Stop after a fixed continuation count; classify read-like tool names as no progress; compare assistant prose; emit a new proxy-only terminal code after a time budget; or leave semantic progress to the client while preserving transport cancellation for objective proxy failures.
+- 선택한 방식: Do not add a proxy semantic cutoff without a client-supplied progress contract. Keep objective transport, byte, concurrency, and silence bounds typed and cancellable; require the workspace-owning client to bound repeated continuations using repository state plus its own side-effect ledger.
+- 다른 대안 대신 이 방식을 선택한 이유: Calls and prose are not a repository oracle, and tool names do not prove side effects. A proxy cutoff would either miss the reported loop because items kept changing or terminate legitimate slow work. Retrying after the cutoff could also replay side-effecting work.
+- 장점, 단점 및 영향: OpenCodex does not manufacture a root cause or silently terminate healthy long turns. The combined route still needs a client-side semantic boundary; if a future client sends an explicit privacy-safe progress marker, the proxy may enforce that contract without inferring workspace state.
diff --git a/structure/decisions/ADR-0032-responses-http-sse.md b/structure/decisions/ADR-0032-responses-http-sse.md
new file mode 100644
index 0000000000..e7368e5f0e
--- /dev/null
+++ b/structure/decisions/ADR-0032-responses-http-sse.md
@@ -0,0 +1,12 @@
+# ADR-0032 — decision recorded under "Responses HTTP/SSE"
+
+- Contract owner: [transports/responses.md](../transports/responses.md#responses-httpsse)
+
+## Decision record
+
+- 목적과 의도: Keep transport helpers reusable without making every consumer evaluate the full routed Responses and sidecar graph at module load.
+- 기존 구현 및 제약 조건: The original `responses.ts` split copied the monolith import header into `fetch-helpers.ts`; seven helper exports therefore retained 39 distinct runtime import specifiers and reached 326 modules even though the implementations used only three runtime dependencies.
+- 검토한 주요 대안: Leave the imports because current modules have limited top-level side effects; move the helpers again; prune the copied imports and lock the direct runtime boundary.
+- 선택한 방식: Preserve the file and all public exports, remove unused runtime edges, and enforce an explicit three-specifier allowlist with a source-level regression that also proves type-only imports are ignored.
+- 다른 대안 대신 이 방식을 선택한 이유: Relying on unrelated modules to remain side-effect-free makes startup ownership accidental, while another move adds churn without changing the responsibility boundary.
+- 장점, 단점 및 영향: Ordinary native Chat and compact consumers no longer load unrelated routing, combo, OAuth, web-search, vision, and relay modules through this leaf. The allowlist is intentionally strict, so a future helper that needs a new runtime dependency must make that ownership decision explicit in code, tests, and this document.
diff --git a/structure/decisions/ADR-0033-responses-http-sse.md b/structure/decisions/ADR-0033-responses-http-sse.md
new file mode 100644
index 0000000000..ae6c83a00f
--- /dev/null
+++ b/structure/decisions/ADR-0033-responses-http-sse.md
@@ -0,0 +1,13 @@
+# ADR-0033 — decision recorded under "Responses HTTP/SSE"
+
+- Contract owner: [transports/responses.md](../transports/responses.md#responses-httpsse)
+
+## Decision record
+
+- 목적과 의도: Prevent routed models from turning invented or neighboring-agent tool names into client-executable Responses calls.
+- 기존 구현 및 제약 조건: The request catalog already controlled custom-tool restoration and the non-OpenAI prompt nudge, but an undeclared upstream name still fell through as an ordinary `function_call`; Codex then reduced the mismatch to a bare `aborted` result.
+- 검토한 주요 대안: Rely only on prompt guidance; automatically translate undeclared `apply_patch` into Code Mode; validate returned names against the request-visible catalog at the final bridge.
+- 선택한 방식: Retain the allowed wire-name set with the existing bridge maps and fail the turn with an explicit compatibility error before emitting any undeclared tool item.
+- 보완된 경계: Key-auth Responses passthrough restores a routed custom call only when the adapter actually lowered that name after request normalization and the caller's `tool_choice` still authorizes it. Native `apply_patch` stays in its upstream function-call form unless the destination explicitly denies Responses custom tools; tools replaced by hosted-provider policy also stay in their upstream function-call form.
+- 다른 대안 대신 이 방식을 선택한 이유: Model guidance is not an enforcement boundary, while automatic translation would invent executable caller intent and arguments after generation.
+- 장점, 단점 및 영향: Streaming and non-streaming routed responses now fail closed with an actionable provider-contract error; providers that emit aliases they never advertised must correct their adapter mapping instead of relying on client abort behavior.
diff --git a/structure/decisions/ADR-0034-responses-http-sse.md b/structure/decisions/ADR-0034-responses-http-sse.md
new file mode 100644
index 0000000000..78d6e9a7fe
--- /dev/null
+++ b/structure/decisions/ADR-0034-responses-http-sse.md
@@ -0,0 +1,12 @@
+# ADR-0034 — decision recorded under "Responses HTTP/SSE"
+
+- Contract owner: [transports/responses.md](../transports/responses.md#responses-httpsse)
+
+## Decision record
+
+- 목적과 의도: Accept a routed model's decorated outer `apply_patch` delimiter lines without changing the executable meaning of any provider-returned program.
+- 기존 구현 및 제약 조건: Routed custom tools arrive through a public function wrapper and are restored at the response boundary, but arbitrary `exec` JavaScript is caller-executable source whose strings, comments, templates, and helper arguments cannot be safely rewritten with text patterns.
+- 검토한 주요 대안: Regex-rewrite nested helper calls in `exec`; wrap a raw `exec` patch body as a helper call; reject every decorated patch; or normalize only the outer lines of a complete top-level `apply_patch` custom-tool payload.
+- 선택한 방식: After unwrapping the request-authorized custom-tool function shape, normalize only exact decorated Begin/End lines when the entire `apply_patch` input is one structurally recognizable patch with a file operation. Keep `exec` and all other freeform bodies byte-identical.
+- 다른 대안 대신 이 방식을 선택한 이유: A top-level `apply_patch` call already carries explicit executable intent, so its unambiguous outer-line spelling can be repaired without inventing a call or parsing JavaScript. Every broader rewrite could reinterpret ordinary data as code.
+- 장점, 단점 및 영향: Decorated top-level patches regain compatibility while strings, comments, generated source, raw `exec` text, incomplete envelopes, and patch-file content remain untouched. Nested malformed helper source must be corrected by the provider instead of being guessed at the response boundary.
diff --git a/structure/decisions/ADR-0035-responses-http-sse.md b/structure/decisions/ADR-0035-responses-http-sse.md
new file mode 100644
index 0000000000..a1cfd0ceea
--- /dev/null
+++ b/structure/decisions/ADR-0035-responses-http-sse.md
@@ -0,0 +1,12 @@
+# ADR-0035 — decision recorded under "Responses HTTP/SSE"
+
+- Contract owner: [transports/responses.md](../transports/responses.md#responses-httpsse)
+
+## Decision record
+
+- 목적과 의도: Stop wasting a turn when a routed model submits one complete patch envelope as the entire code-mode `exec` body.
+- 기존 구현 및 제약 조건: The decision above rejected "wrap a raw `exec` patch body as a helper call" because a text rewrite could reinterpret data as code. Rollout evidence then showed about 55 such bodies across four models, each a guaranteed isolate throw. Measurement added the missing fact: a complete envelope is never valid JavaScript, since `*** Begin Patch` fails to parse at the leading `**`.
+- 검토한 주요 대안: Keep failing closed; rewrite decorated delimiters inside `exec` JavaScript; parse `exec` bodies as JavaScript; or retarget only a body that is itself one complete operation-bearing envelope.
+- 선택한 방식: Retarget only that complete-envelope shape to the existing apply_patch helper, through one shared resolver used by all four restore paths. Delimiter-repair functions stay unchanged and every other `exec` body, including JavaScript that mentions an envelope, stays byte-identical. Streaming holds a buffer that could still become an envelope so the live preview is never rewound.
+- 다른 대안 대신 이 방식을 선택한 이유: This narrows the earlier rejection rather than reversing it. The rejection protected bodies with a competing executable reading; a complete envelope has none, so it is the same one-faithful-reading rule the delimiter repair already follows. Rewriting inside JavaScript remains rejected: there the marker is a delimiter or a string or a comment, and no lexical or parse-based rule separates them safely.
+- 장점, 단점 및 영향: A previously wasted turn now performs the edit the model intended. This does convert a hard failure into a real filesystem write, so the predicate stays anchored and operation-bearing; prefixed, suffixed, incomplete, namespaced, and JavaScript bodies still fail closed. The write itself is the same `apply_patch` capability code mode already grants, reached by payload shape instead of tool name.
diff --git a/structure/decisions/ADR-0036-responses-http-sse.md b/structure/decisions/ADR-0036-responses-http-sse.md
new file mode 100644
index 0000000000..fef122d5cd
--- /dev/null
+++ b/structure/decisions/ADR-0036-responses-http-sse.md
@@ -0,0 +1,12 @@
+# ADR-0036 — decision recorded under "Responses HTTP/SSE"
+
+- Contract owner: [transports/responses.md](../transports/responses.md#responses-httpsse)
+
+## Decision record
+
+- 목적과 의도: Keep Codex client-side deferred tool discovery usable through third-party Responses-compatible gateways that implement public function tools but reject the private `tool_search` declaration.
+- 기존 구현 및 제약 조건: The chat translation path already exposed search as a function and bridged its call back to `tool_search_call`; passthrough only promoted definitions returned by an earlier search, so it could not initiate discovery on a strict third-party Responses endpoint.
+- 검토한 주요 대안: Require every gateway to implement Codex-private tool types; route affected models through `openai-chat`; lower the declaration only; lower the noncanonical request and restore both JSON and SSE response lifecycles.
+- 선택한 방식: On noncanonical Responses passthrough only, lower an actually declared `tool_search` to a collision-free public function name, translate its replayed call/output history to public function pairs, record only caller-authorized request-local conversions, and restore matching JSON/SSE calls to client `tool_search_call` items. Canonical OpenAI forward remains byte-shape native.
+- 다른 대안 대신 이 방식을 선택한 이유: Provider-specific workarounds fragment the contract, while unconditional restoration could turn an untrusted ordinary function call into a privileged client discovery action.
+- 장점, 단점 및 영향: Strict third-party Responses gateways can start and continue deferred discovery without changing native ChatGPT behavior; ordinary same-named functions remain distinct, and the proxy performs a capped SSE lifecycle rewrite only when the request actually required compatibility translation.
diff --git a/structure/decisions/ADR-0037-responses-http-sse.md b/structure/decisions/ADR-0037-responses-http-sse.md
new file mode 100644
index 0000000000..013d871e7e
--- /dev/null
+++ b/structure/decisions/ADR-0037-responses-http-sse.md
@@ -0,0 +1,12 @@
+# ADR-0037 — decision recorded under "Responses HTTP/SSE"
+
+- Contract owner: [transports/responses.md](../transports/responses.md#responses-httpsse)
+
+## Decision record
+
+- 목적과 의도: Keep Codex 0.147 namespace tool catalogs usable after a routed provider adopts native Responses but implements only the public flat tool variants.
+- 기존 구현 및 제약 조건: Chat translation already flattened namespace children, while native Responses passthrough forwarded the private `namespace` variant unchanged. xAI therefore rejected Grok requests before inference after its OAuth Grok 4.5/4.6 route moved to Responses.
+- 검토한 주요 대안: Move Grok back to Chat; special-case only xAI or the reserved `functions` group; flatten every complete namespace on noncanonical Responses and restore request-authorized aliases on return.
+- 선택한 방식: Noncanonical Responses lowers `functions` children to their bare top-level names and every other complete namespace to collision-checked `<namespace>__<name>` aliases after custom/tool-search conversion. It rewrites matching replay calls and tool selectors, records the aliases on the built request, and restores only those aliases in JSON/SSE call items before custom/tool-search lifecycle repair. Canonical OpenAI forward preserves native namespace shapes.
+- 다른 대안 대신 이 방식을 선택한 이유: A transport regression should not discard Responses streaming or create a provider-specific fork, and restoration without request-local authorization could reinterpret an unrelated upstream function as a client namespace call.
+- 장점, 단점 및 영향: Grok and other public-schema Responses gateways accept current Codex catalogs while Codex still receives explicit namespace routing. No `type: "namespace"` value survives the boundary: a group the layer cannot express — empty, nested, or with an unusable child name — is dropped along with the children it cannot represent, because relaying the private shape costs the whole request rather than one tool. Genuinely ambiguous wire names still fail closed, now as a 400 rather than an unstructured 500.
diff --git a/structure/decisions/ADR-0038-responses-http-sse.md b/structure/decisions/ADR-0038-responses-http-sse.md
new file mode 100644
index 0000000000..b70b30b6ac
--- /dev/null
+++ b/structure/decisions/ADR-0038-responses-http-sse.md
@@ -0,0 +1,12 @@
+# ADR-0038 — decision recorded under "Responses HTTP/SSE"
+
+- Contract owner: [transports/responses.md](../transports/responses.md#responses-httpsse)
+
+## Decision record
+
+- 목적과 의도: Complete Cursor turns at the protocol terminal instead of waiting for a separate HTTP-body EOF that may never arrive.
+- 기존 구현 및 제약 조건: Cursor can send turnEnded followed by a clean Connect END_STREAM envelope while RunSSE remains open or later closes through an abort-shaped transport error. The adapter logged the clean envelope but did not settle its terminal owner, so a completed-looking turn could remain open until the Responses stall watchdog.
+- 검토한 주요 대안: Shorten the global stall timeout; treat every later abort as success; settle only when the HTTP stream emits end; make the clean Connect envelope authoritative.
+- 선택한 방식: Process preceding frames in order, preserve an already-emitted terminal, run any already-armed drained client-tool finalizer before protocol cleanup clears its grace timer only while the call set is still drained, otherwise finalize once through the existing fail-closed tool-call logic, and settle the transport successfully on a clean Connect END_STREAM.
+- 다른 대안 대신 이 방식을 선택한 이유: The protocol envelope is upstream's explicit terminal signal. Timeout changes only hide the race, and globally swallowing aborts would mask genuine mid-turn cancellation.
+- 장점, 단점 및 영향: Completed Cursor responses no longer wait for the 300-second watchdog when the HTTP body stays open; incomplete tool calls still emit their existing truncation error, and error-bearing Connect terminals remain failures.
diff --git a/structure/decisions/ADR-0039-responses-http-sse.md b/structure/decisions/ADR-0039-responses-http-sse.md
new file mode 100644
index 0000000000..40f7c8b19b
--- /dev/null
+++ b/structure/decisions/ADR-0039-responses-http-sse.md
@@ -0,0 +1,23 @@
+# ADR-0039 — decision recorded under "Responses HTTP/SSE"
+
+- Contract owner: [transports/responses.md](../transports/responses.md#responses-httpsse)
+
+## Decision record
+
+- 목적과 의도: Keep a session usable after its history crosses backends, instead of wedging it on a
+  compaction blob the current upstream cannot decode.
+- 기존 구현 및 제약 조건: Compaction handling was binary — `ocx1:` envelopes were ours, everything
+  else was treated as a native blob and gated only by the destination, even though multiple backends
+  mint mutually incompatible blobs. Response-side field backfill exempted only `compaction`, so its
+  two sibling types received synthesized ids the client then replayed.
+- 검토한 주요 대안: Tag every compaction item with its minting provider/credential/model identity;
+  drop compaction items on any route change; gate relay on the destination that would decode them.
+- 선택한 방식: Reuse the thread's recorded serving identity to degrade native blobs after a known
+  route change; otherwise retain the destination capability gate, and treat the compact wire family
+  as one enumeration so id-bearing passes cannot diverge per type.
+- 다른 대안 대신 이 방식을 선택한 이유: Full per-item provenance tagging is unnecessary when the
+  existing thread identity proves a route change, while dropping the item would silently discard
+  compacted context and widening unknown-identity behavior needs a separate decision.
+- 장점, 단점 및 영향: A cross-backend session degrades one compaction summary to a note instead of
+  failing every later turn. A self-hosted OpenAI relay keeps its blobs only when explicitly opted in;
+  other routed gateways see a note because routed compaction produces an `ocx1:` envelope.
diff --git a/structure/decisions/ADR-0040-responses-http-sse.md b/structure/decisions/ADR-0040-responses-http-sse.md
new file mode 100644
index 0000000000..b87373fd5c
--- /dev/null
+++ b/structure/decisions/ADR-0040-responses-http-sse.md
@@ -0,0 +1,12 @@
+# ADR-0040 — decision recorded under "Responses HTTP/SSE"
+
+- Contract owner: [transports/responses.md](../transports/responses.md#responses-httpsse)
+
+## Decision record
+
+- 목적과 의도: Stop routed models from abandoning `apply_patch` after the Codex host rejects an object argument or a decorated marker, and from blocking a turn in a shell sleep loop when the host offers `session_id` polling.
+- 기존 구현 및 제약 조건: The shared nudge, Cursor guidance and native Responses instructions already carry the result-emission rule from `exec-tool-result-normalize.ts`, but none stated the helper's argument type, the marker rule, the import ban, or the polling protocol; `260905_apply_patch_envelope_gap` refused to rewrite JavaScript bodies (MODE B), so payload repair is off the table.
+- 검토한 주요 대안: Repair the argument shape inside the proxy (rejected: same body ambiguity as MODE B and it turns a rejected write into a performed one); Cursor-only guidance (rejected: the incident was native routed Responses on xAI); annotate every adapter's tool results (rejected: Anthropic/Google/OpenAI-chat/command-code have no exec-result seam and would need a new one).
+- 선택한 방식: One pre-call sentence and one marker→recovery table in the module that already owns the echo pair; inject the sentence at the three existing code-mode sites; annotate at the three existing exec-result seams with an exec-gated, idempotent helper that never changes error status.
+- 다른 대안 대신 이 방식을 선택한 이유: The safe repair for a host contract the model broke is to state it before the call and name it after the failure; keeping both halves in one file is what keeps them consistent.
+- 장점, 단점 및 영향: Code-mode system prompts grow by roughly 600 characters on routed turns; OpenAI destinations, flat catalogs and compaction requests are untouched. An exec result that legitimately prints one of the four phrases gains a recovery line, which is additive text and never an error flip. On Cursor, a structured tool literally named `exec` whose output quotes one of those phrases would also gain that line. The effect on the live Grok defect rate is unmeasured until a re-probe.
diff --git a/structure/decisions/ADR-0041-responses-http-sse.md b/structure/decisions/ADR-0041-responses-http-sse.md
new file mode 100644
index 0000000000..83920bcbb2
--- /dev/null
+++ b/structure/decisions/ADR-0041-responses-http-sse.md
@@ -0,0 +1,12 @@
+# ADR-0041 — decision recorded under "Responses HTTP/SSE"
+
+- Contract owner: [transports/responses.md](../transports/responses.md#responses-httpsse)
+
+## Decision record
+
+- 목적과 의도: Keep Codex hosted web search usable on xAI's public Responses endpoint without forwarding private OpenAI-only fields that xAI rejects.
+- 기존 구현 및 제약 조건: Codex emits `external_web_access`, `search_context_size`, `search_content_types`, and `user_location`; xAI documents a live-only `web_search` tool with domain filters and image flags, while Codex cached mode explicitly forbids external access.
+- 검토한 주요 대안: Strip only the first rejected field; pass every hosted-search field unchanged; disable web search for all xAI turns; normalize only the exact official xAI API destination.
+- 선택한 방식: On `https://api.x.ai` Responses traffic, lower live search to xAI's public shape, map image content requests to `enable_image_search`, remove unsupported OpenAI-private fields, and omit cached/index-only search plus stale selectors because xAI has no non-live equivalent.
+- 다른 대안 대신 이 방식을 선택한 이유: One-field stripping exposes the next schema mismatch and turning `external_web_access:false` into xAI live search widens the caller's network policy; destination scoping leaves custom gateways and canonical OpenAI byte-shape native.
+- 장점, 단점 및 영향: Grok 4.5/4.6 no longer fail every default Codex turn with an unsupported-argument 400; live search remains available when explicitly enabled, while cached search degrades to no hosted search on xAI rather than silently going live.
diff --git a/structure/decisions/ADR-0042-responses-http-sse.md b/structure/decisions/ADR-0042-responses-http-sse.md
new file mode 100644
index 0000000000..21f4b02159
--- /dev/null
+++ b/structure/decisions/ADR-0042-responses-http-sse.md
@@ -0,0 +1,12 @@
+# ADR-0042 — decision recorded under "Responses HTTP/SSE"
+
+- Contract owner: [transports/responses.md](../transports/responses.md#responses-httpsse)
+
+## Decision record
+
+- 목적과 의도: Match OpenCode Go's model-specific Luna endpoint without changing sibling model behavior.
+- 기존 구현 및 제약 조건: The preset had one Chat default even though the upstream publishes a mixed Chat, Responses, and Anthropic matrix; operators must retain explicit override precedence.
+- 검토한 주요 대안: Move the whole preset to Responses; infer from the model name; declare one exact registry default; also force bounded JSON from an older conditional terminal report.
+- 선택한 방식: Use one exact Luna wire default and leave upstream streaming unchanged.
+- 다른 대안 대신 이 방식을 선택한 이유: The endpoint mismatch is reproducible from current code and upstream documentation, whereas a current-dev live canary has not established the separate terminal-delivery policy.
+- 장점, 단점 및 영향: Luna reaches its documented endpoint across inbound surfaces and explicit opt-out still works; any future stream workaround remains a separately reviewed compatibility decision.
diff --git a/structure/decisions/ADR-0043-responses-http-sse.md b/structure/decisions/ADR-0043-responses-http-sse.md
new file mode 100644
index 0000000000..b28812cda8
--- /dev/null
+++ b/structure/decisions/ADR-0043-responses-http-sse.md
@@ -0,0 +1,12 @@
+# ADR-0043 — decision recorded under "Responses HTTP/SSE"
+
+- Contract owner: [transports/responses.md](../transports/responses.md#responses-httpsse)
+
+## Decision record
+
+- 목적과 의도: Give OpenCode Go the stable per-conversation header it requires for prompt-cache routing without exposing raw Codex identifiers.
+- 기존 구현 및 제약 조건: Codex already supplies task and subagent identity, but Go requests reached every adapter without `x-opencode-session`; one static provider header would collapse unrelated conversations.
+- 검토한 주요 대안: Forward a raw thread header; reuse `prompt_cache_key`; configure one global value; inject separately in Chat and Responses adapters; enrich the canonical provider before wire selection.
+- 선택한 방식: Hash the existing parent-qualified session lane with a provider-specific domain, attach it as runtime-only provider metadata before wire selection, and preserve an explicit operator override.
+- 다른 대안 대신 이 방식을 선택한 이유: The lane already separates sibling subagents, while cache keys may represent shared cohorts and adapter-local changes would drift across Go's mixed wire matrix.
+- 장점, 단점 및 영향: Go requests gain stable opaque affinity across normal retries and key rotation without persisted config changes; requests with no stable lane remain headerless rather than receiving a per-request value that defeats affinity.
diff --git a/structure/decisions/ADR-0044-responses-http-sse.md b/structure/decisions/ADR-0044-responses-http-sse.md
new file mode 100644
index 0000000000..d3e194fe21
--- /dev/null
+++ b/structure/decisions/ADR-0044-responses-http-sse.md
@@ -0,0 +1,20 @@
+# ADR-0044 — decision recorded under "Responses HTTP/SSE"
+
+- Contract owner: [transports/responses.md](../transports/responses.md#responses-httpsse)
+
+## Decision record
+
+- 목적과 의도: Turn upstream terminal variants and bare EOF into one deterministic Responses
+  outcome instead of a retryable disconnect or duplicate terminal.
+- 기존 구현 및 제약 조건: Policy refusals can arrive in several SSE envelopes, while a clean EOF,
+  an unterminated final frame, and a read error exercise different pull/tee and eager cleanup paths.
+- 검토한 주요 대안: Forward every byte unchanged; classify only request logs; synthesize a failure
+  after every EOF or read error; normalize the bounded terminal at the client output boundary.
+- 선택한 방식: Rewrite only high-confidence policy terminal shapes, preserve their bounded metadata,
+  flush native terminal candidates before transport-error classification, keep repair-owned
+  delimiter-less candidates tainted, and synthesize `adapter_eof` only when no real terminal exists.
+- 다른 대안 대신 이 방식을 선택한 이유: Log-only classification leaves Codex retry behavior
+  unchanged, while unconditional synthesis can create two contradictory outcomes for one turn.
+- 장점, 단점 및 영향: Both native relay shapes expose exactly one terminal and one sentinel with
+  matching accounting. Ordinary upstream errors remain fail-closed, and policy refusals remain
+  refusals rather than becoming successful model output.
diff --git a/structure/decisions/ADR-0045-standalone-images.md b/structure/decisions/ADR-0045-standalone-images.md
new file mode 100644
index 0000000000..84dd60634b
--- /dev/null
+++ b/structure/decisions/ADR-0045-standalone-images.md
@@ -0,0 +1,12 @@
+# ADR-0045 — decision recorded under "Standalone Images"
+
+- Contract owner: [data-planes/images.md](../data-planes/images.md#standalone-images)
+
+## Decision record
+
+- 목적과 의도: Preserve Codex Desktop reasoning summaries while adapting only the delivery enum rejected by a specific Responses-compatible upstream.
+- 기존 구현 및 제약 조건: The existing boolean capability either passed Codex's enum unchanged or disabled summaries entirely; stale running clients can keep sending the old enum after a catalog refresh.
+- 검토한 주요 대안: Disable summaries; rewrite the enum globally; inject a delivery field when absent; configure a provider-wide value.
+- 선택한 방식: Use a validated per-model allowlisted map, imply summary capability for that model, and rewrite only a caller-provided delivery field at the Responses adapter boundary.
+- 다른 대안 대신 이 방식을 선택한 이유: Upstream enum support differs by model and provider, while global rewriting or injection would change unrelated requests and disabling summaries removes Desktop UX.
+- 장점, 단점 및 영향: Configured models retain the native summary UI and stale clients self-heal; each incompatible model needs an explicit map entry and contradictory opt-out configuration now fails closed.
diff --git a/structure/decisions/ADR-0046-claude-desktop-config-library-resolution.md b/structure/decisions/ADR-0046-claude-desktop-config-library-resolution.md
new file mode 100644
index 0000000000..e1be492077
--- /dev/null
+++ b/structure/decisions/ADR-0046-claude-desktop-config-library-resolution.md
@@ -0,0 +1,12 @@
+# ADR-0046 — decision recorded under "Claude Desktop config-library resolution"
+
+- Contract owner: [clients/claude-desktop.md](../clients/claude-desktop.md#claude-desktop-config-library-resolution)
+
+## Decision record
+
+- 목적과 의도: 생성된 Claude Desktop 프로필이 설치된 Desktop이 실제로 읽는 디렉터리에 떨어지고, 대시보드 상태가 그 쓰기 대상과 일치하게 한다.
+- 기존 구현 및 제약 조건: 두 호출자가 경로 계산을 각자 복제했고, Desktop이 실제로 참조하는 `CLAUDE_USER_DATA_DIR`와 Windows `LOCALAPPDATA` 분기가 빠져 있었다(#539). 사용자가 프로필 루트를 직접 지정하는 경우도 있다.
+- 검토한 주요 대안: `-3p` 접미사를 구버전 잔재로 보고 제거; 두 디렉터리를 모두 스캔; 레거시 파일을 자동 이전; 크로스플랫폼 해석기를 한 곳에 둔다.
+- 선택한 방식: Desktop 번들의 해석 규칙을 그대로 이식한 override 인지 해석기를 한 곳에 두고, 쓰기 경로와 상태 조회가 같은 함수를 쓴다.
+- 다른 대안 대신 이 방식을 선택한 이유: `-3p`는 Desktop의 정상 동작이므로 제거는 회귀였다. 해석기를 한 곳에 두면 두 호출자의 드리프트가 불가능해지고, 파괴적 이전 없이 상태와 쓰기 대상이 일치한다.
+- 장점, 단점 및 영향: 지원 플랫폼 전부에서 apply 결과가 Desktop에 보인다. 비표준 레이아웃 사용자는 문서화된 override를 써야 하고, 해석기는 Desktop 번들의 규칙 변경을 따라가야 한다.
diff --git a/structure/decisions/ADR-0047-cursor-native-exec.md b/structure/decisions/ADR-0047-cursor-native-exec.md
new file mode 100644
index 0000000000..48eebb5328
--- /dev/null
+++ b/structure/decisions/ADR-0047-cursor-native-exec.md
@@ -0,0 +1,12 @@
+# ADR-0047 — decision recorded under "Cursor Native Exec"
+
+- Contract owner: [providers/cursor.md](../providers/cursor.md#cursor-native-exec)
+
+## Decision record
+
+- 목적과 의도: prevent caller-controlled Responses text from authorizing Cursor native local shell, filesystem, or fetch execution.
+- 기존 구현 및 제약 조건: the adapter preserved top-level `instructions`, system messages, and developer messages, then treated a `sandbox_mode ... danger-full-access` prose marker as an exec allow signal in `codex-sandbox` mode.
+- 검토한 주요 대안: keep marker-based authorization, require a future trustworthy attestation channel, or restrict authorization to server-local config.
+- 선택한 방식: keep marker detection only as diagnostic/context and make `nativeLocalExec: "on"` the only non-legacy mode that enables built-in local exec; unset, `off`, and `codex-sandbox` all deny.
+- 다른 대안 대신 이 방식을 선택한 이유: opencodex has no trustworthy per-request sandbox attestation in request text or headers, so any prompt-carried marker is spoofable by data-plane callers.
+- 장점, 단점 및 영향: this closes prompt-to-native-exec escalation while preserving an explicit operator escape hatch; existing configs that relied on `codex-sandbox` must switch to `nativeLocalExec: "on"` for trusted local experiments.
diff --git a/structure/decisions/ADR-0048-cursor-native-exec.md b/structure/decisions/ADR-0048-cursor-native-exec.md
new file mode 100644
index 0000000000..63a20aebc6
--- /dev/null
+++ b/structure/decisions/ADR-0048-cursor-native-exec.md
@@ -0,0 +1,12 @@
+# ADR-0048 — decision recorded under "Cursor Native Exec"
+
+- Contract owner: [providers/cursor.md](../providers/cursor.md#cursor-native-exec)
+
+## Decision record
+
+- 목적과 의도: keep fresh Cursor-routed Codex Desktop subagents able to invoke the actual unified `exec` tool exposed by their client catalog.
+- 기존 구현 및 제약 조건: catalog truncation already pinned `exec`, but the later generic-tool filter recognized only bare `exec_command`/`shell_command` and could erase the sole executable client tool while also naming aliases that were absent.
+- 검토한 주요 대안: synthesize a legacy alias, execute `exec` through Cursor native-local-exec, disable generic filtering, or treat every Responses-owned execution-path tool as eligible.
+- 선택한 방식: preserve the existing client tool and schema by filtering with `isCursorExecutionPathTool`; keep alias-specific prompt guidance gated on an alias actually being present.
+- 다른 대안 대신 이 방식을 선택한 이유: Codex Desktop remains the execution and approval authority, no unavailable tool name is invented, and the existing Responses MCP suspension path can relay the call without widening native execution privileges.
+- 장점, 단점 및 영향: unified `exec` survives the filter and returns to Desktop for execution; legacy aliases behave as before; `wait` and unrelated tools remain excluded from generic tool-count prompts.
diff --git a/structure/decisions/ADR-0049-heartbeat-and-stall-deadline.md b/structure/decisions/ADR-0049-heartbeat-and-stall-deadline.md
new file mode 100644
index 0000000000..9cb10eaf3e
--- /dev/null
+++ b/structure/decisions/ADR-0049-heartbeat-and-stall-deadline.md
@@ -0,0 +1,21 @@
+# ADR-0049 — decision recorded under "Heartbeat and stall deadline"
+
+- Contract owner: [transports/streaming-health.md](../transports/streaming-health.md#heartbeat-and-stall-deadline)
+
+## Decision record
+
+- 목적과 의도: Stop Codex from replaying a provider-rejected oversized turn and hand the failure
+  to the client's existing context-compaction semantics.
+- 기존 구현 및 제약 조건: Providers can reject before SSE starts; Codex retries raw HTTP 413,
+  while it recognizes terminal `response.failed` `context_length_exceeded`; the proxy cannot edit
+  Codex's persisted transcript safely.
+- 검토한 주요 대안: Relay 413 unchanged; return HTTP 400 JSON; silently remove media or old turns;
+  synthesize a successful assistant warning.
+- 선택한 방식: Preserve HTTP 413 with typed JSON for non-streaming clients, and map the final
+  streaming 413 to one redacted non-retryable Responses failure at the outer request boundary.
+- 다른 대안 대신 이 방식을 선택한 이유: Raw 413 causes a retry loop, HTTP JSON does not enter
+  Codex's context-window path, and silent deletion or fake success loses user intent without fixing
+  transcript ownership.
+- 장점, 단점 및 영향: Codex stops reconnecting and can compact on the next turn; no input is
+  silently lost. The failed turn itself is not auto-replayed, and callers must retry after Codex
+  compacts or reduce the current input.
diff --git a/structure/decisions/ADR-0050-heartbeat-and-stall-deadline.md b/structure/decisions/ADR-0050-heartbeat-and-stall-deadline.md
new file mode 100644
index 0000000000..0c79aea9a2
--- /dev/null
+++ b/structure/decisions/ADR-0050-heartbeat-and-stall-deadline.md
@@ -0,0 +1,12 @@
+# ADR-0050 — decision recorded under "Heartbeat and stall deadline"
+
+- Contract owner: [transports/streaming-health.md](../transports/streaming-health.md#heartbeat-and-stall-deadline)
+
+## Decision record
+
+- 목적과 의도: Prevent Kiro progress from becoming a false final answer, reject invalid empty completion retries, and stop concurrent transient 429s from consuming independent retry budgets.
+- 기존 구현 및 제약 조건: Kiro text has no trustworthy phase; stop metadata arrives only at stream end; the private completion tool is adapter-owned; normal parallel tool traffic must remain parallel; client cancellation must interrupt all waits.
+- 검토한 주요 대안: Trust native `END_TURN`; infer completion from wording; serialize every Kiro request; leave throttling entirely to the client; manufacture empty assistant turns to preserve alternation.
+- 선택한 방식: Require the private completion tool on tool-enabled turns, rebuild only valid replayable wire turns, validate the final conversation, and activate a shared cooldown plus single probe only after a transient throttle.
+- 다른 대안 대신 이 방식을 선택한 이유: Native stop metadata has mislabeled progress, wording is language-dependent, global serialization harms healthy concurrency, client-only retries amplify bursts, and empty structural turns are rejected upstream.
+- 장점, 단점 및 영향: Completion phase is deterministic and throttled concurrency recovers without a request storm; some clean Kiro stops pay one bounded validation call and an exactly repeated completion answer may be shown twice to preserve `final_answer` semantics.
diff --git a/structure/decisions/ADR-0051-reasoning-and-tool-result-compatibility.md b/structure/decisions/ADR-0051-reasoning-and-tool-result-compatibility.md
new file mode 100644
index 0000000000..b615971553
--- /dev/null
+++ b/structure/decisions/ADR-0051-reasoning-and-tool-result-compatibility.md
@@ -0,0 +1,12 @@
+# ADR-0051 — decision recorded under "Reasoning and tool-result compatibility"
+
+- Contract owner: [providers/chat-compat.md](../providers/chat-compat.md#reasoning-and-tool-result-compatibility)
+
+## Decision record
+
+- 목적과 의도: Keep same-backend opaque reasoning replay while preventing backend-private blobs and output-only fields from breaking the first turn after a route change.
+- 기존 구현 및 제약 조건: Reasoning-input sanitation already handled raw content and `ocxr1:` envelopes; the replay cache already supplied a bounded, thread-scoped physical-route identity, but no record connected that identity to native `encrypted_content` provenance.
+- 검토한 주요 대안: Strip every opaque blob, persist provenance across restarts, trust generic 4xx prose, rely only on a retry, or combine deterministic route comparison with a narrowly identified recovery.
+- 선택한 방식: Remove output-only `status` from every reasoning input item without changing the pre-existing raw-`content` blanking rule; compare a 64-entry/256 KiB/one-hour in-process serving-identity record using durable destination and credential dimensions before sending, commit it only after the selected destination succeeds, pass a proven change into the Responses adapter before the first send, and use one self-identified opaque-blob recovery only when provenance was unknown.
+- 다른 대안 대신 이 방식을 선택한 이유: The former blob/status coupling was defensive rather than observed, and live backends showed that removing `status` preserves same-backend Grok replay while allowing cold cross-backend requests to reach blob validation. Unknown provenance can still be valid after restart, durable storage is unnecessary for this bounded compatibility hint, and deterministic pre-flight avoids the extra paid or stateful upstream attempt whenever the process has evidence. The upstream's narrow error identity supplies authoritative evidence only for histories the process could not observe.
+- 장점, 단점 및 영향: Same-route and unknown replay retain cached reasoning on the first send without replaying an output-only field, known cross-route replay keeps the reasoning item without its undecodable blob, and a cold cross-route replay can reach opaque-blob recovery instead of failing early on `status`. A repeated blob rejection is surfaced unchanged after exactly one recovery attempt.
diff --git a/structure/decisions/ADR-0052-reasoning-and-tool-result-compatibility.md b/structure/decisions/ADR-0052-reasoning-and-tool-result-compatibility.md
new file mode 100644
index 0000000000..98a32fd2cc
--- /dev/null
+++ b/structure/decisions/ADR-0052-reasoning-and-tool-result-compatibility.md
@@ -0,0 +1,12 @@
+# ADR-0052 — decision recorded under "Reasoning and tool-result compatibility"
+
+- Contract owner: [providers/chat-compat.md](../providers/chat-compat.md#reasoning-and-tool-result-compatibility)
+
+## Decision record
+
+- 목적과 의도: Preserve DeepSeek reasoning replay for parallel tool calls while retaining the provider-scoped repair for hook-interleaved results.
+- 기존 구현 및 제약 조건: Pair-by-pair adjacency fixed one call but split parallel calls into separate assistant turns; DeepSeek always enables parallel tool calling and merges adjacent reasoning and calls into one assistant message.
+- 검토한 주요 대안: Disable parallel calls, duplicate reasoning, remove the #1292 repair, or normalize one unambiguous call/output batch.
+- 선택한 방식: Group calls that occur before the first matched output, emit the call batch followed by outputs in call order, and retain intervening non-tool items after the batch.
+- 다른 대안 대신 이 방식을 선택한 이유: The batch shape matches the documented Responses contract without inventing reasoning or reintroducing hook-interleaving failures.
+- 장점, 단점 및 영향: Sequential and parallel tool continuations both retain their reasoning contract; only the declared strict provider changes order, and ambiguous histories still fail closed upstream.
diff --git a/structure/decisions/ADR-0053-cursor-active-context-usage.md b/structure/decisions/ADR-0053-cursor-active-context-usage.md
new file mode 100644
index 0000000000..709bfde309
--- /dev/null
+++ b/structure/decisions/ADR-0053-cursor-active-context-usage.md
@@ -0,0 +1,12 @@
+# ADR-0053 — decision recorded under "Cursor active-context usage"
+
+- Contract owner: [providers/cursor.md](../providers/cursor.md#cursor-active-context-usage)
+
+## Decision record
+
+- 목적과 의도: Keep Codex's visible "context left" indicator aligned with Cursor's active-context usage on client-tool turns that finalize before a checkpoint arrives.
+- 기존 구현 및 제약 조건: Checkpoint turns reported totalTokens correctly, but no-checkpoint client-tool finalize fell back to output-only usage and could overwrite a meaningful prior total with values like 109 tokens.
+- 검토한 주요 대안: Add a longer wait for late checkpoints; infer prior+output totals; store full prompt/history state; carry forward only the last numeric checkpoint per Cursor conversation.
+- 선택한 방식: Carry forward the last numeric absolute checkpoint per Cursor conversation with bounded LRU/TTL storage, update it only from live checkpoint frames, and clear/suppress it once when a newly appended compaction boundary starts an epoch; previous_response replay provenance acknowledges historical markers without serializing private metadata upstream.
+- 다른 대안 대신 이 방식을 선택한 이유: It fixes the UI regression without delaying tool turns, fabricating token growth, storing prompt/tool content, or repeatedly clearing valid post-compaction usage when historical markers replay; one-time compaction resets still prevent stale over-report when history is replaced.
+- 장점, 단점 및 영향: Active-context reporting stays monotonic within an uncompacted Cursor conversation; no-checkpoint turns remain estimated; a process restart loses the numeric cache, and when neither a checkpoint nor a carry-forward is available the turn reports a request-local estimate derived from the same pruned payload sent to Cursor (#373 — reporting output-only usage made Codex read the context as nearly empty). Estimates are never persisted or promoted into checkpoint carry-forward; only live checkpoint frames update the cache.
diff --git a/structure/decisions/ADR-0054-cursor-conversation-checkpoint-reuse.md b/structure/decisions/ADR-0054-cursor-conversation-checkpoint-reuse.md
new file mode 100644
index 0000000000..1ff6c2f6fa
--- /dev/null
+++ b/structure/decisions/ADR-0054-cursor-conversation-checkpoint-reuse.md
@@ -0,0 +1,12 @@
+# ADR-0054 — decision recorded under "Cursor conversation checkpoint reuse"
+
+- Contract owner: [providers/cursor.md](../providers/cursor.md#cursor-conversation-checkpoint-reuse)
+
+## Decision record
+
+- 목적과 의도: Reuse Cursor's returned ConversationStateStructure on validated linear continuations so OpenCodex does not rebuild the full root history every turn.
+- 기존 구현 및 제약 조건: Stable conversation ids already exist (#366), but every turn still reconstructed rootPromptMessagesJson and conversationTurns. Cursor Connect still reports only usedTokens/maxTokens, so cache_read_tokens cannot be treated as authoritative (#275).
+- 검토한 주요 대안: Keep full replay; copy Pi's live MCP bridge immediately; store raw protobuf in Responses JSON; key checkpoints only by conversation id.
+- 선택한 방식: Keep an opaque process-local checkpointRef on OcxProviderContinuationState.cursor, bind the snapshot to conversation/account/model affinity, and require a remembered provider conversation or stable client thread before a ref-less prefix lookup. Reuse the bounded process-local Desktop session/thread HMAC when the canonical parent-thread header is absent. Pin referenced blobs for the checkpoint lifetime, and fall back to the existing full-replay path for unowned headerless requests, isolation, compaction, restart, missing refs, and invalid_argument recovery. Tool-result turns reuse the last completed checkpoint plus an uncovered suffix. previous_response_id is a branch anchor, never a Cursor conversation ownership key.
+- 다른 대안 대신 이 방식을 선택한 이유: It removes avoidable replay cost without claiming cache-hit rates, without changing OAuth, and without collapsing helper/compaction isolation or tool-call replay safety.
+- 장점, 단점 및 영향: Validated no-tool follow-ups stop growing local rootBytes with history; a process restart or missing blob lease falls back to full replay; large-context 429 / premature-completion acceptance for #1527 is still unproven; a stateful live MCP bridge remains out of scope.
diff --git a/structure/decisions/ADR-0055-google-thought-text-visibility-boundary.md b/structure/decisions/ADR-0055-google-thought-text-visibility-boundary.md
new file mode 100644
index 0000000000..4a08b5c568
--- /dev/null
+++ b/structure/decisions/ADR-0055-google-thought-text-visibility-boundary.md
@@ -0,0 +1,12 @@
+# ADR-0055 — decision recorded under "Google thought-text visibility boundary"
+
+- Contract owner: [providers/google.md](../providers/google.md#google-thought-text-visibility-boundary)
+
+## Decision record
+
+- 목적과 의도: Prevent provider-marked internal reasoning from appearing as ordinary assistant text while preserving reasoning and tool-call continuation.
+- 기존 구현 및 제약 조건: Both Google response paths emitted every non-empty `Part.text` as visible text; function calls, inline images, and Antigravity/Vertex thought-signature replay already depended on the original part ordering.
+- 검토한 주요 대안: Drop thought text; classify it separately in each parser; remove the marker and keep visible text; use one shared classifier without mutating the provider parts.
+- 선택한 방식: Map `thought: true` text to `reasoning_raw_delta` through one helper used by streaming and buffered parsing, leaving part order and signature observation unchanged.
+- 다른 대안 대신 이 방식을 선택한 이유: Dropping the text loses reasoning replay/display policy input, while duplicated parser rules can drift and exposing marked thoughts violates the provider's visibility boundary.
+- 장점, 단점 및 영향: Internal reasoning no longer leaks into normal answers and both transports stay consistent; downstream reasoning policy still decides whether raw reasoning is rendered or only preserved, and malformed non-boolean markers remain ordinary text rather than broadening hidden-content inference.
diff --git a/structure/decisions/ADR-0056-google-response-part-field-boundary.md b/structure/decisions/ADR-0056-google-response-part-field-boundary.md
new file mode 100644
index 0000000000..1903d92dc5
--- /dev/null
+++ b/structure/decisions/ADR-0056-google-response-part-field-boundary.md
@@ -0,0 +1,12 @@
+# ADR-0056 — decision recorded under "Google response-part field boundary"
+
+- Contract owner: [providers/google.md](../providers/google.md#google-response-part-field-boundary)
+
+## Decision record
+
+- 목적과 의도: Keep malformed Google-compatible response fields from violating the internal string-only text and tool-name contract or dispatching an unidentified tool.
+- 기존 구현 및 제약 조건: Container validation guaranteed object parts, but truthy string/number/array functionCall values emitted a nameless tool call and truthy non-string text values crossed as text or reasoning events. Gemini supplies a complete call in one part, so there is no later name fragment to await.
+- 검토한 주요 대안: Pass malformed values through; coerce them to strings; silently drop every malformed field; terminate the turn for every malformed field; distinguish dispatch identity from optional text.
+- 선택한 방식: Prevalidate function calls and terminate on a non-object, non-string, empty, or whitespace name; drop only non-string text; leave arguments untouched.
+- 다른 대안 대신 이 방식을 선택한 이유: Passing or coercing can execute the wrong tool or fabricate transcript text, while terminating for optional malformed text discards an otherwise usable response. An invalid call name cannot be recovered or safely ignored once the model selected a tool.
+- 장점, 단점 및 영향: Streaming and buffered paths enforce the same AdapterEvent contract and invalid calls cannot enter thought-signature replay. Nonconforming third-party Google-compatible text fields are ignored rather than surfaced, and operators receive a structured terminal error for call identity failures.
diff --git a/structure/decisions/ADR-0057-google-tool-call-thought-signature-replay.md b/structure/decisions/ADR-0057-google-tool-call-thought-signature-replay.md
new file mode 100644
index 0000000000..c2cad106da
--- /dev/null
+++ b/structure/decisions/ADR-0057-google-tool-call-thought-signature-replay.md
@@ -0,0 +1,12 @@
+# ADR-0057 — decision recorded under "Google tool-call thought-signature replay"
+
+- Contract owner: [providers/google.md](../providers/google.md#google-tool-call-thought-signature-replay)
+
+## Decision record
+
+- 목적과 의도: Preserve Vertex Gemini tool-call continuation without exposing opaque signatures to Codex or another Google backend.
+- 기존 구현 및 제약 조건: Responses history does not carry a safe Gemini signature field; Antigravity already used a bounded in-process replay cache, while Vertex bypassed it and received HTTP 400 after the first tool call.
+- 검토한 주요 대안: Serialize the signature into Responses item ids or reasoning content; create an unbounded Vertex map; reuse the bounded cache with or without a transport namespace.
+- 선택한 방식: Reuse the bounded cache for Vertex, observe both response shapes, apply after wire-name compilation, and scope Vertex by transport/project/location plus the opaque client session key when available.
+- 다른 대안 대신 이 방식을 선택한 이유: Responses ids are not Gemini signatures and previously caused Base64/TYPE_BYTES failures; a second cache duplicates limits; an unscoped cache could send provider-private state across destinations.
+- 장점, 단점 및 영향: Tool loops continue with exact opaque state and bounded memory while cross-transport reuse fails closed. Replay remains process-local, matching the existing Antigravity contract.
diff --git a/structure/decisions/ADR-0058-google-tool-result-adjacency-repair.md b/structure/decisions/ADR-0058-google-tool-result-adjacency-repair.md
new file mode 100644
index 0000000000..9489cf1cc7
--- /dev/null
+++ b/structure/decisions/ADR-0058-google-tool-result-adjacency-repair.md
@@ -0,0 +1,23 @@
+# ADR-0058 — decision recorded under "Google tool-result adjacency repair"
+
+- Contract owner: [providers/google.md](../providers/google.md#google-tool-result-adjacency-repair)
+
+## Decision record
+
+- 목적과 의도: prevent interrupted or replayed Claude-on-Antigravity histories from reaching the
+  Google wire with unanswered `functionCall` or unpaired `functionResponse` parts.
+- 기존 구현 및 제약 조건: `messagesToGeminiFormat` emitted every internal message independently;
+  Antigravity translates the resulting Gemini shape back into strict Anthropic tool-use blocks, and
+  rejects malformed adjacency with HTTP 400. Tool-result images cannot live inside a
+  `functionResponse` and already rely on sibling `inline_data` parts.
+- 검토한 주요 대안: repair the shared internal history; synthesize fake calls for orphan results;
+  repair only the Google adapter serialization boundary.
+- 선택한 방식: group only consecutive results after a model call batch, match by the normalized
+  request-scoped call id, emit responses in call order, synthesize an explicit missing result, and
+  degrade remaining results to marked text while retaining image siblings.
+- 다른 대안 대신 이 방식을 선택한 이유: shared-history mutation could change other adapters,
+  while fabricating a successful call would invent model behavior. The adapter boundary owns the
+  strict upstream wire contract and can repair it without changing client-visible history.
+- 장점, 단점 및 영향: normal histories remain byte-shape equivalent, parallel and interrupted
+  histories become provider-valid, and orphan data is not lost. A result separated by a non-tool
+  barrier is intentionally not reattached across that boundary.
diff --git a/structure/decisions/ADR-0059-xai-grok-hardening-official-grok-build-contract.md b/structure/decisions/ADR-0059-xai-grok-hardening-official-grok-build-contract.md
new file mode 100644
index 0000000000..005f98ea1e
--- /dev/null
+++ b/structure/decisions/ADR-0059-xai-grok-hardening-official-grok-build-contract.md
@@ -0,0 +1,23 @@
+# ADR-0059 — decision recorded under "xAI Grok hardening (official Grok Build contract parity)"
+
+- Contract owner: [providers/xai-grok.md](../providers/xai-grok.md#xai-grok-hardening-official-grok-build-contract-parity)
+
+## Decision record
+
+- 목적과 의도: Prevent Grok Build from classifying a visibly streamed answer as empty and replaying
+  the same billable turn when the terminal snapshot is sparse.
+- 기존 구현 및 제약 조건: OpenCodex already reconstructed missing terminal output for provider
+  opt-ins, but preserved explicit empty arrays; Grok Build discarded ordinary completed-item events
+  when constructing its final conversation response.
+- 검토한 주요 대안: Change every caller's empty-array semantics; accept a turn merely because a
+  text delta was visible; reuse the provider's broader lifecycle synthesis; add a strict repair at
+  the generated Grok client boundary.
+- 선택한 방식: Use the existing generated client marker to opt Grok into a terminal-only repair and
+  backfill only from unique, contiguous, bounded real done items whose raw semantics are valid.
+- 다른 대안 대신 이 방식을 선택한 이유: A global rewrite would alter valid provider semantics,
+  while accepting deltas without durable items would leave persistence and continuation empty. The
+  marker is already the client-specific compatibility boundary; keeping the provider repair separate
+  also prevents synthesized or permissively normalized items from overriding an explicit empty terminal.
+- 장점, 단점 및 영향: Grok receives one durable completed answer without a paid retry; ordinary
+  clients remain byte-semantics compatible. The proxy retains bounded item state for marked streams
+  and intentionally refuses ambiguous reconstruction.
diff --git a/structure/decisions/ADR-0060-kiro-client-parallel-tool-hint.md b/structure/decisions/ADR-0060-kiro-client-parallel-tool-hint.md
new file mode 100644
index 0000000000..4bcdcbd2a0
--- /dev/null
+++ b/structure/decisions/ADR-0060-kiro-client-parallel-tool-hint.md
@@ -0,0 +1,12 @@
+# ADR-0060 — decision recorded under "Kiro client parallel-tool hint"
+
+- Contract owner: [providers/kiro.md](../providers/kiro.md#kiro-client-parallel-tool-hint)
+
+## Decision record
+
+- 목적과 의도: Keep current Codex clients usable with Kiro without claiming or inventing parallel execution on the CodeWhisperer wire.
+- 기존 구현 및 제약 조건: Codex can send `parallel_tool_calls: true` even for catalog rows that advertise false; Kiro has no verified parallel-control request field and serializes tool execution.
+- 검토한 주요 대안: Reject the client hint, rewrite it to false before routing, or accept it as permission while leaving the Kiro wire unchanged.
+- 선택한 방식: Accept either request value, preserve the parsed client intent internally, and omit all parallel-control fields from the Kiro payload.
+- 다른 대안 대신 이 방식을 선택한 이유: Rejection interprets permission as a requirement and blocks valid turns, while rewriting shared request state hides caller intent and can affect later policy or diagnostics.
+- 장점, 단점 및 영향: Codex tool turns reach Kiro again and the adapter contract stays honest; Kiro still cannot produce true parallel tool batches through this transport.
diff --git a/structure/decisions/ADR-0061-kiro-responses-text-controls.md b/structure/decisions/ADR-0061-kiro-responses-text-controls.md
new file mode 100644
index 0000000000..8f545cf432
--- /dev/null
+++ b/structure/decisions/ADR-0061-kiro-responses-text-controls.md
@@ -0,0 +1,12 @@
+# ADR-0061 — decision recorded under "Kiro Responses text controls"
+
+- Contract owner: [providers/kiro.md](../providers/kiro.md#kiro-responses-text-controls)
+
+## Decision record
+
+- 목적과 의도: Stop rejecting valid Kiro turns whose only offence is carrying a Responses text control the wire ignores.
+- 기존 구현 및 제약 조건: The guard tested `_rawBody.text !== undefined`, so `text.verbosity`, `text.format:{"type":"text"}`, and even `text:{}` produced HTTP 400 with sendCount 0 while identical turns without `text` succeeded; `_structuredOutput` already distinguishes real structured output, and the catalog's `support_verbosity: false` helps neither a client holding a cached catalog nor the default text format, which no capability flag governs.
+- 검토한 주요 대안: Keep the presence check, add an openai-responses-style stripper before serialization, or narrow the guard to `_structuredOutput` alone.
+- 선택한 방식: Narrow the condition to `_structuredOutput`; no stripper is needed because the Kiro payload never spreads the raw body.
+- 다른 대안 대신 이 방식을 선택한 이유: The presence check reads a preference as a requirement — the same error `db040e70f` removed for parallel-tool hints — and a stripper would add a serialization stage to defend against a body Kiro already ignores by construction.
+- 장점, 단점 및 영향: Kiro-routed Codex turns stop failing intermittently and structured output stays honestly refused; a future `text` member Kiro genuinely cannot ignore would need its own condition.
diff --git a/structure/decisions/ADR-0062-chat-streaming-client-with-a-json-upstream-resul.md b/structure/decisions/ADR-0062-chat-streaming-client-with-a-json-upstream-resul.md
new file mode 100644
index 0000000000..7c59b66133
--- /dev/null
+++ b/structure/decisions/ADR-0062-chat-streaming-client-with-a-json-upstream-resul.md
@@ -0,0 +1,12 @@
+# ADR-0062 — decision recorded under "Chat streaming client with a JSON upstream result"
+
+- Contract owner: [data-planes/inbound-compat.md](../data-planes/inbound-compat.md#chat-streaming-client-with-a-json-upstream-result)
+
+## Decision record
+
+- 목적과 의도: Keep tool execution and incomplete-response detection working when a streaming client receives a JSON upstream result.
+- 기존 구현 및 제약 조건: The existing fallback copied only text and forced `stop`, despite the JSON converter already retaining tool calls, reasoning, and incomplete status.
+- 검토한 주요 대안: Duplicate Responses parsing in the emitter; perform another inference request; preserve the already-converted Chat completion.
+- 선택한 방식: Copy supported converted message fields into one delta, assign tool-call stream indexes, and retain the converted finish reason.
+- 다른 대안 대신 이 방식을 선택한 이유: One conversion authority prevents the streaming fallback from drifting from non-streaming semantics without changing routing or retry behavior.
+- 장점, 단점 및 영향: No additional upstream request or dependency; this remains buffered delivery, not token-by-token upstream streaming. Handler regressions cover tools, reasoning, length, ordinary and empty completions, and budget release.
diff --git a/structure/decisions/ADR-0063-volcengine-ark-assistant-continuation-shapes.md b/structure/decisions/ADR-0063-volcengine-ark-assistant-continuation-shapes.md
new file mode 100644
index 0000000000..a921088dcd
--- /dev/null
+++ b/structure/decisions/ADR-0063-volcengine-ark-assistant-continuation-shapes.md
@@ -0,0 +1,12 @@
+# ADR-0063 — decision recorded under "Volcengine Ark assistant continuation shapes"
+
+- Contract owner: [providers/chat-compat.md](../providers/chat-compat.md#volcengine-ark-assistant-continuation-shapes)
+
+## Decision record
+
+- 목적과 의도: Preserve multi-turn tool-call continuations across both Ark Chat endpoint families.
+- 기존 구현 및 제약 조건: The #796 workaround was host-wide and unverified; live Coding Plan evidence shows its structured placeholder returns HTTP 400 while an empty string succeeds.
+- 검토한 주요 대안: Remove the workaround globally, select by model ID, or scope it by endpoint path.
+- 선택한 방식: Apply the structured placeholder only to recognized Ark hosts whose normalized base path is exactly `/api/v3`.
+- 다른 대안 대신 이 방식을 선택한 이유: Global removal would reopen #796, while model IDs can appear behind multiple Ark products and therefore do not identify the wire contract.
+- 장점, 단점 및 영향: Coding Plan regains its accepted continuation shape without changing generic providers; any future Ark endpoint family must provide evidence before inheriting the pay-as-you-go quirk.
diff --git a/structure/decisions/ADR-0064-chat-structured-output-compatibility.md b/structure/decisions/ADR-0064-chat-structured-output-compatibility.md
new file mode 100644
index 0000000000..f19b51239a
--- /dev/null
+++ b/structure/decisions/ADR-0064-chat-structured-output-compatibility.md
@@ -0,0 +1,12 @@
+# ADR-0064 — decision recorded under "Chat structured-output compatibility"
+
+- Contract owner: [providers/chat-compat.md](../providers/chat-compat.md#chat-structured-output-compatibility)
+
+## Decision record
+
+- 목적과 의도: Make Moonshot's compatibility rewrite remove rejected sibling `$ref` shapes without silently weakening a tool schema.
+- 기존 구현 및 제약 조건: The target and sibling both apply under JSON Schema 2020-12, but a shallow shared-property merge let sibling bounds replace stricter target bounds; Moonshot still requires the local bounded rewrite.
+- 검토한 주요 대안: Keep shallow sibling precedence; emit `allOf`; intersect only top-level bounds; recursively compose the supported set-valued and ordered assertions.
+- 선택한 방식: Reuse the existing bound and required intersection rules recursively for overlapping object properties inside the first-party destination gate.
+- 다른 대안 대신 이 방식을 선택한 이유: Shallow precedence weakens constraints, while a new `allOf` wire shape needs separate provider evidence; recursive composition fixes the demonstrated loss without broadening normalization to custom providers.
+- 장점, 단점 및 영향: Looser siblings cannot relax nested constraints and tighter siblings still narrow them; non-ordered conflicting keywords retain the existing sibling precedence and are not treated as a complete JSON Schema algebra.
diff --git a/structure/decisions/ADR-0065-chat-structured-output-compatibility.md b/structure/decisions/ADR-0065-chat-structured-output-compatibility.md
new file mode 100644
index 0000000000..e7cdd33ed1
--- /dev/null
+++ b/structure/decisions/ADR-0065-chat-structured-output-compatibility.md
@@ -0,0 +1,12 @@
+# ADR-0065 — decision recorded under "Chat structured-output compatibility"
+
+- Contract owner: [providers/chat-compat.md](../providers/chat-compat.md#chat-structured-output-compatibility)
+
+## Decision record
+
+- 목적과 의도: Recover chat models that reject `response_format` without removing structured output from models that support it.
+- 기존 구현 및 제약 조건: The adapter forwarded the field to every routed chat model after #1137, while the same model id may sit behind gateways with different capabilities.
+- 검토한 주요 대안: Revert translation globally; blacklist a model id globally; detect a proxy by name or URL; add an explicit provider/model opt-out.
+- 선택한 방식: Preserve default translation and omit it only for exact ids in `noStructuredOutputModels`.
+- 다른 대안 대신 이 방식을 선택한 이유: Global or heuristic rules regress supported providers and make custom gateway names part of the wire contract.
+- 장점, 단점 및 영향: Compatible siblings retain schema enforcement and explicitly incompatible models avoid the upstream 400; operators must classify each unsupported model they route.
diff --git a/structure/decisions/ADR-0066-anthropic-structured-output-compatibility.md b/structure/decisions/ADR-0066-anthropic-structured-output-compatibility.md
new file mode 100644
index 0000000000..dfab9c437f
--- /dev/null
+++ b/structure/decisions/ADR-0066-anthropic-structured-output-compatibility.md
@@ -0,0 +1,12 @@
+# ADR-0066 — decision recorded under "Anthropic structured-output compatibility"
+
+- Contract owner: [providers/chat-compat.md](../providers/chat-compat.md#anthropic-structured-output-compatibility)
+
+## Decision record
+
+- 목적과 의도: Preserve schema-constrained output when OpenAI-shaped Responses or Chat Completions requests route to Anthropic Messages.
+- 기존 구현 및 제약 조건: The parser retained the requested schema, but the Anthropic adapter dropped it; forwarding the OpenAI schema unchanged fails when it includes constraints outside Anthropic's supported subset.
+- 검토한 주요 대안: Keep tool-call emulation; forward the raw schema; depend on the full Anthropic SDK; maintain a local compatibility transform based on the SDK.
+- 선택한 방식: Merge Anthropic `output_config.format` into compatible adaptive-thinking configuration, mirror the SDK transform locally with strict `unknown` narrowing, move unsupported constraints into descriptions, and preserve root `$defs` before returning a root `$ref`.
+- 다른 대안 대신 이 방식을 선택한 이유: Native structured output avoids synthetic tools, raw forwarding produces upstream 400s, and importing the full SDK only for a small wire transform would duplicate the adapter's direct HTTP ownership.
+- 장점, 단점 및 영향: Both OpenAI-shaped input surfaces gain native Anthropic schema enforcement and unsupported intent remains visible to the model; the copied subset must track upstream SDK changes, description-carried constraints are guidance rather than hard validation, and the root-reference fix is an intentional divergence to keep definitions reachable.
diff --git a/structure/decisions/ADR-0067-reasoning-display-parity-hidethinkingsummary.md b/structure/decisions/ADR-0067-reasoning-display-parity-hidethinkingsummary.md
new file mode 100644
index 0000000000..672d781b4b
--- /dev/null
+++ b/structure/decisions/ADR-0067-reasoning-display-parity-hidethinkingsummary.md
@@ -0,0 +1,12 @@
+# ADR-0067 — decision recorded under "Reasoning display parity (hideThinkingSummary)"
+
+- Contract owner: [providers/chat-compat.md](../providers/chat-compat.md#reasoning-display-parity-hidethinkingsummary)
+
+## Decision record
+
+- 목적과 의도: Keep reasoning replay bounded while preserving opaque values exactly.
+- 기존 구현 및 제약 조건: Reasoning continuity needs JSON/base64 envelopes, and existing callers already own retained accounting and typed overflow handling.
+- 검토한 주요 대안: Per-field truncation, an independent fixed field limit, or shared transient admission plus cumulative inbound ownership.
+- 선택한 방식: Reserve conservative copy projections in the envelope helpers and use the existing request budget across inbound blocks.
+- 다른 대안 대신 이 방식을 선택한 이유: Truncation changes signed values; one field limit does not describe aggregate ownership. Existing budget errors retain the established HTTP and stream error contracts.
+- 장점, 단점 및 영향: Normal replay is unchanged; envelope admission includes copy overhead and is stricter than a raw-string length ceiling. These are translator accounting limits, not a process-wide RSS guarantee.
diff --git a/structure/decisions/ADR-0068-reasoning-display-parity-hidethinkingsummary.md b/structure/decisions/ADR-0068-reasoning-display-parity-hidethinkingsummary.md
new file mode 100644
index 0000000000..735311e1c0
--- /dev/null
+++ b/structure/decisions/ADR-0068-reasoning-display-parity-hidethinkingsummary.md
@@ -0,0 +1,12 @@
+# ADR-0068 — decision recorded under "Reasoning display parity (hideThinkingSummary)"
+
+- Contract owner: [providers/chat-compat.md](../providers/chat-compat.md#reasoning-display-parity-hidethinkingsummary)
+
+## Decision record
+
+- 목적과 의도: Preserve tool-call continuation compatibility without forwarding one provider or physical account's private reasoning to another fallback target.
+- 기존 구현 및 제약 조건: Conversation-only scoping stopped process-global call-id collisions, but combo and 429 failover can reuse the same thread and provider-generated call id across destinations or credentials.
+- 검토한 주요 대안: Disable replay on every failover-capable provider; key only by provider name; use persisted or truncated secret-derived ids; bind the in-memory cache to an exact process-local route and credential tuple.
+- 선택한 방식: Keep a shared mutable scope holder and key entries by thread, provider name, an opaque destination HMAC, adapter, final model, and an opaque HMAC/account identity; incomplete identities read and write nothing.
+- 다른 대안 대신 이 방식을 선택한 이유: Exact binding preserves same-generation same-target retries while making account switches and OAuth token refreshes fail closed, without logging, persisting, or exposing credential material.
+- 장점, 단점 및 영향: Cross-provider/account replay is blocked and rotations are visible to live bridges; providers without a stable credential identity lose cache replay and use the existing minimal placeholder path.
diff --git a/structure/decisions/ADR-0069-chat-to-responses-message-phase-inference.md b/structure/decisions/ADR-0069-chat-to-responses-message-phase-inference.md
new file mode 100644
index 0000000000..9241ea59ce
--- /dev/null
+++ b/structure/decisions/ADR-0069-chat-to-responses-message-phase-inference.md
@@ -0,0 +1,12 @@
+# ADR-0069 — decision recorded under "Chat-to-Responses message phase inference"
+
+- Contract owner: [transports/responses.md](../transports/responses.md#chat-to-responses-message-phase-inference)
+
+## Decision record
+
+- 목적과 의도: Prevent Codex App from rendering one bridged Chat Completions answer as both live commentary and a second persisted final answer.
+- 기존 구현 및 제약 조건: openai-chat emits text deltas without phase, the bridge streamed them immediately, and whether text is pre-tool commentary or the terminal answer is unknowable until a later boundary arrives.
+- 검토한 주요 대안: Mark every delta final_answer; mark every delta commentary; buffer the entire answer before emitting; infer phase only when the message is finalized.
+- 선택한 방식: Keep the live added item provisional and infer commentary or final_answer at the authoritative close boundary, preserving explicit phases and item identity in done/completed output.
+- 다른 대안 대신 이 방식을 선택한 이유: Eager defaults misclassify either tool preambles or final answers, while full buffering removes live streaming; close-time inference provides correct persisted semantics without adding latency.
+- 장점, 단점 및 영향: Codex App receives a definitive phase for persisted bridged messages and avoids the duplicate-final rendering path; the provisional output_item.added event intentionally has no phase because its classification is not yet knowable.
diff --git a/structure/decisions/ADR-0070-same-provider-combo-quota-fallback.md b/structure/decisions/ADR-0070-same-provider-combo-quota-fallback.md
new file mode 100644
index 0000000000..6c8d20514b
--- /dev/null
+++ b/structure/decisions/ADR-0070-same-provider-combo-quota-fallback.md
@@ -0,0 +1,12 @@
+# ADR-0070 — decision recorded under "Same-provider combo quota fallback"
+
+- Contract owner: [transports/responses.md](../transports/responses.md#same-provider-combo-quota-fallback)
+
+## Decision record
+
+- 목적과 의도: Let an ordered combo recover when one model-specific Codex quota window is exhausted but another model on the same account remains usable.
+- 기존 구현 및 제약 조건: Account health is shared across models, and recording a reset-derived 429 before combo advancement rejected the later model locally.
+- 검토한 주요 대안: Make every quota cooldown model-scoped; ignore all combo 429 cooldowns; or defer only reset-derived cooldown recording for an eligible later same-provider failover target.
+- 선택한 방식: Use the narrow request-scoped deferral while retaining target cooldown and all explicit Retry-After/default account cooldown behavior.
+- 다른 대안 대신 이 방식을 선택한 이유: Reset timestamps identify quota windows rather than a literal account-wide retry instruction, but widening the exception would risk hot retries and provider abuse.
+- 장점, 단점 및 영향: Same-account model fallback works without weakening explicit upstream backoff; the account health map intentionally does not remember that one deferred reset-derived failure, while the combo target map does.
diff --git a/structure/decisions/ADR-0071-combo-streaming-commit-boundary.md b/structure/decisions/ADR-0071-combo-streaming-commit-boundary.md
new file mode 100644
index 0000000000..7143e89dce
--- /dev/null
+++ b/structure/decisions/ADR-0071-combo-streaming-commit-boundary.md
@@ -0,0 +1,12 @@
+# ADR-0071 — decision recorded under "Combo streaming commit boundary"
+
+- Contract owner: [transports/responses.md](../transports/responses.md#combo-streaming-commit-boundary)
+
+## Decision record
+
+- 목적과 의도: Recover a failover combo from a provider-local SSE or model-lifecycle failure only while replay is provably free of duplicate client output and tool calls.
+- 기존 구현 및 제약 조건: The parent committed every HTTP-200 child before reading its SSE body, while terminal stream errors were classified only later by logging; generic 410 responses stopped the chain.
+- 검토한 주요 대안: Retry every failed stream, buffer the complete turn, inspect only HTTP status, or preflight a bounded prefix until an explicit output/terminal boundary.
+- 선택한 방식: Put the one-reader bounded preflight in a dedicated module, commit on any non-control event, and treat only explicit model-lifecycle 410 evidence as target-local.
+- 다른 대안 대신 이 방식을 선택한 이유: Replaying after output can duplicate text or tools, full-turn buffering destroys streaming and grows memory, and making every 410 retryable hides caller/application errors.
+- 장점, 단점 및 영향: Zero-output provider failures can reach a healthy target with ordered receipts and cooldown; ambiguous or oversized pre-output streams keep the current fail-closed behavior instead of consuming unbounded memory.
diff --git a/structure/decisions/ADR-0072-transport-inventory.md b/structure/decisions/ADR-0072-transport-inventory.md
new file mode 100644
index 0000000000..96f45745ae
--- /dev/null
+++ b/structure/decisions/ADR-0072-transport-inventory.md
@@ -0,0 +1,12 @@
+# ADR-0072 — decision recorded under "Transport inventory"
+
+- Contract owner: [transports/inventory.md](../transports/inventory.md#transport-inventory)
+
+## Decision record
+
+- 목적과 의도: Keep reactive OAuth 429 recovery available without silently enabling proactive account-routing policy the operator switched off.
+- 기존 구현 및 제약 조건: #3495 made reactive recovery presence-driven, but a disabled Anthropic pool still consulted its dormant strategy on the reactive path, and a per-provider `oauthAccountFailover.enabled: true` could no longer beat a global `false`.
+- 검토한 주요 대안: Restore the old all-or-nothing enable flag; leave the merged behavior and document the gaps; or keep the reactive/proactive split and repair the exact policy boundaries.
+- 선택한 방식: Keep presence-driven reactive recovery, apply proactive precedence only before dispatch, and use quota ordering for disabled-pool Anthropic recovery.
+- 다른 대안 대신 이 방식을 선택한 이유: This preserves the merged product decision without letting disabled proactive settings influence a retry, and it restores the published narrow-over-broad precedence in both directions.
+- 장점, 단점 및 영향: 429 recovery stays automatic for operators with multiple eligible accounts; operators who require no automatic account switch must keep one eligible account, which the GUI and public docs state explicitly.
diff --git a/structure/decisions/ADR-0073-authentication-boundaries.md b/structure/decisions/ADR-0073-authentication-boundaries.md
new file mode 100644
index 0000000000..9c78ec1a0f
--- /dev/null
+++ b/structure/decisions/ADR-0073-authentication-boundaries.md
@@ -0,0 +1,12 @@
+# ADR-0073 — decision recorded under "Authentication boundaries"
+
+- Contract owner: [gui-and-management-api.md](../gui-and-management-api.md#authentication-boundaries)
+
+## Decision record
+
+- 목적과 의도: Keep a lower-privileged local process from collecting the management bearer by impersonating `/healthz` on an unused port.
+- 기존 구현 및 제약 조건: Liveness must remain public and backward-compatible, but its service string and reported PID are assertions made by the listener itself.
+- 검토한 주요 대안: Require only a runtime source and non-null PID; stop showing account health; authenticate the listener with a protected per-process challenge secret.
+- 선택한 방식: Store a random secret in the mode-protected runtime record and use method/path/PID/port-bound HMAC capabilities for the two CLI health reads, so the CLI sends no reusable Authorization value.
+- 다른 대안 대신 이 방식을 선택한 이유: PID and command-line checks are not cryptographic listener identity, while removing live account health would regress diagnostics unnecessarily.
+- 장점, 단점 및 영향: The long-lived token never reaches a listener without the runtime secret; an old running proxy remains visible but cannot provide detailed CLI account health until restarted on the new version.
diff --git a/structure/decisions/ADR-0074-api-ownership.md b/structure/decisions/ADR-0074-api-ownership.md
new file mode 100644
index 0000000000..f4e30b0dcd
--- /dev/null
+++ b/structure/decisions/ADR-0074-api-ownership.md
@@ -0,0 +1,12 @@
+# ADR-0074 — decision recorded under "API ownership"
+
+- Contract owner: [gui-and-management-api.md](../gui-and-management-api.md#api-ownership)
+
+## Decision record
+
+- 목적과 의도: Distinguish a healthy process from a continuation spill writer that is repeatedly failing, especially on Windows where the ACL publication lane is asynchronous.
+- 기존 구현 및 제약 조건: `/healthz` intentionally reports liveness only, while `spillWriteFailures` was cumulative and discarded the failure class, event time, and recovery boundary.
+- 검토한 주요 대안: Make `/healthz` fail on a spill error; publish raw error messages; expose a fixed classified health projection only on the authenticated memory route.
+- 선택한 방식: Keep liveness unchanged and add a consecutive streak, fixed error class, and last failure/success timestamps to the existing authenticated response-state metrics.
+- 다른 대안 대신 이 방식을 선택한 이유: One failed cache demotion must not restart or remove an otherwise serving proxy, and raw filesystem errors can disclose user paths while still failing to show whether the next write recovered.
+- 장점, 단점 및 영향: Operators can identify accumulating failures and same-process recovery without sensitive text. The status is process-local and resets to `initial` on restart, so historical diagnosis still requires external metric collection.
diff --git a/structure/decisions/ADR-0075-startup-safety.md b/structure/decisions/ADR-0075-startup-safety.md
new file mode 100644
index 0000000000..385abf2fea
--- /dev/null
+++ b/structure/decisions/ADR-0075-startup-safety.md
@@ -0,0 +1,12 @@
+# ADR-0075 — decision recorded under "Startup safety"
+
+- Contract owner: [gui-and-management-api.md](../gui-and-management-api.md#startup-safety)
+
+## Decision record
+
+- 목적과 의도: Keep a refused fresh Windows service install from stopping a working proxy and removing managed Codex routing.
+- 기존 구현 및 제약 조건: The generic installer stopped service managers and the standalone proxy before the first scheduler create attempt; the Dashboard UAC path depended on assets produced by that already-destructive failure.
+- 검토한 주요 대안: Reject every non-elevated caller up front, restart and re-inject after failure, snapshot every runtime/config artifact for rollback, or separate registration approval from the destructive commit.
+- 선택한 방식: When scheduler absence is proven, create but do not run the owned registration from a temporary XML first; cleanup and canonical asset publication begin only after registration succeeds.
+- 다른 대안 대신 이 방식을 선택한 이유: An early rejection breaks Dashboard UAC, while a best-effort restart cannot prove that manager, proxy, and routing state were restored. The two-phase boundary makes denial/cancellation a real pre-commit failure.
+- 장점, 단점 및 영향: Fresh-install UAC failure preserves the live proxy and routing. Failures after registration remain explicit partial-install cases, and existing/conflicting scheduler recovery remains conservative until exact prior-state restoration is available.
diff --git a/structure/decisions/ADR-0076-startup-safety.md b/structure/decisions/ADR-0076-startup-safety.md
new file mode 100644
index 0000000000..cf764c64ba
--- /dev/null
+++ b/structure/decisions/ADR-0076-startup-safety.md
@@ -0,0 +1,12 @@
+# ADR-0076 — decision recorded under "Startup safety"
+
+- Contract owner: [gui-and-management-api.md](../gui-and-management-api.md#startup-safety)
+
+## Decision record
+
+- 목적과 의도: Make Windows scheduler installation recovery work on non-English systems without broadening the commands that may request UAC.
+- 기존 구현 및 제약 조건: Access-denied classification parsed English and German stderr. Chinese OEM output decoded as UTF-8 became mojibake, so the fixed scheduler-create failure lost its machine marker and the dashboard could not select its existing elevation transaction.
+- 검토한 주요 대안: Add translations and code-page decoders; elevate every scheduler failure; always launch installation elevated; or combine a native effective-token probe with the already fixed command shape and exit status.
+- 선택한 방식: Preserve text detection, then use the native token probe only for status-1 creation of the owned `opencodex-proxy` XML task. Unknown probe results fail closed.
+- 다른 대안 대신 이 방식을 선택한 이유: Windows localization and OEM code pages are open-ended, while the token state and owned command shape are stable security signals already bounded by the elevated transaction protocol.
+- 장점, 단점 및 영향: Non-English users receive stable guidance and dashboard UAC recovery. A non-permission status-1 failure from the exact owned command may be retried once elevated, but foreign operations cannot cross the elevation boundary and the elevated transaction still fails closed.
diff --git a/structure/decisions/ADR-0077-startup-safety.md b/structure/decisions/ADR-0077-startup-safety.md
new file mode 100644
index 0000000000..dd39473acc
--- /dev/null
+++ b/structure/decisions/ADR-0077-startup-safety.md
@@ -0,0 +1,12 @@
+# ADR-0077 — decision recorded under "Startup safety"
+
+- Contract owner: [gui-and-management-api.md](../gui-and-management-api.md#startup-safety)
+
+## Decision record
+
+- 목적과 의도: Prevent a crashed dashboard update worker from permanently blocking every later update.
+- 기존 구현 및 제약 조건: The job file was written before spawn, the returned PID was not persisted, and active status had no liveness or freshness check.
+- 검토한 주요 대안: Require manual deletion; expire all jobs by age; or persist PID and use age only for legacy no-PID records.
+- 선택한 방식: Persist and verify PID liveness, with a ten-minute fallback only for legacy records.
+- 다른 대안 대신 이 방식을 선택한 이유: It recovers known-dead workers promptly without allowing a second installer beside a long-running live worker.
+- 장점, 단점 및 영향: New jobs self-recover after worker death and spawn failures become visible; legacy crashes may remain blocked for up to ten minutes.
diff --git a/structure/decisions/ADR-0078-usage-accounting.md b/structure/decisions/ADR-0078-usage-accounting.md
new file mode 100644
index 0000000000..8a30ff014c
--- /dev/null
+++ b/structure/decisions/ADR-0078-usage-accounting.md
@@ -0,0 +1,12 @@
+# ADR-0078 — decision recorded under "Usage accounting"
+
+- Contract owner: [gui-and-management-api.md](../gui-and-management-api.md#usage-accounting)
+
+## Decision record
+
+- 목적과 의도: Explain missing main-account quota without confusing a working login with a successful WHAM read.
+- 기존 구현 및 제약 조건: HTTP failures and body/transport exceptions returned identical null metadata; existing authentication and freshness policy must remain unchanged.
+- 검토한 주요 대안: Copy raw errors, infer plan/quota, reuse stale evidence, or add a bounded diagnostic outcome.
+- 선택한 방식: Carry a non-persisted fixed category and optional numeric HTTP status through the existing management and CLI read paths.
+- 다른 대안 대신 이 방식을 선택한 이유: It gives reporters actionable evidence without disclosing payloads, changing permissions, or introducing another cache.
+- 장점, 단점 및 영향: Main-account failures become distinguishable; root-cause repair and pool diagnostics remain separate work, and clients must tolerate an absent field.
diff --git a/structure/decisions/ADR-0079-usage-accounting.md b/structure/decisions/ADR-0079-usage-accounting.md
new file mode 100644
index 0000000000..cb87d1113a
--- /dev/null
+++ b/structure/decisions/ADR-0079-usage-accounting.md
@@ -0,0 +1,12 @@
+# ADR-0079 — decision recorded under "Usage accounting"
+
+- Contract owner: [gui-and-management-api.md](../gui-and-management-api.md#usage-accounting)
+
+## Decision record
+
+- 목적과 의도: Keep dashboard and management requests responsive as `usage.jsonl` grows.
+- 기존 구현 및 제약 조건: The append-only JSONL file remains the durable source of truth and may be truncated or replaced. A tail-only byte/row bound kept memory finite but made historical totals incomplete on busy installations; arbitrary in-place historical edits cannot be detected without rereading the prefix.
+- 검토한 주요 대안: Raise the byte/row caps, retain normalized rows, maintain a second database, or stream the complete ledger into compact accumulators and cache only revision-keyed summaries.
+- 선택한 방식: Stream the complete ledger in fixed 1 MiB chunks for a cold rebuild, retain only compact aggregate state plus an LF/digest checkpoint, fold verified append suffixes atomically, share concurrent work, yield during parsing, and poll usage separately at a slower cadence.
+- 다른 대안 대신 이 방식을 선택한 이유: It restores complete historical aggregation without making correctness depend on an operator-sized read limit, retaining every parsed row, or introducing a second persistence format.
+- 장점, 단점 및 영향: Unchanged queries are cheap, normal refreshes read only appended bytes, and memory stays bounded. Cold starts and explicit invalidations still consume file-size-proportional IO/CPU. A same-inode historical rewrite outside the trailing checkpoint requires replacement, truncation, or restart to force that cold rebuild.
diff --git a/structure/decisions/ADR-0080-github-pages.md b/structure/decisions/ADR-0080-github-pages.md
new file mode 100644
index 0000000000..7528b2afc0
--- /dev/null
+++ b/structure/decisions/ADR-0080-github-pages.md
@@ -0,0 +1,12 @@
+# ADR-0080 — decision recorded under "GitHub Pages"
+
+- Contract owner: [ops/docs-and-release.md](../ops/docs-and-release.md#github-pages)
+
+## Decision record
+
+- 목적과 의도: Serve the public documentation from the memorable first-party `opencodex.me` domain.
+- 기존 구현 및 제약 조건: The project Pages site was built for `lidge-jun.github.io/opencodex`, so Astro emitted a `/opencodex` base path that returns 404 under a root custom domain.
+- 검토한 주요 대안: Keep the GitHub project URL as canonical; redirect the custom domain through Cloudflare; configure the custom domain directly on GitHub Pages and build for the domain root.
+- 선택한 방식: Keep GitHub Actions Pages hosting, configure `opencodex.me` as the repository custom domain, publish root-relative assets and routes, and retain the default GitHub URL only as GitHub's automatic redirect.
+- 다른 대안 대신 이 방식을 선택한 이유: Direct Pages hosting preserves the existing deployment and HTTPS lifecycle without adding a second proxy or redirect service.
+- 장점, 단점 및 영향: Public links and canonical metadata become stable and branded. DNS and the Pages custom-domain setting are now deployment dependencies, and old hardcoded `/opencodex` links must not be reintroduced.
diff --git a/structure/decisions/ADR-0081-container-deployment-recipe.md b/structure/decisions/ADR-0081-container-deployment-recipe.md
new file mode 100644
index 0000000000..b93174b49c
--- /dev/null
+++ b/structure/decisions/ADR-0081-container-deployment-recipe.md
@@ -0,0 +1,12 @@
+# ADR-0081 — decision recorded under "Container deployment recipe"
+
+- Contract owner: [ops/docs-and-release.md](../ops/docs-and-release.md#container-deployment-recipe)
+
+## Decision record
+
+- 목적과 의도: Document a reproducible container topology without silently creating an official image channel.
+- 기존 구현 및 제약 조건: The documentation recipe was not executable from the repository root, file-backed Compose secret ownership varies by implementation, and no registry workflow, scanner, SBOM/signing chain, or image rollback policy exists.
+- 검토한 주요 대안: Publish an official image; keep only copied documentation snippets; ship a maintained source recipe with a volume-backed stdin bootstrap.
+- 선택한 방식: Maintain the root source-build recipe, persist the owner-only token in the state volume, publish only `10100`, and leave registry publication out of scope.
+- 다른 대안 대신 이 방식을 선택한 이유: A runnable source recipe can be tested and reviewed without claiming provenance and operational controls the project does not provide.
+- 장점, 단점 및 영향: Compose users get a reproducible non-root deployment and safe first-run secret path; operators still own image builds, upgrades, external TLS/tailnet management, and rollout policy.
diff --git a/structure/decisions/ADR-0082-windows-service-wrapper-and-incomplete-updates.md b/structure/decisions/ADR-0082-windows-service-wrapper-and-incomplete-updates.md
new file mode 100644
index 0000000000..1f9c2ea038
--- /dev/null
+++ b/structure/decisions/ADR-0082-windows-service-wrapper-and-incomplete-updates.md
@@ -0,0 +1,12 @@
+# ADR-0082 — decision recorded under "Windows service wrapper and incomplete updates"
+
+- Contract owner: [ops/docs-and-release.md](../ops/docs-and-release.md#windows-service-wrapper-and-incomplete-updates)
+
+## Decision record
+
+- 목적과 의도: Prevent a failed npm replacement from making the Task Scheduler wrapper retry missing package files forever.
+- 기존 구현 및 제약 조건: The wrapper deliberately restarts a proxy after runtime crashes, but an absent baked Bun or CLI path cannot recover inside that process. Current updater preflight and stop-first behavior reduce replacement risk but do not provide a transactional restore of npm's package tree and global launchers.
+- 검토한 주요 대안: Keep unconditional five-second retries, add a generic crash ceiling, restore npm directories in-place, or classify only proven missing executable paths as terminal.
+- 선택한 방식: Check the baked Bun and CLI paths before every spawn; log one actionable incomplete-install message and exit with code 3 when either is absent. Preserve the existing retry loop for a child that actually launched and then failed.
+- 다른 대안 대신 이 방식을 선택한 이유: A generic retry ceiling can stop a service after unrelated intermittent crashes, while copying a package directory without matching npm shims, ownership, and lock guarantees is not a safe rollback.
+- 장점, 단점 및 영향: File-less package skeletons no longer produce unbounded service logs or restart churn. The wrapper still recovers ordinary proxy crashes, but repairing an incomplete npm install remains an explicit reinstall plus `ocx service repair` operation until a verified staged-update design exists.
diff --git a/structure/decisions/ADR-0083-maintenance-governance.md b/structure/decisions/ADR-0083-maintenance-governance.md
new file mode 100644
index 0000000000..1cd9635a23
--- /dev/null
+++ b/structure/decisions/ADR-0083-maintenance-governance.md
@@ -0,0 +1,12 @@
+# ADR-0083 — decision recorded under "Maintenance governance"
+
+- Contract owner: [ops/docs-and-release.md](../ops/docs-and-release.md#maintenance-governance)
+
+## Decision record
+
+- 목적과 의도: Make project ownership and review authority discoverable without exposing credentials or treating a documentation file as an access-control mechanism.
+- 기존 구현 및 제약 조건: Contribution and security docs referred to maintainers generically, while the repository had no maintainer roster or CODEOWNERS policy. GitHub permissions can change independently of the source tree.
+- 검토한 주요 대안: Keep the roster only in GitHub settings; introduce a larger standalone governance charter; list raw GitHub permission levels in the repository.
+- 선택한 방식: Add a concise maintainer roster and merge policy, use CODEOWNERS for review routing, and keep actual permission state authoritative in GitHub settings.
+- 다른 대안 대신 이 방식을 선택한 이유: A two-maintainer project needs clear ownership and sensitive-path review rules but does not yet need a separate governance framework.
+- 장점, 단점 및 영향: Contributors can identify reviewers and merge expectations directly from the repository. The roster must be updated when responsibilities change, and CODEOWNERS still requires branch-protection configuration to enforce approvals.
diff --git a/structure/decisions/ADR-0084-public-provider-contract.md b/structure/decisions/ADR-0084-public-provider-contract.md
new file mode 100644
index 0000000000..26c1a5114e
--- /dev/null
+++ b/structure/decisions/ADR-0084-public-provider-contract.md
@@ -0,0 +1,12 @@
+# ADR-0084 — decision recorded under "Public provider contract"
+
+- Contract owner: [providers/openai-tiers.md](../providers/openai-tiers.md#public-provider-contract)
+
+## Decision record
+
+- 목적과 의도: Let public Responses clients use the Codex-login route without one unsupported prompt-cache extension failing the whole turn.
+- 기존 구현 및 제약 조건: Parsing already preserves unknown top-level fields in `_rawBody`, and the canonical backend rejects `prompt_cache_options`; API-key and custom providers may accept the same field.
+- 검토한 주요 대안: Add the field to the Zod schema; strip it for every Responses provider; translate it to a legacy retention hint; remove it only at the canonical destination boundary.
+- 선택한 방식: Keep parser passthrough unchanged and strip the caller field only after `isCanonicalOpenAiForwardProvider` succeeds.
+- 다른 대안 대신 이 방식을 선택한 이유: Schema admission does not change `_rawBody`, global stripping would remove supported public API behavior, and translation would invent cache policy.
+- 장점, 단점 및 영향: VS Code and other public-shape clients avoid the canonical backend rejection while API-key/custom routes retain their wire options; canonical callers cannot request this cache option through OpenCodex.
diff --git a/structure/decisions/ADR-0085-public-provider-contract.md b/structure/decisions/ADR-0085-public-provider-contract.md
new file mode 100644
index 0000000000..bfecc5e73a
--- /dev/null
+++ b/structure/decisions/ADR-0085-public-provider-contract.md
@@ -0,0 +1,22 @@
+# ADR-0085 — decision recorded under "Public provider contract"
+
+- Contract owner: [providers/openai-tiers.md](../providers/openai-tiers.md#public-provider-contract)
+
+## Decision record
+
+- 목적과 의도: Keep Desktop reconnects on the account selected for the App task without persisting
+  or exposing its session and thread identifiers.
+- 기존 구현 및 제약 조건: Pool affinity used only `x-codex-parent-thread-id`; Desktop requests can
+  omit it while stable `session-id` and `thread-id` headers remain available. Exact account
+  selectors must stay outside automatic Pool affinity.
+- 검토한 주요 대안: Leave reconnects unbound, persist a plain hash, bind from either header alone,
+  delete App turn metadata, or derive one process-local key from the complete pair.
+- 선택한 방식: Preserve the parent-thread key when present; otherwise HMAC the two bounded headers
+  under a random per-process key and carry that opaque value through selection, subagent preview,
+  and outcome handling.
+- 다른 대안 대신 이 방식을 선택한 이유: A complete pair avoids weak partial identities, a
+  process-local HMAC prevents durable correlation or dictionary recovery, and no upstream metadata
+  needs to be mutated before the first-403 cause is proven.
+- 장점, 단점 및 영향: Reconnects stop rotating among Pool accounts and failure accounting clears
+  the correct binding. Affinity intentionally resets on process restart, and requests missing either
+  component retain the prior unbound behavior.
diff --git a/structure/decisions/ADR-0086-public-provider-contract.md b/structure/decisions/ADR-0086-public-provider-contract.md
new file mode 100644
index 0000000000..9bc3354fa2
--- /dev/null
+++ b/structure/decisions/ADR-0086-public-provider-contract.md
@@ -0,0 +1,18 @@
+# ADR-0086 — decision recorded under "Public provider contract"
+
+- Contract owner: [providers/openai-tiers.md](../providers/openai-tiers.md#public-provider-contract)
+
+## Decision record
+
+- 목적과 의도: Keep an explicit healthy main selection from being replaced by an exhausted stored
+  account merely because the client supplied main through a request-owned keyring bearer.
+- 기존 구현 및 제약 조건: Request-owned credentials are deliberately excluded from stored-account
+  entitlement discovery, but shared-state preservation interpreted that exclusion as a dead main login.
+- 검토한 주요 대안: Persist the caller credential, read the physical main token for identity, ignore
+  the manual pin, or validate the caller independently before stored-Pool selection.
+- 선택한 방식: Use only the effective pin, pause state, cached quota, and the caller credential's own
+  gated-model check; synthesize shared-state liveness only while main stays request-ineligible.
+- 다른 대안 대신 이 방식을 선택한 이유: It preserves credential isolation and explicit operator
+  intent without admitting an unentitled model or binding an ephemeral bearer into durable Pool state.
+- 장점, 단점 및 영향: Healthy main pins survive keyring requests and model-only detours; cached quota
+  remains the only proactive drain evidence available without crossing the physical credential boundary.
diff --git a/structure/decisions/ADR-0087-model-and-wire-identity.md b/structure/decisions/ADR-0087-model-and-wire-identity.md
new file mode 100644
index 0000000000..e4bc8ac193
--- /dev/null
+++ b/structure/decisions/ADR-0087-model-and-wire-identity.md
@@ -0,0 +1,19 @@
+# ADR-0087 — decision recorded under "Model and wire identity"
+
+- Contract owner: [providers/openai-tiers.md](../providers/openai-tiers.md#model-and-wire-identity)
+
+## Decision record
+
+- 목적과 의도: Preserve the account-gated Daybreak UX while avoiding shard-dependent selector
+  rejection and the unsupported prompt-cache retention parameter.
+- 기존 구현 및 제약 조건: The authenticated roster grants Daybreak, but live successful
+  responses report `gpt-5.6-sol`; the selector can still fail eight consecutive times.
+- 검토한 주요 대안: Increase retries indefinitely, hide Daybreak entirely, or canonicalize only
+  the credential-bearing wire model after entitlement selection.
+- 선택한 방식: Keep Daybreak for visibility and account authorization, then send the stable
+  serving id and remove only the unsupported optional retention hint.
+- 다른 대안 대신 이 방식을 선택한 이유: It keeps fail-closed entitlement checks and avoids
+  unbounded duplicate requests while preserving the user-facing model choice.
+- 장점, 단점 및 영향: Requests become deterministic and cheaper; this relies on the serving id
+  observed from successful upstream responses and must be revisited if the roster exposes a
+  first-class wire id later.
diff --git a/structure/decisions/ADR-0088-model-and-wire-identity.md b/structure/decisions/ADR-0088-model-and-wire-identity.md
new file mode 100644
index 0000000000..aac68824a5
--- /dev/null
+++ b/structure/decisions/ADR-0088-model-and-wire-identity.md
@@ -0,0 +1,21 @@
+# ADR-0088 — decision recorded under "Model and wire identity"
+
+- Contract owner: [providers/openai-tiers.md](../providers/openai-tiers.md#model-and-wire-identity)
+
+## Decision record
+
+- 목적과 의도: Prevent account-gated native models from being shown or dispatched through a
+  ChatGPT account that upstream does not authorize.
+- 기존 구현 및 제약 조건: A static global Daybreak row solved clean-install discovery for
+  entitled accounts, but Pool accounts can hold different grants and Codex's injected catalog does
+  not refresh itself.
+- 검토한 주요 대안: Infer grants from plan labels, learn only from prompt failures, bind Daybreak
+  permanently to main, or rewrite the wire id to `gpt-5.6-sol`.
+- 선택한 방식: Share bounded authenticated per-account model-roster evidence between catalog sync,
+  `/v1/models`, and Pool auth selection.
+- 다른 대안 대신 이 방식을 선택한 이유: Plan labels and account position do not prove a grant;
+  failure-only learning wastes a turn; permanent main binding rejects valid secondary grants; wire
+  rewriting changes the requested product identity.
+- 장점, 단점 및 영향: Entitled accounts retain clean-install discovery while unentitled accounts
+  never receive the gated dispatch. A cold gated request may pay one bounded roster fetch per
+  account, and an unavailable discovery temporarily hides the model rather than guessing.
diff --git a/structure/decisions/ADR-0089-process-local-affinity-diagnostics.md b/structure/decisions/ADR-0089-process-local-affinity-diagnostics.md
new file mode 100644
index 0000000000..227ac4ffa2
--- /dev/null
+++ b/structure/decisions/ADR-0089-process-local-affinity-diagnostics.md
@@ -0,0 +1,12 @@
+# ADR-0089 — decision recorded under "Process-local affinity diagnostics"
+
+- Contract owner: [providers/openai-tiers.md](../providers/openai-tiers.md#process-local-affinity-diagnostics)
+
+## Decision record
+
+- 목적과 의도: Identify which combined Codex affinity values survive a Plus-to-K12 credential substitution without collecting private thread or account data.
+- 기존 구현 및 제약 조건: Pool auth intentionally copies the curated caller metadata and replaces only authorization plus chatgpt-account-id. Individual header probes did not reproduce the workspace denial, while raw captures would expose account-bound identifiers.
+- 검토한 주요 대안: Delete all affinity metadata; log raw values; persist ordinary hashes; perform automatic header-ablation retries; or emit process-local keyed equality evidence only when provider debug is enabled.
+- 선택한 방식: Emit bounded pre-stream diagnostics with a random per-process HMAC key, a fixed non-credential header allowlist, known turn-field summaries, and no request mutation.
+- 다른 대안 대신 이 방식을 선택한 이유: Equality across two requests in one run is enough to narrow the incompatible combination; process-local HMACs prevent durable correlation and make offline guessing useless, while observation-only capture cannot change production semantics.
+- 장점, 단점 및 영향: Maintainers can compare a Plus success and exact-K12 denial safely. Tags cannot be compared across restarts, and the diagnostic does not itself identify an upstream policy rule or fix the rejection.
diff --git a/structure/decisions/ADR-0090-hermes-model-capabilities.md b/structure/decisions/ADR-0090-hermes-model-capabilities.md
new file mode 100644
index 0000000000..c44a227cbf
--- /dev/null
+++ b/structure/decisions/ADR-0090-hermes-model-capabilities.md
@@ -0,0 +1,12 @@
+# ADR-0090 — decision recorded under "Hermes Model Capabilities"
+
+- Contract owner: [clients/integrations.md](../clients/integrations.md#hermes-model-capabilities)
+
+## Decision record
+
+- 목적과 의도: Preserve catalog-backed image routing when Hermes uses OpenCodex as a custom provider.
+- 기존 구현 및 제약 조건: A string array preserved model selection but normalized to empty metadata in Hermes, while OpenCodex has authoritative text/image/audio facts but no video fact.
+- 검토한 주요 대안: Keep the array; mark every model vision-capable; infer video from model names; emit a per-model metadata map from declared modalities.
+- 선택한 방식: Emit a stable per-model map and include only the `supports_vision` boolean that the catalog can prove.
+- 다른 대안 대신 이 방식을 선택한 이유: The map is the Hermes-supported capability boundary, while guesses would misroute attachments or advertise unsupported video.
+- 장점, 단점 및 영향: Vision-capable custom models route correctly and text-only rows stay explicit; unknown rows remain unknown, and video routing waits for authoritative source metadata.
diff --git a/structure/decisions/ADR-0091-ownership-axes.md b/structure/decisions/ADR-0091-ownership-axes.md
new file mode 100644
index 0000000000..5609670147
--- /dev/null
+++ b/structure/decisions/ADR-0091-ownership-axes.md
@@ -0,0 +1,12 @@
+# ADR-0091 — decision recorded under "Ownership Axes"
+
+- Contract owner: [clients/integrations.md](../clients/integrations.md#ownership-axes)
+
+## Decision record
+
+- 목적과 의도: Treat JSON object-key order as formatting while retaining safe ownership proof across upgrades.
+- 기존 구현 및 제약 조건: Existing records contain order-sensitive hashes, and replacing their hash format in place would make every installed integration look foreign-edited.
+- 검토한 주요 대안: Replace the hash format globally; ignore key order only for ZCode; store a semantic companion beside the existing exact hash.
+- 선택한 방식: Preserve the exact hashes for compatibility and add object-key-independent semantic companions to new records, with a bounded desired-contribution fallback for old records.
+- 다른 대안 대신 이 방식을 선택한 이유: A global replacement cannot validate old records, while a ZCode-only exception would leave the shared JSON ownership rule inconsistent.
+- 장점, 단점 및 영향: New records tolerate key normalization even across catalog refreshes; old records recover when the recorded catalog is still reconstructible, and ambiguous old-record drift remains fail-closed.
diff --git a/structure/decisions/ADR-0092-zcode-runtime-metadata.md b/structure/decisions/ADR-0092-zcode-runtime-metadata.md
new file mode 100644
index 0000000000..3b1ced0490
--- /dev/null
+++ b/structure/decisions/ADR-0092-zcode-runtime-metadata.md
@@ -0,0 +1,12 @@
+# ADR-0092 — decision recorded under "ZCode Runtime Metadata"
+
+- Contract owner: [clients/integrations.md](../clients/integrations.md#zcode-runtime-metadata)
+
+## Decision record
+
+- 목적과 의도: Allow ZCode's documented runtime normalization without turning genuine provider or connection edits into refreshable drift.
+- 기존 구현 및 제약 조건: The classifier hashed the whole `provider.opencodex` fragment. That was safe for ordinary JSON clients but made every ZCode save a permanent foreign edit. Refresh and disable both depend on the same ownership proof.
+- 검토한 주요 대안: Ignore all model metadata; compare only the provider connection envelope; hard-code a ZCode branch directly in `state.ts`; store explicit operation-scoped mutable paths and a protected fingerprint.
+- 선택한 방식: Keep the strict generated contribution hash, add a separate protected fingerprint, and persist the exact ZCode-derived paths with each ownership record through a client-scoped policy module.
+- 다른 대안 대신 이 방식을 선택한 이유: Ignoring all model metadata would allow user model edits to be overwritten. Comparing only the connection envelope would stop protecting model membership and capabilities. A state-only special case would disagree with writer behavior. Operation-scoped paths preserve the original grant across later catalog changes.
+- 장점, 단점 및 영향: Normal ZCode saves become refreshable, connection edits still fail closed, and later catalog refreshes remain possible. Legacy records with simultaneous catalog drift still require a conservative manual recovery because the old schema did not store enough evidence.
diff --git a/structure/decisions/ADR-0093-moonshot-ref-with-siblings-normalization.md b/structure/decisions/ADR-0093-moonshot-ref-with-siblings-normalization.md
new file mode 100644
index 0000000000..576eddc476
--- /dev/null
+++ b/structure/decisions/ADR-0093-moonshot-ref-with-siblings-normalization.md
@@ -0,0 +1,31 @@
+# ADR-0093 — decision recorded under "Moonshot `$ref`-with-siblings normalization"
+
+- Contract owner: [adapters/registry.md](../adapters/registry.md#moonshot-ref-with-siblings-normalization)
+
+## Decision record
+
+- 목적과 의도: Codex가 내보내는 `$ref` + 형제 키워드 스키마를 Moonshot이 받아들이는 형태로
+  바꾸되, 도구가 실제로 요구하는 제약을 잃지 않는다.
+- 기존 구현 및 제약 조건: JSON Schema 2020-12에서 `$ref`는 in-place applicator라 형제
+  키워드와 함께 적용된다. Moonshot은 이를 거부하므로 참조 대상을 노드 아래로 인라인해야 하고,
+  재귀 스키마는 유한해야 하며, 어댑터는 요청 경로에 있으므로 지연이 그대로 사용자에게 간다.
+- 검토한 주요 대안: (1) 형제 키워드를 버리고 순수 `$ref`만 남긴다. (2) 참조를 인라인하되
+  형제 키워드가 대상을 덮어쓴다. (3) 인라인하되 집합형 어서션은 합집합으로 합치고 나머지는
+  좁히는 쪽이 이긴다. (4) `allOf`로 감싼다.
+- 선택한 방식: (3). `required`는 합집합, `properties`는 병합, 나머지 키워드는 노드가 이긴다.
+  해석 불가능한 참조는 순수 `$ref`로 남기고, 깊이·노드·확장 예산을 각각 둔다.
+- 다른 대안 대신 이 방식을 선택한 이유: (1)은 노드가 좁힌 제약을 통째로 버린다. (2)는 대상이
+  요구하던 `a`를 형제의 `b`가 덮어써서, 양쪽 어느 쪽도 요청하지 않은 더 약한 계약을 조용히
+  내보냈다 — 리뷰가 지적한 정확한 결함이다. (4)는 Moonshot이 `allOf`를 어떻게 다루는지
+  확인된 근거가 없어 검증되지 않은 가정을 계약으로 만든다.
+- 장점, 단점 및 영향: 도구 계약이 보존된 채 Moonshot을 통과한다. 인라인은 대상을 복제하므로
+  큰 정의를 여러 노드가 참조하면 출력이 커질 수 있고, 예산이 소진되면 해당 노드는 빈 객체나
+  순수 `$ref`로 닫힌다 — 약해진 스키마를 절반만 내보내는 것보다 낫다. Moonshot 계열
+  `openai-chat` baseUrl에만 적용되고 다른 provider는 손대지 않는다.
+
+## Why three budgets
+
+예산은 세 가지다. 확장 횟수만으로는 참조가 하나도 없는 깊은 스키마를 막지 못해서, 깊이와
+노드 수를 따로 둔다 — `google-tool-schema.ts`가 이미 쓰는 형태다. 두 가드 모두 제거했을 때
+실제로 red가 되는지 확인했고, 예산을 풀면 20k 깊이에서 `RangeError: Maximum call stack size
+exceeded`가 난다.
diff --git a/structure/decisions/ADR-0094-canonical-forward-continuation-extensions.md b/structure/decisions/ADR-0094-canonical-forward-continuation-extensions.md
new file mode 100644
index 0000000000..ee85fdb3e6
--- /dev/null
+++ b/structure/decisions/ADR-0094-canonical-forward-continuation-extensions.md
@@ -0,0 +1,12 @@
+# ADR-0094 — decision recorded under "Canonical forward continuation extensions"
+
+- Contract owner: [adapters/compatibility-contracts.md](../adapters/compatibility-contracts.md#canonical-forward-continuation-extensions)
+
+## Decision record
+
+- 목적과 의도: Preserve Posit Assistant tool continuation semantics while preventing canonical ChatGPT Codex forwarding from sending client-only cache markers or unresolvable stored-item references.
+- 기존 구현 및 제약 조건: The existing `store: false` sanitizer removed item ids but left `item_reference` shells, and no bounded pass recognized markers nested inside content; tool `call_id` pairing and reasoning effort are continuation-critical.
+- 검토한 주요 대안: Strip the extensions for every Responses destination; delete only reference ids; expand references from local state; or normalize only the canonical forward destination with bounded recursive marker removal.
+- 선택한 방식: Apply the bounded marker pass only to canonical forward `input`, and omit `item_reference` rows only when `store` is exactly `false`.
+- 다른 대안 대신 이 방식을 선택한 이유: Public and custom gateways may implement these extensions, while id-only deletion creates an invalid reference shell and local expansion would invent unavailable persistence authority.
+- 장점, 단점 및 영향: Posit continuations retain tool pairing and reasoning controls without widening public-provider behavior; hostile nesting fails closed to the original input, so an over-limit request may still be rejected upstream rather than partially rewritten.
diff --git a/structure/decisions/ADR-0095-canonical-forward-continuation-extensions.md b/structure/decisions/ADR-0095-canonical-forward-continuation-extensions.md
new file mode 100644
index 0000000000..841fadc3f2
--- /dev/null
+++ b/structure/decisions/ADR-0095-canonical-forward-continuation-extensions.md
@@ -0,0 +1,12 @@
+# ADR-0095 — decision recorded under "Canonical forward continuation extensions"
+
+- Contract owner: [adapters/compatibility-contracts.md](../adapters/compatibility-contracts.md#canonical-forward-continuation-extensions)
+
+## Decision record
+
+- 목적과 의도: Make provider compatibility explicit and machine-readable before larger routing or Responses refactors.
+- 기존 구현 및 제약 조건: Adapter-wide conformance tests already protect tool translation, and Compatibility Lab owns broader protocol evidence, but neither publishes an exact provider/destination/auth/model claim table. Lab must remain outside the ordinary request import graph.
+- 검토한 주요 대안: Infer capabilities directly from registry flags; publish prose only; add a broad all-provider matrix immediately; introduce the schema with one exact fixture-backed subject.
+- 선택한 방식: Add a passive versioned schema and one exact `openai`/canonical Codex URL/forward/`gpt-5.6-sol` manifest whose claims reference assertion-level fixtures executed against the production adapter.
+- 다른 대안 대신 이 방식을 선택한 이유: Registry flags do not capture transformations such as local continuation expansion or orphan-output degradation. A broad first matrix would turn unverified assumptions into public promises.
+- 장점, 단점 및 영향: The first contract is small but trustworthy and can feed future CLI/GUI surfaces. Coverage expands only as fixtures are added; no request behavior changes in this slice.
diff --git a/structure/decisions/ADR-0096-z-ai-quota-destination-ownership.md b/structure/decisions/ADR-0096-z-ai-quota-destination-ownership.md
new file mode 100644
index 0000000000..884ec68ddd
--- /dev/null
+++ b/structure/decisions/ADR-0096-z-ai-quota-destination-ownership.md
@@ -0,0 +1,12 @@
+# ADR-0096 — decision recorded under "Z.ai quota destination ownership"
+
+- Contract owner: [gui-and-management-api.md](../gui-and-management-api.md#zai-quota-destination-ownership)
+
+## Decision record
+
+- 목적과 의도: Restore quota reads for documented international Anthropic and Responses bases without changing their inference configuration.
+- 기존 구현 및 제약 조건: Admission omitted both bases; a separate monitor ternary treated all other admitted bases as CN.
+- 검토한 주요 대안: Add the same paths to two lists, accept any path on either host, or share one exact mapping.
+- 선택한 방식: Share one base-to-monitor mapping and preserve the existing CN allowlist.
+- 다른 대안 대신 이 방식을 선택한 이유: A single mapping prevents new international admission from silently selecting the CN authentication scheme, without admitting unrelated pay-as-you-go paths.
+- 장점, 단점 및 영향: No config migration or inference change; new documented endpoints still require an explicit reviewed mapping entry. Quota-consumption differences are not inferred from adapter choice.
diff --git a/structure/07_design-methodology.md b/structure/design-methodology.md
similarity index 80%
rename from structure/07_design-methodology.md
rename to structure/design-methodology.md
index 66f736c216..690b3b1287 100644
--- a/structure/07_design-methodology.md
+++ b/structure/design-methodology.md
@@ -1,4 +1,4 @@
-# 07 — Design Methodology for New Surfaces
+# Design Methodology For New Surfaces
 
 When adding or redesigning a GUI page, CLI wizard, or user-facing flow in opencodex,
 follow the PABCD Catalog Discovery stage ordering (CATALOG-DESIGN-FIRST-01):
@@ -18,7 +18,7 @@ interview engine. The rule stands on its own; it does not depend on an external
 
 The surfaces below are examples chosen to show the design direction, not an inventory; the current
 surface list lives in `gui/src/app-routing.ts` and
-[`05_gui-and-management-api.md`](05_gui-and-management-api.md).
+[`gui-and-management-api.md`](gui-and-management-api.md).
 
 | Surface | Current design | Notes |
 |---|---|---|
@@ -36,3 +36,8 @@ surfaces, run through all 3 stages in order.
 - Design methodology: Product-Personality-Selection (dev-uiux-design §1)
 - 6 design dials: mood, lightness, density, shape, typography, motion
 - 7 axes total: design → domain → feature/data/security/ops/cost (derived)
+
+The management quota DTO keeps Combo editing aligned with scoped inference evidence;
+see [Combo editor routing quota](gui-and-management-api.md#combo-editor-routing-quota).
+
+Cline uses the existing file-integration page, tabs, status badge and rollback dialogs. Its localized semantics identify both files and the required stop/restart boundary before users mutate them.
diff --git a/structure/05_gui-and-management-api.md b/structure/gui-and-management-api.md
similarity index 82%
rename from structure/05_gui-and-management-api.md
rename to structure/gui-and-management-api.md
index 2c21897855..73090d646e 100644
--- a/structure/05_gui-and-management-api.md
+++ b/structure/gui-and-management-api.md
@@ -1,4 +1,4 @@
-# GUI And Management API SOT
+# GUI And Management API
 
 ## Dashboard serving
 
@@ -47,13 +47,7 @@ contains no provider object, API key, OAuth value, custom header, reusable manag
 credential, or config digest. Both the proof and reload request use the direct local
 transport so environment HTTP proxies cannot observe or fabricate the exchange.
 
-[Decision Log]
-- 목적과 의도: Keep a lower-privileged local process from collecting the management bearer by impersonating `/healthz` on an unused port.
-- 기존 구현 및 제약 조건: Liveness must remain public and backward-compatible, but its service string and reported PID are assertions made by the listener itself.
-- 검토한 주요 대안: Require only a runtime source and non-null PID; stop showing account health; authenticate the listener with a protected per-process challenge secret.
-- 선택한 방식: Store a random secret in the mode-protected runtime record and use method/path/PID/port-bound HMAC capabilities for the two CLI health reads, so the CLI sends no reusable Authorization value.
-- 다른 대안 대신 이 방식을 선택한 이유: PID and command-line checks are not cryptographic listener identity, while removing live account health would regress diagnostics unnecessarily.
-- 장점, 단점 및 영향: The long-lived token never reaches a listener without the runtime secret; an old running proxy remains visible but cannot provide detailed CLI account health until restarted on the new version.
+> Decision record: [ADR-0073](decisions/ADR-0073-authentication-boundaries.md)
 
 Management authentication never has a loopback bypass. If no management credential is available, or
 management token creation, validation, or permission hardening fails, every `/api/*` request returns
@@ -124,7 +118,7 @@ this document owns is which module holds which area and what invariant that area
 | Models | Fetch routed model lists, disabled model visibility, and catalog-facing ids. New non-OAuth registration holds exposure until authoritative discovery; 20 or more distinct switch rows start OFF without disabling the provider. Pending rows cannot accept visibility changes. |
 | OAuth | Login/status/logout for OAuth-backed providers, plus multiauth account management: `GET /api/oauth/accounts`, `PUT /api/oauth/accounts/active`, `PUT /api/oauth/accounts/alias`, `DELETE /api/oauth/accounts` list masked accounts per provider, switch the active one, edit its display-only alias, and remove one. The login flow itself is `GET /api/oauth/providers`, `POST /api/oauth/login`, `POST /api/oauth/login/code`, `POST /api/oauth/login/cancel`, `POST /api/oauth/logout`, and `GET /api/oauth/status`; pool controls are `GET/PUT/PATCH /api/oauth/accounts/pool` and `POST /api/oauth/accounts/clear-cooldown`. Login accepts `addAccount: true` to force a fresh browser identity. Device flows return a structured `deviceCode`; the GUI highlights and copies it before the user opens the verification page. |
 | Key providers | `GET /api/key-providers` exposes API-key provider presets for setup and dashboard flows, and `GET/POST/DELETE /api/keys` owns the proxy's own admission keys. Multi-key pool per key-auth provider: `GET /api/providers/keys`, `POST /api/providers/keys`, `PUT /api/providers/keys/active`, `PUT /api/providers/keys/alias`, `DELETE /api/providers/keys` masked list, add (upsert + activate), switch, rename, and remove keys. `provider.apiKey` always mirrors the active pool entry so routing stays single-key. |
-| OpenAI account mode | Report one OpenAI Codex card with Pool/Direct controls and one API-key card. Mode PATCH persists live without restart or catalog identity changes; Pool owns account/quota controls and Direct uses caller/main login only. Main-account DTOs report real credential presence and terminal `needsReauth` state instead of treating missing/invalid native auth as an unknown quota. Selection order has its own route: `PUT /api/codex-auth/accounts/priority` takes `{ id, priority }`, where `priority` is an integer -100..100 or `null` to restore the default, accepts `__main__`, 404s an unknown id, and echoes the stored value. Re-ordering never clears thread affinity, so the response carries no `appliesImmediately`, but it does release any pin — see [`08_openai-provider-tiers.md`](08_openai-provider-tiers.md) for why. `PUT /api/codex-auth/active` with a null id releases one too, but that drops the operator's account selection along with it, so this route is the only operator-facing way to clear a pin while leaving the selected account in place. `GET /api/codex-auth/active` reports `pinned`, true only while the manually selected account is still the effective active one, plus `pinnedAccountId`, which names the pinned account whether or not it is the active one. Surfaces should render `pinnedAccountId`: under round-robin and fill-first the pin caps the tier ceiling at its own tier while the strategy cursor moves freely inside that tier, so `pinned` goes false on a sibling's turn even though the pin is still suppressing every higher tier — which is why the dashboard badges `pinnedAccountId` and the GUI controller tracks only the id. `pinned` answers the narrower question of whether routing is *currently* on the operator's choice; no surface in this repo asks it, and a new one almost certainly wants the id instead. |
+| OpenAI account mode | Report one OpenAI Codex card with Pool/Direct controls and one API-key card. Mode PATCH persists live without restart or catalog identity changes; Pool owns account/quota controls and Direct uses caller/main login only. Main-account DTOs report real credential presence and terminal `needsReauth` state instead of treating missing/invalid native auth as an unknown quota. Selection order has its own route: `PUT /api/codex-auth/accounts/priority` takes `{ id, priority }`, where `priority` is an integer -100..100 or `null` to restore the default, accepts `__main__`, 404s an unknown id, and echoes the stored value. Re-ordering never clears thread affinity, so the response carries no `appliesImmediately`, but it does release any pin — see [`openai-tiers.md`](providers/openai-tiers.md) for why. `PUT /api/codex-auth/active` with a null id releases one too, but that drops the operator's account selection along with it, so this route is the only operator-facing way to clear a pin while leaving the selected account in place. `GET /api/codex-auth/active` reports `pinned`, true only while the manually selected account is still the effective active one, plus `pinnedAccountId`, which names the pinned account whether or not it is the active one. Surfaces should render `pinnedAccountId`: under round-robin and fill-first the pin caps the tier ceiling at its own tier while the strategy cursor moves freely inside that tier, so `pinned` goes false on a sibling's turn even though the pin is still suppressing every higher tier — which is why the dashboard badges `pinnedAccountId` and the GUI controller tracks only the id. `pinned` answers the narrower question of whether routing is *currently* on the operator's choice; no surface in this repo asks it, and a new one almost certainly wants the id instead. |
 | Subagents | Read/write the featured `subagentModels` list capped at five ids. `GET/PUT /api/injection-model` manages the shared delegation model/effort selection, the independent OpenCodex guidance switch, and the default-off `syncCodexSubagentDefaults` opt-in for native Codex subagent defaults. When OpenCodex owns the active Codex routing, native `[agents]` defaults apply to newly created Codex tasks after sync/restart; external user-managed provider configs remain untouched. The defaults do not cause delegation and preserve existing user-owned defaults rather than overwriting them. PUT is partial-update: absent keys are unchanged, `null` clears, and non-object bodies are rejected with 400 before field validation. `syncCodexSubagentDefaults: true` requires a nonblank `model` and a supported Codex reasoning effort when effort is set; clearing `model` (null/empty) always clears effort and disables native-default sync even when the stored effort was invalid. |
 | V2 / Multi-agent mode | `GET/PUT /api/v2` — reports/sets the codex `multi_agent_v2` feature flag, the 3-state `multiAgentMode` override (`v1`/`default`/`v2`), the `keepNativeChatGptOnV1` hybrid pin, and the logical maximum thread count. Selecting `v2` normally enables the native flag; with the hybrid pin it disables that global override so native rows can resolve to v1 while routed rows resolve to v2. Selecting `v1` disables the flag; `default` leaves it unchanged. PUT rejects an explicit enabled flag that conflicts with the selected mode or hybrid pin. Every transition preserves the logical thread limit, is rollback-safe, and resyncs the catalog. GET and successful PUT also return stored `multiAgentModeHintText` plus response-only `multiAgentModeHintRecommendation: { text, revision }`; the recommendation is not a writable or persisted config field. |
 | Logs & Debug | One sidebar entry (`/#logs`) with two tabs. Logs tab: request/runtime logs for local diagnosis. `LogsFilterBar` owns controls over the shared `LogFilterState`; `filterLogs` composes filters over the loaded ring. The logs envelope adds `generatedAt` (proxy epoch milliseconds); the page advances that sample with monotonic elapsed time and retains a browser-clock fallback for older proxies. Reset returns focus to the stable All surface radio. Provider/model options include attempts, model choices match normalized complete identities, and relative-time filtering refreshes every 30 seconds while the Logs tab is active, independently of network auto-refresh. Debug tab (`/#logs/debug`; legacy `/#debug` deep links redirect there): provider + usage toggles, refresh/follow log viewer. `GET/PUT /api/debug`; `GET /api/debug/logs` and `GET /api/debug/usage-logs` (monotonic `after` cursor, legacy `since` accepted). CLI: `ocx debug provider|usage …` (both streams via running proxy API). |
@@ -132,24 +126,19 @@ this document owns is which module holds which area and what invariant that area
 | System | `POST /api/system/restart` restarts the proxy in place. Local CLI/tray callers first attest the exact runtime PID and port, then send a process-scoped HMAC capability bound to that method, path, PID, and port; the capability authorizes no other management route and is invalid after replacement. The caller observes one absolute deadline and accepts success only after a different runtime PID is healthy on the same port. `GET /api/system/health` is the authenticated scalar-only identity used by shared-plane Dashboard status and restart reconnect polling; it does not widen a Remote Hub management ingress to unauthenticated `/healthz`. `GET /api/system/memory` — service-process runtime/memory identity (pid, Bun version/revision, optional `bunRuntimeSource` provenance, platform, RSS/heap/external/ArrayBuffers scalars, observed memory = max(RSS, external, ArrayBuffers), `bun:jsc` heap context, streamMode + eager-relay gate decision, watchdog snapshot sliced to the last 60 samples) plus privacy-safe `appOwnedBytes` retained-store totals/counters under static store ids. Its response-state block also reports spill-write `initial`/`healthy`/`degraded` status, a consecutive-failure streak, fixed error class, and failure/success timestamps. A successful publication clears the streak in the same process; raw error text and paths never enter this surface. Scalar-only payload; dashboard/admin callers use the standard management gate, while `ocx doctor` may use only the exact process-scoped local-read capability. It must never move to unauthenticated `/healthz`. |
 | Stop | `POST /api/stop` — restore native Codex, stop any installed service, and exit the proxy. |
 | Diagnostics/sync | `src/server/management/config-routes.ts` — `GET /api/diagnostics/project-config` reports project-level Codex config that bypasses managed routing; `POST /api/sync` re-runs catalog/config sync. The diagnostic reports the bypass; it does not rewrite the project file. |
-| Sidecar/shadow-call settings | `src/server/management/config-routes.ts` — `GET/PUT /api/sidecar-settings` and `GET/PUT /api/shadow-call-settings`. PUT accepts model and backend (web-search union: openai/anthropic/xai/gemini/exa; xAI is live through stored Grok OAuth, while Gemini/Exa remain inert until their executors ship) plus validated `webSearch.xSearch`, optional `webSearch.exaApiKey` (write/clear only — never echoed by GET or the PUT response; redact.ts strips it from logs), `webSearch.reasoning`, `vision.reasoning`, `vision.enabled`, `vision.maxDescriptionsPerTurn`, and `vision.timeoutMs`; the read and PUT-response payload reports model, backend, reasoning, enabled, the vision per-turn limit, and timeout. `timeoutMs` is validated against the runtime integer bounds in `src/vision/timeout-bounds.ts`. Provider/OAuth credentials live in their stores; `exaApiKey` is the one sidecar-owned secret and follows the write-only contract above. Both shadow-call responses also report the resolved `sourceModels` — the prefixes the runtime actually intercepts (`src/lib/shadow-call.ts`, default `gpt-5.4-mini` + `gpt-5.6-luna`), so no client hard-codes a helper slug that a Codex release can invalidate. |
+| Sidecar/shadow-call settings | `src/server/management/config-routes.ts` — `GET/PUT /api/sidecar-settings` and `GET/PUT /api/shadow-call-settings`. PUT accepts model and backend (web-search union: openai/anthropic/xai/gemini/exa; xAI is live through stored Grok OAuth, while Gemini/Exa remain inert until their executors ship) plus validated `webSearch.xSearch`, optional `webSearch.exaApiKey` (write/clear only — never echoed by GET or the PUT response; redact.ts strips it from logs), `webSearch.reasoning`, `vision.reasoning`, `vision.enabled`, `vision.maxDescriptionsPerTurn`, and `vision.timeoutMs`; the read and PUT-response payload reports model, backend, reasoning, enabled, the vision per-turn limit, and timeout. `timeoutMs` is validated against the runtime integer bounds in `src/vision/timeout-bounds.ts`. Provider/OAuth credentials live in their stores; `exaApiKey` is the one sidecar-owned secret and follows the write-only contract above. Both shadow-call responses also report the resolved `sourceModels` — the prefixes the runtime actually intercepts (`src/lib/shadow-call.ts`, default `gpt-5.6-luna`; the retired `gpt-5.4-mini` stays available as an explicit `sourceModels` entry for 0.144.x clients), so no client hard-codes a helper slug that a Codex release can invalidate. |
 | Storage | `src/server/management/logs-usage-routes.ts` — `GET /api/storage`, `POST /api/storage/cleanup/preview` and `/api/storage/cleanup`, `GET /api/storage/trash`, `POST /api/storage/trash/restore`, and `GET/PUT /api/storage/cleanup-policy` plus `POST /api/storage/cleanup-policy/run`. `GET /api/storage/cleanup-policy/test-stream` and `GET /api/storage/trash/restore/test-stream` exist for progress-stream testing. Cleanup takes an explicit `mode`: `quarantine` moves to trash and is restorable, `permanent` is not. The caller must name the mode — there is no default that silently deletes. |
 | Provider quotas and tests | `src/server/management/provider-routes.ts` — `GET /api/provider-quotas`, `POST /api/providers/test`, `GET/PUT /api/provider-context-caps`, `GET /api/provider-presets`. A quota read may be served from cache or force-refreshed; absent quota data is reported as unknown rather than as a measured zero. |
 | Models and visibility | `src/server/management/model-routes.ts` — `GET /api/models`, `PUT /api/disabled-models`, `PUT /api/model-visibility`, `PUT /api/selected-models`, `GET/POST /api/custom-models`. Visibility writes trigger catalog sync through the owning server path. |
 | Effort and fallback | `src/server/management/agent-settings-routes.ts` — `GET/PUT /api/effort-caps`, `/api/subagent-models`, `/api/subagent-model-fallback`. Caps clamp; they do not reject. |
-| Grok and Claude integrations | `src/server/management/agent-settings-routes.ts` — `GET /api/grok`, `PUT /api/grok/selection`, `POST /api/grok/apply`, `GET/PUT /api/claude-desktop`, `POST /api/claude-desktop/apply`, `GET /api/claude-desktop/status`, `GET/PUT /api/claude-code`. Apply writes an external app's profile, so its status probe must read the same resolved path it writes (see [`04_transports-and-sidecars.md`](04_transports-and-sidecars.md)). |
+| Grok and Claude integrations | `src/server/management/agent-settings-routes.ts` — `GET /api/grok`, `PUT /api/grok/selection`, `POST /api/grok/apply`, `GET/PUT /api/claude-desktop`, `POST /api/claude-desktop/apply`, `GET /api/claude-desktop/status`, `GET/PUT /api/claude-code`. Apply writes an external app's profile, so its status probe must read the same resolved path it writes (see [`responses.md`](transports/responses.md)). |
+| Grok reset coupons | `src/server/management/grok-coupon-routes.ts` — `GET /api/grok/reset-coupons`, `POST /api/grok/reset-coupons/consume`. The dashboard owner is `gui/src/hooks/useGrokResetCoupons.ts` with `gui/src/components/provider-workspace/GrokResetCoupons.tsx`, wired into the xAI OAuth rows of `ProviderAuthPanel`. Redemption truth is the settled ledger `code`, not the HTTP status: a replayed failure returns 200 with `replayed: true`. See [`providers/xai-grok.md`](providers/xai-grok.md). |
 | Combos | `src/server/management/combo-routes.ts` — `GET/PUT/DELETE /api/combos` own provider combination and failover definitions. |
 | Codex accounts | `src/codex/auth-api.ts` — `GET/POST/DELETE /api/codex-auth/accounts`, `PUT /api/codex-auth/accounts/alias`, `PUT /api/codex-auth/accounts/pause`, `PUT /api/codex-auth/accounts/pause-exhausted`, `POST /api/codex-auth/accounts/clear-cooldown`, `GET/PUT /api/codex-auth/active`, `PUT /api/codex-auth/auto-switch`, `PUT /api/codex-auth/pool-strategy`, `PUT /api/codex-auth/failover`, `GET /api/codex-auth/quota`, `GET /api/codex-auth/reset-credits` with `POST /api/codex-auth/reset-credits/consume`, and the login flow `POST /api/codex-auth/login`, `POST /api/codex-auth/login/code`, `POST /api/codex-auth/login/cancel`, `GET /api/codex-auth/login-status`. Per-account quota activation uses the existing `GET/PUT /api/settings` surface and `src/codex/quota-auto-refresh.ts`, keeping scheduled spending separate from credential/authentication mutation. Account ids are opaque handles and are serialized so the GUI can address an account; emails are masked and tokens are never serialized. New-account config commits add UI-managed selector bindings in the same config save; deletion deliberately retains existing bindings for fail-closed exact routing and re-add stability. Account mutations request catalog convergence only after config durability and expose only the boolean `catalogRefreshPending` completion projection. |
 | Sidebar | `src/server/management/sidebar-routes.ts` — `GET/POST /api/github/star` and `GET /api/update/badge`. Sidebar state is cosmetic; a failed fetch degrades silently. |
 | Logs | `src/server/management/logs-usage-routes.ts` — `GET /api/logs`, `GET /api/claude/inbound-debug`, and `GET /api/debug/injection-logs` join the debug streams described above. |
 
-[Decision Log]
-- 목적과 의도: Distinguish a healthy process from a continuation spill writer that is repeatedly failing, especially on Windows where the ACL publication lane is asynchronous.
-- 기존 구현 및 제약 조건: `/healthz` intentionally reports liveness only, while `spillWriteFailures` was cumulative and discarded the failure class, event time, and recovery boundary.
-- 검토한 주요 대안: Make `/healthz` fail on a spill error; publish raw error messages; expose a fixed classified health projection only on the authenticated memory route.
-- 선택한 방식: Keep liveness unchanged and add a consecutive streak, fixed error class, and last failure/success timestamps to the existing authenticated response-state metrics.
-- 다른 대안 대신 이 방식을 선택한 이유: One failed cache demotion must not restart or remove an otherwise serving proxy, and raw filesystem errors can disclose user paths while still failing to show whether the next write recovered.
-- 장점, 단점 및 영향: Operators can identify accumulating failures and same-process recovery without sensitive text. The status is process-local and resets to `initial` on restart, so historical diagnosis still requires external metric collection.
+> Decision record: [ADR-0074](decisions/ADR-0074-api-ownership.md)
 
 Provider writes must not round-trip masked API keys as real secrets. Dashboard actions that change
 model visibility or subagent selection should trigger catalog/cache sync behavior through the server
@@ -158,7 +147,7 @@ path that owns it.
 The UI must show one provider card and one Models group for Codex-login OpenAI, describe Pool and
 Direct accurately, and keep the main account inside Pool. Public model state keeps virtual Pro ids
 even though transport logs may additionally report the resolved base model. Detailed rules live in
-[`08_openai-provider-tiers.md`](08_openai-provider-tiers.md).
+[`openai-tiers.md`](providers/openai-tiers.md).
 
 User aliases are display metadata only. Codex pool aliases live on `CodexAccount`, OAuth aliases on
 `ProviderAccount`, and API-key aliases reuse the existing key `label`; account ids, credential
@@ -186,7 +175,7 @@ is routing metadata that Pool selection consults, it lives in config rather than
 `__main__` Desktop login can carry one, and the alias route's rejection of `__main__` would be wrong for
 it. The matching CLI is `ocx account priority <provider> <id|main> [<value>]`, reading the current order
 when the value is omitted. Ordering invariants live in
-[`08_openai-provider-tiers.md`](08_openai-provider-tiers.md).
+[`openai-tiers.md`](providers/openai-tiers.md).
 
 ## Sidebar stop button
 
@@ -277,46 +266,28 @@ until Windows returns approval or cancellation; other proxy requests keep runnin
 Existing or conflicting registrations stay on the older fail-closed path because deleting or
 replacing them cannot be called a rollback without an exact prior-registration snapshot.
 
-```text
-[Decision Log]
-- 목적과 의도: Keep a refused fresh Windows service install from stopping a working proxy and removing managed Codex routing.
-- 기존 구현 및 제약 조건: The generic installer stopped service managers and the standalone proxy before the first scheduler create attempt; the Dashboard UAC path depended on assets produced by that already-destructive failure.
-- 검토한 주요 대안: Reject every non-elevated caller up front, restart and re-inject after failure, snapshot every runtime/config artifact for rollback, or separate registration approval from the destructive commit.
-- 선택한 방식: When scheduler absence is proven, create but do not run the owned registration from a temporary XML first; cleanup and canonical asset publication begin only after registration succeeds.
-- 다른 대안 대신 이 방식을 선택한 이유: An early rejection breaks Dashboard UAC, while a best-effort restart cannot prove that manager, proxy, and routing state were restored. The two-phase boundary makes denial/cancellation a real pre-commit failure.
-- 장점, 단점 및 영향: Fresh-install UAC failure preserves the live proxy and routing. Failures after registration remain explicit partial-install cases, and existing/conflicting scheduler recovery remains conservative until exact prior-state restoration is available.
-```
-
-```text
-[Decision Log]
-- 목적과 의도: Make Windows scheduler installation recovery work on non-English systems without broadening the commands that may request UAC.
-- 기존 구현 및 제약 조건: Access-denied classification parsed English and German stderr. Chinese OEM output decoded as UTF-8 became mojibake, so the fixed scheduler-create failure lost its machine marker and the dashboard could not select its existing elevation transaction.
-- 검토한 주요 대안: Add translations and code-page decoders; elevate every scheduler failure; always launch installation elevated; or combine a native effective-token probe with the already fixed command shape and exit status.
-- 선택한 방식: Preserve text detection, then use the native token probe only for status-1 creation of the owned `opencodex-proxy` XML task. Unknown probe results fail closed.
-- 다른 대안 대신 이 방식을 선택한 이유: Windows localization and OEM code pages are open-ended, while the token state and owned command shape are stable security signals already bounded by the elevated transaction protocol.
-- 장점, 단점 및 영향: Non-English users receive stable guidance and dashboard UAC recovery. A non-permission status-1 failure from the exact owned command may be retried once elevated, but foreign operations cannot cross the elevation boundary and the elevated transaction still fails closed.
-```
+> Decision record: [ADR-0075](decisions/ADR-0075-startup-safety.md)
+
+> Decision record: [ADR-0076](decisions/ADR-0076-startup-safety.md)
 
 Dashboard updates persist their detached worker PID before returning success. This lets a later run
 distinguish a live installer from a worker that crashed. Records created by older versions do not
 have a PID, so they remain exclusive for a conservative ten-minute window before automatic
 recovery; operators no longer need to delete `update-job.json` after a dead worker.
 
-```text
-[Decision Log]
-- 목적과 의도: Prevent a crashed dashboard update worker from permanently blocking every later update.
-- 기존 구현 및 제약 조건: The job file was written before spawn, the returned PID was not persisted, and active status had no liveness or freshness check.
-- 검토한 주요 대안: Require manual deletion; expire all jobs by age; or persist PID and use age only for legacy no-PID records.
-- 선택한 방식: Persist and verify PID liveness, with a ten-minute fallback only for legacy records.
-- 다른 대안 대신 이 방식을 선택한 이유: It recovers known-dead workers promptly without allowing a second installer beside a long-running live worker.
-- 장점, 단점 및 영향: New jobs self-recover after worker death and spawn failures become visible; legacy crashes may remain blocked for up to ten minutes.
-```
+> Decision record: [ADR-0077](decisions/ADR-0077-startup-safety.md)
 
 ## UX boundary
 
 The dashboard is a local control surface, not a separate service. It should reflect the same config
 and catalog invariants documented in this folder rather than inventing parallel state.
 
+Codex quota cards consume the display cache from `src/codex/quota.ts`. A partial refresh
+removes an omitted short tuple whose reset deadline has elapsed, so a stale Spark-derived
+5h row does not persist on a weekly-only account. This is independent of the main-account
+hard-lock evidence and reset-notification history; their retention rules are documented in
+[OpenAI account modes](providers/openai-tiers.md#quota-cache-and-short-window-history).
+
 ## Dashboard surfaces
 
 Provider Overview consumes the existing shared `add-provider-presets` resource for sponsor
@@ -337,8 +308,8 @@ single forms, and the shell pattern is the part worth keeping stable:
 | Storage | Rail plus cleanup and trash detail (`gui/src/components/storage-workspace/`). |
 | Subagents | Featured-roster selection workspace (`gui/src/components/subagents-workspace/`). |
 | Combos | Rail, detail panel, and an add flow (`gui/src/components/ComboWorkspace.tsx`). |
-| Add provider | Catalog browser plus form and OAuth panes (`gui/src/components/provider-catalog/`, `gui/src/components/AddProviderModal.tsx`). |
-| Codex accounts | Account pool cards, add-account flow, switch and reset modals (`gui/src/components/CodexAccountPool.tsx`, `gui/src/components/AddCodexAccountModal.tsx`), plus the generic account-targeting picker opt-in on `gui/src/pages/CodexAuth.tsx`. Add/delete/login completion is projected to one boolean before presentation; pending catalog work is a warning, not a failed account mutation. |
+| Add provider | Catalog browser plus form and OAuth panes (`gui/src/components/provider-catalog/`, `gui/src/components/AddProviderModal.tsx`). The catalog browses four tabs — Accounts, Free, Local, Paid — where Local is a catalog-only bucket peeled out of `bucketPresets` after `presetTier` has classified; the workspace `providerTier` stays three-way, so the rail, the free-paid sort and the Free count still treat a local runtime as free. Search sits above the tabs and reaches every tab at once: while a query is live the list renders all four groups with headings and the strip becomes jump chips with counts rather than a tablist, because moving the selected tab would change the row kind under the user (a preset-select button becomes a login row). ArrowDown from the search input focuses the first enabled result action; if none is available, focus stays in the input. The tab strip wraps within narrow modals. Every nonempty note has a full-text button so narrow rows never hide content permanently; the native note dialog closes during teardown and restores focus to its trigger. Provider notes clamp to two lines and open in full in a stacked native `<dialog>` owned by `AddProviderModal`, which also owns the search text so its `window` Escape handler can unwind popup, then query, then dialog. |
+| Codex accounts | Account pool cards, add-account flow, switch and reset modals (`gui/src/components/CodexAccountPool.tsx`, `gui/src/components/AddCodexAccountModal.tsx`), plus the generic account-targeting picker opt-in on `gui/src/pages/codex-set-multiauth.tsx`. Add/delete/login completion is projected to one boolean before presentation; pending catalog work is a warning, not a failed account mutation. |
 | Dashboard overview | Overview, Providers, and Models tabs at the page level (`gui/src/pages/Dashboard.tsx`), the 30-day token and coverage stats in the overview head (`gui/src/pages/dashboard-overview-head.tsx`), and the effort-cap, injection, maintenance, sidecar, and memory panels below it (`gui/src/pages/dashboard-overview-panels.tsx`). |
 
 Rail selection is component-local state today, so a reload returns to the workspace's default
@@ -429,13 +400,7 @@ attempts; the generation itself is never serialized or stored in the quota cache
 The CLI reconstructs the object using a fixed vocabulary and bounded numeric HTTP
 status, so an unexpected management response cannot add raw upstream material.
 
-[Decision Log]
-- 목적과 의도: Explain missing main-account quota without confusing a working login with a successful WHAM read.
-- 기존 구현 및 제약 조건: HTTP failures and body/transport exceptions returned identical null metadata; existing authentication and freshness policy must remain unchanged.
-- 검토한 주요 대안: Copy raw errors, infer plan/quota, reuse stale evidence, or add a bounded diagnostic outcome.
-- 선택한 방식: Carry a non-persisted fixed category and optional numeric HTTP status through the existing management and CLI read paths.
-- 다른 대안 대신 이 방식을 선택한 이유: It gives reporters actionable evidence without disclosing payloads, changing permissions, or introducing another cache.
-- 장점, 단점 및 영향: Main-account failures become distinguishable; root-cause repair and pool diagnostics remain separate work, and clients must tolerate an absent field.
+> Decision record: [ADR-0078](decisions/ADR-0078-usage-accounting.md)
 
 `src/usage/log.ts` writes append-only JSONL to `~/.opencodex/usage.jsonl` with file mode `0o600`.
 An opt-in shadow-call rewrite persists the bounded, redacted original helper model as
@@ -491,13 +456,7 @@ remain in the response for compatibility with older GUI and CLI clients. A succe
 scan reports `false`, `0`, `false`, and `0`; clients must not interpret those fields as evidence that
 `managementUsageMaxReadBytes` was raised or that a bounded tail was selected.
 
-[Decision Log]
-- 목적과 의도: Keep dashboard and management requests responsive as `usage.jsonl` grows.
-- 기존 구현 및 제약 조건: The append-only JSONL file remains the durable source of truth and may be truncated or replaced. A tail-only byte/row bound kept memory finite but made historical totals incomplete on busy installations; arbitrary in-place historical edits cannot be detected without rereading the prefix.
-- 검토한 주요 대안: Raise the byte/row caps, retain normalized rows, maintain a second database, or stream the complete ledger into compact accumulators and cache only revision-keyed summaries.
-- 선택한 방식: Stream the complete ledger in fixed 1 MiB chunks for a cold rebuild, retain only compact aggregate state plus an LF/digest checkpoint, fold verified append suffixes atomically, share concurrent work, yield during parsing, and poll usage separately at a slower cadence.
-- 다른 대안 대신 이 방식을 선택한 이유: It restores complete historical aggregation without making correctness depend on an operator-sized read limit, retaining every parsed row, or introducing a second persistence format.
-- 장점, 단점 및 영향: Unchanged queries are cheap, normal refreshes read only appended bytes, and memory stays bounded. Cold starts and explicit invalidations still consume file-size-proportional IO/CPU. A same-inode historical rewrite outside the trailing checkpoint requires replacement, truncation, or restart to force that cold rebuild.
+> Decision record: [ADR-0079](decisions/ADR-0079-usage-accounting.md)
 
 For diagnosing upstream-shape / usage-extraction issues run `ocx debug usage on` (or set
 `OPENCODEX_USAGE_DEBUG=1` before start). The proxy then writes a rolling debug record per finalized
@@ -506,6 +465,16 @@ once it exceeds 200) with the upstream content-type, body kind (`sse / json / ot
 body sample, and the extracted usage. Off by default; the hot path is guarded so production stays
 untouched.
 
+## Z.ai quota destination ownership
+
+`src/providers/quota.ts` uses one exact normalized-base mapping for both Z.ai quota
+eligibility and monitor selection. International root, coding Chat, Anthropic and
+Responses bases use `api.z.ai` with Bearer authentication. Existing BigModel CN root,
+coding Chat and Responses bases use `open.bigmodel.cn` with the raw key. Unsupported
+bases produce no probe; redirect refusal and quota parsing/cache semantics are unchanged.
+
+> Decision record: [ADR-0096](decisions/ADR-0096-z-ai-quota-destination-ownership.md)
+
 ## Provider debug logging
 
 Provider transport diagnostics (dropped SSE frames, adapter dial/stream events, etc.) are opt-in:
@@ -542,3 +511,35 @@ converge the Codex catalog once and return its disposition. The Models UI owns a
 picker data resource so failure cannot erase the ordinary model inventory; Apply publishes through
 the resource's generation fence, and Most used reads usage only on explicit Apply. Stored mode
 survives availability drift, while complete/native custom orders await explicit replacement.
+
+Chat helper admission in `src/server/responses/core.ts` follows the
+[deferred stored-main contract](providers/openai-tiers.md): only a needed Direct OpenAI helper
+claims stored main, after terminal vision, routed vision and search exclusions.
+
+## Combo editor routing quota
+
+`src/server/management/provider-routes.ts` projects `routingQuota` after each quota read using the
+current provider configuration and [scoped inference evidence](runtime.md#scoped-provider-quota-for-combo-selection).
+The DTO carries only state, observation time and an exclusive `validUntil`; cached display reports
+and private credential bindings are unchanged. Known states expire within 30 minutes; exhaustion
+may expire earlier when the runtime predicate clears at a reset boundary, accounting for other
+windows and persistent USD blockers.
+
+`gui/src/combo-workspace-data.ts` accepts only this projection for quota-based Save/Create blocking.
+Missing, invalid or expired evidence is unknown. `gui/src/pages/Combos.tsx` wakes at the rendered
+expiry, including a deadline crossed before effects run, rechecks activation and visibility, and
+refreshes quota with Combo data while preserving drafts. Each successful quota snapshot also
+advances the observation clock, so a retained older row cannot defer evaluation of a fresh row.
+
+## Paginated history writer boundary
+
+`src/codex/history-provider.ts` refuses external writes to paginated or migration-capable history. `src/codex/inject.ts` checks affected rows and manifest-owned restore targets before artifact changes and compensates detected migration. Failed config restore stops later catalog/history work. See the [history writer contract](codex-home.md#paginated-history-writer-boundary) for guarantees and concurrent-writer limits.
+
+Claude replay carries [Go conversation affinity](data-planes/inbound-compat.md#claude-affinity-at-final-go-dispatch)
+privately to final dispatch; preliminary route selection does not inject Go-only headers.
+
+Cline journal Undo eligibility reads both native configuration files through the paired
+integration IO adapter. Its snapshot fingerprint cannot be checked against providers.json alone;
+[the integration contract](clients/integrations.md#cline-paired-files) defines recovery.
+
+The existing dashboard file-client maps include Cline CLI and reuse its committed color mark. The export panel labels its download as a settings/catalog bundle; all locales explain that Undo restores both original files.
diff --git a/structure/manifest.json b/structure/manifest.json
new file mode 100644
index 0000000000..fd85177820
--- /dev/null
+++ b/structure/manifest.json
@@ -0,0 +1,411 @@
+{
+  "version": 2,
+  "sizeBudgetLines": 600,
+  "generatedPaths": [
+    "gui/dist"
+  ],
+  "absentPaths": [
+    {
+      "path": "go/",
+      "reason": "the Go native-runtime experiment is retired; ops/docs-and-release.md documents that no go/ tree is tracked"
+    }
+  ],
+  "tiers": [
+    {
+      "id": 1,
+      "name": "Foundation",
+      "purpose": "What opencodex is, what it owns on disk, and the invariants nothing may break."
+    },
+    {
+      "id": 2,
+      "name": "Configuration and catalog",
+      "purpose": "Persisted config, the Codex home it writes into, and the model catalog it publishes."
+    },
+    {
+      "id": 3,
+      "name": "Data planes and transports",
+      "purpose": "The wire surfaces a client actually talks to."
+    },
+    {
+      "id": 4,
+      "name": "Providers and adapters",
+      "purpose": "Per-vendor contracts and the adapter authority that constructs them."
+    },
+    {
+      "id": 5,
+      "name": "Surfaces and clients",
+      "purpose": "The dashboard, the management API, and third-party client config ownership."
+    },
+    {
+      "id": 6,
+      "name": "Operations and process",
+      "purpose": "Background service, docs, release, and design discipline."
+    }
+  ],
+  "docs": [
+    {
+      "path": "overview.md",
+      "tier": 1,
+      "title": "Overview",
+      "scope": "Product boundary, local state ownership, and the non-negotiable invariants index.",
+      "documents": [
+        "gui/",
+        "scripts/",
+        "src/config.ts",
+        "src/lib/"
+      ]
+    },
+    {
+      "path": "runtime.md",
+      "tier": 1,
+      "title": "Runtime",
+      "scope": "Entrypoints, process lifecycle, CLI surface, and provider/adapter selection.",
+      "documents": [
+        "bin/",
+        "src/adapters/",
+        "src/chat/",
+        "src/claude/",
+        "src/cli.ts",
+        "src/cli/",
+        "src/client/",
+        "src/codex/",
+        "src/combos/",
+        "src/compatibility/",
+        "src/config.ts",
+        "src/config/",
+        "src/generated/",
+        "src/github/",
+        "src/grok/",
+        "src/images/",
+        "src/index.ts",
+        "src/lab/",
+        "src/lib/",
+        "src/oauth/",
+        "src/providers/",
+        "src/reasoning-effort.ts",
+        "src/remote/",
+        "src/responses/",
+        "src/router.ts",
+        "src/server/",
+        "src/service.ts",
+        "src/stall-timeout.ts",
+        "src/storage/",
+        "src/tray/",
+        "src/types.ts",
+        "src/update/",
+        "src/usage/",
+        "src/vision/",
+        "src/web-search/"
+      ]
+    },
+    {
+      "path": "config.md",
+      "tier": 2,
+      "title": "Config Surface",
+      "scope": "Persisted config schema, both injection forms, provider validation, and restore.",
+      "documents": [
+        "src/cli/",
+        "src/codex/",
+        "src/config.ts",
+        "src/config/",
+        "src/types.ts"
+      ]
+    },
+    {
+      "path": "codex-home.md",
+      "tier": 2,
+      "title": "Codex Home",
+      "scope": "CODEX_HOME resolution, the files opencodex manages there, and Codex-home diagnostics.",
+      "documents": [
+        "src/codex/"
+      ]
+    },
+    {
+      "path": "catalog.md",
+      "tier": 2,
+      "title": "Model Catalog",
+      "scope": "Shared Codex catalog assembly, account namespaces, pool rotation, and effort ladders.",
+      "documents": [
+        "src/codex/",
+        "src/routing/",
+        "src/server/"
+      ]
+    },
+    {
+      "path": "subagents.md",
+      "tier": 2,
+      "title": "Subagents And Multi-Agent Surface",
+      "scope": "Multi-agent surface mode and subagent roster ordering.",
+      "documents": [
+        "src/codex/",
+        "src/providers/",
+        "src/server/"
+      ]
+    },
+    {
+      "path": "transports/responses.md",
+      "tier": 3,
+      "title": "Responses Transport",
+      "scope": "The Responses HTTP/SSE data plane, combo failover, and streaming commit boundaries.",
+      "documents": [
+        "src/adapters/",
+        "src/lib/",
+        "src/responses/",
+        "src/server/"
+      ]
+    },
+    {
+      "path": "transports/streaming-health.md",
+      "tier": 3,
+      "title": "Streaming Health And WebSocket",
+      "scope": "Heartbeat and stall deadlines, plus the opt-in WebSocket transport.",
+      "documents": [
+        "src/server/"
+      ]
+    },
+    {
+      "path": "transports/inventory.md",
+      "tier": 3,
+      "title": "Transport Inventory",
+      "scope": "The per-provider transport table and diagnostic outbound safety.",
+      "documents": [
+        "src/adapters/",
+        "src/chat/",
+        "src/images/",
+        "src/lib/",
+        "src/oauth/",
+        "src/providers/",
+        "src/server/"
+      ]
+    },
+    {
+      "path": "data-planes/images.md",
+      "tier": 3,
+      "title": "Images Data Plane",
+      "scope": "Standalone image generation and edit relay.",
+      "documents": [
+        "src/server/"
+      ]
+    },
+    {
+      "path": "data-planes/search.md",
+      "tier": 3,
+      "title": "Search Data Plane",
+      "scope": "Hosted search relay and exact account selectors.",
+      "documents": []
+    },
+    {
+      "path": "data-planes/inbound-compat.md",
+      "tier": 3,
+      "title": "Inbound Compatibility Surfaces",
+      "scope": "Chat Completions inbound, Anthropic-shaped clients, and JSON-upstream streaming clients.",
+      "documents": [
+        "src/adapters/",
+        "src/chat/",
+        "src/server/"
+      ]
+    },
+    {
+      "path": "providers/openai-tiers.md",
+      "tier": 4,
+      "title": "OpenAI Provider Account Modes",
+      "scope": "Pool/Direct account modes, API-key separation, wire identity, and quota evidence.",
+      "documents": [
+        "src/codex/",
+        "src/config.ts"
+      ]
+    },
+    {
+      "path": "providers/cursor.md",
+      "tier": 4,
+      "title": "Cursor Provider",
+      "scope": "Cursor native exec, parameterized models, checkpoints, and active-context usage.",
+      "documents": [
+        "src/adapters/"
+      ]
+    },
+    {
+      "path": "providers/google.md",
+      "tier": 4,
+      "title": "Google Provider",
+      "scope": "Gemini thought-text, response parts, thought-signature replay, and adjacency repair.",
+      "documents": []
+    },
+    {
+      "path": "providers/kiro.md",
+      "tier": 4,
+      "title": "Kiro Provider",
+      "scope": "Kiro parallel-tool hints, Responses text controls, and reasoning round-trip.",
+      "documents": [
+        "src/responses/"
+      ]
+    },
+    {
+      "path": "providers/xai-grok.md",
+      "tier": 4,
+      "title": "xAI Grok Provider",
+      "scope": "Grok Build contract parity and hardening.",
+      "documents": [
+        "src/oauth/",
+        "src/providers/",
+        "src/responses/",
+        "src/server/"
+      ]
+    },
+    {
+      "path": "providers/chat-compat.md",
+      "tier": 4,
+      "title": "Chat Provider Compatibility",
+      "scope": "Cross-vendor Chat Completions behavior: reasoning, tool results, structured output, parallel tools.",
+      "documents": [
+        "src/adapters/",
+        "src/responses/"
+      ]
+    },
+    {
+      "path": "adapters/registry.md",
+      "tier": 4,
+      "title": "Adapter Registry Authority",
+      "scope": "The single adapter construction authority and contract inheritance.",
+      "documents": [
+        "src/adapters/",
+        "src/server/"
+      ]
+    },
+    {
+      "path": "adapters/compatibility-contracts.md",
+      "tier": 4,
+      "title": "Compatibility Contracts",
+      "scope": "Versioned provider compatibility claims and fixture-evidence boundaries.",
+      "documents": [
+        "src/compatibility/"
+      ]
+    },
+    {
+      "path": "adapters/compatibility-lab.md",
+      "tier": 4,
+      "title": "Compatibility Lab",
+      "scope": "Optional Lab evidence, automation, and its core-runtime isolation boundary.",
+      "documents": [
+        "src/lab/"
+      ]
+    },
+    {
+      "path": "gui-and-management-api.md",
+      "tier": 5,
+      "title": "GUI And Management API",
+      "scope": "Dashboard serving, authentication boundaries, /api/* ownership, and usage accounting.",
+      "documents": [
+        "gui/",
+        "src/codex/",
+        "src/lib/",
+        "src/server/",
+        "src/usage/",
+        "src/vision/"
+      ]
+    },
+    {
+      "path": "clients/integrations.md",
+      "tier": 5,
+      "title": "Client Integrations",
+      "scope": "Third-party client config ownership, snapshots, refresh, disable, and restore.",
+      "documents": [
+        "src/clients/",
+        "src/integrations/",
+        "src/lib/"
+      ]
+    },
+    {
+      "path": "clients/claude-desktop.md",
+      "tier": 5,
+      "title": "Claude Desktop Integration",
+      "scope": "Claude Desktop profile ownership and config-library resolution.",
+      "documents": [
+        "src/claude/",
+        "src/cli/",
+        "src/client/",
+        "src/server/"
+      ]
+    },
+    {
+      "path": "ops/service-and-sidecars.md",
+      "tier": 6,
+      "title": "Background Service And Sidecars",
+      "scope": "Service install/repair, platform launchers, tray, and sidecar processes.",
+      "documents": [
+        "src/server/"
+      ]
+    },
+    {
+      "path": "ops/docs-and-release.md",
+      "tier": 6,
+      "title": "Docs And Release",
+      "scope": "Docs site, workflow map, branch policy, release flow, and cross-platform CI.",
+      "documents": [
+        ".github/",
+        "bin/",
+        "docs-site/",
+        "scripts/",
+        "src/cli.ts",
+        "src/cli/",
+        "src/codex/",
+        "src/lib/",
+        "src/service.ts"
+      ]
+    },
+    {
+      "path": "design-methodology.md",
+      "tier": 6,
+      "title": "Design Methodology For New Surfaces",
+      "scope": "Stage ordering for new GUI, CLI, and user-facing surfaces.",
+      "documents": [
+        "gui/"
+      ]
+    },
+    {
+      "path": "remote-workspace.md",
+      "tier": 3,
+      "title": "Remote Workspace",
+      "scope": "Inactive workspace protocol, cryptographic identity primitives, and bounded framing.",
+      "documents": [
+        "src/remote-control/"
+      ]
+    }
+  ],
+  "grace": {
+    "undocumentedSourceAreas": [
+      {
+        "path": "src/bridge.ts",
+        "reason": "no doc names this file; it is the legacy adapter bridge entry and its behavior is described under the adapter registry without a path reference"
+      },
+      {
+        "path": "src/quota/",
+        "reason": "no doc names a path here; quota evidence is described in providers/openai-tiers.md in prose only"
+      },
+      {
+        "path": "src/service-manager-probe.ts",
+        "reason": "no doc names this file; service probing is described in ops/service-and-sidecars.md without a path reference"
+      },
+      {
+        "path": "src/sidecar/",
+        "reason": "no doc names a path here; ops/service-and-sidecars.md describes sidecar behavior in prose only"
+      },
+      {
+        "path": "src/types/",
+        "reason": "shared declarations plus the tool-name and wire-pin resolvers, which no doc currently describes"
+      }
+    ],
+    "unboundInvariants": [
+      {
+        "id": "INV-HOME-01",
+        "reason": "no test asserts CODEX_HOME precedence over ~/.codex directly; the closest coverage is WSL home discovery"
+      },
+      {
+        "id": "INV-SLUG-01",
+        "reason": "no test constrains routed slug shape; the ten files that mention provider/model consume slugs rather than enforcing the form"
+      }
+    ],
+    "oversizeDocs": [],
+    "staleRefs": []
+  }
+}
diff --git a/structure/06_docs-and-release.md b/structure/ops/docs-and-release.md
similarity index 80%
rename from structure/06_docs-and-release.md
rename to structure/ops/docs-and-release.md
index 9475dba43e..6655aad7db 100644
--- a/structure/06_docs-and-release.md
+++ b/structure/ops/docs-and-release.md
@@ -1,4 +1,4 @@
-# Docs And Release SOT
+# Docs And Release
 
 ## Public docs
 
@@ -19,13 +19,7 @@ https://opencodex.me/
 The workflow runs on `main` pushes touching `docs-site/**` or the workflow itself, builds
 `docs-site`, uploads the artifact, and deploys with GitHub Pages.
 
-[Decision Log]
-- 목적과 의도: Serve the public documentation from the memorable first-party `opencodex.me` domain.
-- 기존 구현 및 제약 조건: The project Pages site was built for `lidge-jun.github.io/opencodex`, so Astro emitted a `/opencodex` base path that returns 404 under a root custom domain.
-- 검토한 주요 대안: Keep the GitHub project URL as canonical; redirect the custom domain through Cloudflare; configure the custom domain directly on GitHub Pages and build for the domain root.
-- 선택한 방식: Keep GitHub Actions Pages hosting, configure `opencodex.me` as the repository custom domain, publish root-relative assets and routes, and retain the default GitHub URL only as GitHub's automatic redirect.
-- 다른 대안 대신 이 방식을 선택한 이유: Direct Pages hosting preserves the existing deployment and HTTPS lifecycle without adding a second proxy or redirect service.
-- 장점, 단점 및 영향: Public links and canonical metadata become stable and branded. DNS and the Pages custom-domain setting are now deployment dependencies, and old hardcoded `/opencodex` links must not be reintroduced.
+> Decision record: [ADR-0080](../decisions/ADR-0080-github-pages.md)
 
 Local validation:
 
@@ -57,23 +51,11 @@ An official image would create a larger release surface requiring maintained bas
 updates, vulnerability scanning, SBOM, signing, registry provenance, rollback, and support policy.
 Those controls still have no owner, so there is no image-publish workflow or official registry tag.
 
-[Decision Log]
-- 목적과 의도: Document a reproducible container topology without silently creating an official image channel.
-- 기존 구현 및 제약 조건: The documentation recipe was not executable from the repository root, file-backed Compose secret ownership varies by implementation, and no registry workflow, scanner, SBOM/signing chain, or image rollback policy exists.
-- 검토한 주요 대안: Publish an official image; keep only copied documentation snippets; ship a maintained source recipe with a volume-backed stdin bootstrap.
-- 선택한 방식: Maintain the root source-build recipe, persist the owner-only token in the state volume, publish only `10100`, and leave registry publication out of scope.
-- 다른 대안 대신 이 방식을 선택한 이유: A runnable source recipe can be tested and reviewed without claiming provenance and operational controls the project does not provide.
-- 장점, 단점 및 영향: Compose users get a reproducible non-root deployment and safe first-run secret path; operators still own image builds, upgrades, external TLS/tailnet management, and rollout policy.
+> Decision record: [ADR-0081](../decisions/ADR-0081-container-deployment-recipe.md)
 
 ## Windows service wrapper and incomplete updates
 
-[Decision Log]
-- 목적과 의도: Prevent a failed npm replacement from making the Task Scheduler wrapper retry missing package files forever.
-- 기존 구현 및 제약 조건: The wrapper deliberately restarts a proxy after runtime crashes, but an absent baked Bun or CLI path cannot recover inside that process. Current updater preflight and stop-first behavior reduce replacement risk but do not provide a transactional restore of npm's package tree and global launchers.
-- 검토한 주요 대안: Keep unconditional five-second retries, add a generic crash ceiling, restore npm directories in-place, or classify only proven missing executable paths as terminal.
-- 선택한 방식: Check the baked Bun and CLI paths before every spawn; log one actionable incomplete-install message and exit with code 3 when either is absent. Preserve the existing retry loop for a child that actually launched and then failed.
-- 다른 대안 대신 이 방식을 선택한 이유: A generic retry ceiling can stop a service after unrelated intermittent crashes, while copying a package directory without matching npm shims, ownership, and lock guarantees is not a safe rollback.
-- 장점, 단점 및 영향: File-less package skeletons no longer produce unbounded service logs or restart churn. The wrapper still recovers ordinary proxy crashes, but repairing an incomplete npm install remains an explicit reinstall plus `ocx service repair` operation until a verified staged-update design exists.
+> Decision record: [ADR-0082](../decisions/ADR-0082-windows-service-wrapper-and-incomplete-updates.md)
 
 ## GitHub workflow map
 
@@ -125,7 +107,7 @@ manual. When an investigation graduates into a maintained invariant, summarize i
 
 ## Branch and devlog policy
 
-[`AGENTS.md`](../AGENTS.md) and [`MAINTAINERS.md`](../MAINTAINERS.md) are authoritative; this section
+[`AGENTS.md`](../../AGENTS.md) and [`MAINTAINERS.md`](../../MAINTAINERS.md) are authoritative; this section
 exists so the repository-shape source of truth does not omit the shape of its own history.
 
 - `dev` is the single integration branch and the target for ordinary pull requests. `main` moves only
@@ -161,13 +143,7 @@ helper validates this actor/base exception separately from its default contribut
 path; it does not certify CI or security review. The PR-only bypass leaves direct pushes,
 force-pushes and deletion blocked. `main` and `preview` retain their existing review rules.
 
-[Decision Log]
-- 목적과 의도: Make project ownership and review authority discoverable without exposing credentials or treating a documentation file as an access-control mechanism.
-- 기존 구현 및 제약 조건: Contribution and security docs referred to maintainers generically, while the repository had no maintainer roster or CODEOWNERS policy. GitHub permissions can change independently of the source tree.
-- 검토한 주요 대안: Keep the roster only in GitHub settings; introduce a larger standalone governance charter; list raw GitHub permission levels in the repository.
-- 선택한 방식: Add a concise maintainer roster and merge policy, use CODEOWNERS for review routing, and keep actual permission state authoritative in GitHub settings.
-- 다른 대안 대신 이 방식을 선택한 이유: A two-maintainer project needs clear ownership and sensitive-path review rules but does not yet need a separate governance framework.
-- 장점, 단점 및 영향: Contributors can identify reviewers and merge expectations directly from the repository. The roster must be updated when responsibilities change, and CODEOWNERS still requires branch-protection configuration to enforce approvals.
+> Decision record: [ADR-0083](../decisions/ADR-0083-maintenance-governance.md)
 
 ## Package runtime (bundled Bun)
 
@@ -204,7 +180,7 @@ Opening a release starts with the `dev` pre-move. Dispatch
 `.github/workflows/dev-version-bump.yml` with the intended version, merge the pull request it opens,
 then promote and release. A no-op is valid when `dev` already outranks the target. `release.yml`
 independently enforces that readiness condition and refuses publication if the pre-move is missing.
-The design and repair history live in `devlog/_plan/260904_release_version_line/`.
+The design and repair history live in `devlog/_fin/260904_release_version_line/`.
 
 Opening a preview for the next core ends the current patch line. After
 `vX.Y.0-preview.*` is tagged, a fix ships as part of `X.Y.0`, not as
@@ -324,3 +300,19 @@ This keeps release runs short and makes release a deployment of a verified commi
 ## Remote Hub locale and release gate
 
 The Remote Hub guide and affected CLI, server-config, management-API, and dashboard references have eight sources: root English plus `fr`, `ko`, `zh-cn`, `zh-tw`, `ru`, `ja`, and `tr`. English is canonical; commands, defaults, endpoint auth, and warnings remain exact in translations. A release requires the remote-only focused/full gates, privacy scan, GUI/docs builds, protocol compatibility receipts, and the MAINTAINERS security review for the exact head.
+
+Codex display-cache expiry, retained main-policy evidence, and reset history follow the
+[quota cache contract](../providers/openai-tiers.md#quota-cache-and-short-window-history).
+
+The Combo guides describe the distinction between display quota and single-credential inference evidence used by routing. See [scoped provider quota](../runtime.md#scoped-provider-quota-for-combo-selection).
+
+The management quota DTO keeps Combo editing aligned with scoped inference evidence;
+see [Combo editor routing quota](../gui-and-management-api.md#combo-editor-routing-quota).
+
+## Paginated history writer boundary
+
+`src/codex/history-provider.ts` refuses external writes to paginated or migration-capable history. `src/codex/inject.ts` checks affected rows and manifest-owned restore targets before artifact changes and compensates detected migration. Failed config restore stops later catalog/history work. See the [history writer contract](../codex-home.md#paginated-history-writer-boundary) for guarantees and concurrent-writer limits.
+
+The integrations guide documents Cline CLI as a two-file, loopback-only integration. Hosted CI validates its source-backed fixtures; the packaged dashboard exposes it through the existing client list.
+
+The lightweight top-level CLI help counts Cline CLI among the fifteen registered export clients; registry parity remains covered by the client help and integration tests.
diff --git a/structure/ops/service-and-sidecars.md b/structure/ops/service-and-sidecars.md
new file mode 100644
index 0000000000..39dc9a82da
--- /dev/null
+++ b/structure/ops/service-and-sidecars.md
@@ -0,0 +1,144 @@
+# Background Service And Sidecars
+
+## Background service command selection
+
+A bare `ocx service` is an idempotent install-or-repair command. Argument validation happens before
+any platform status probe. macOS and Linux choose from the registration file's proven presence;
+Windows combines the Task Scheduler and WinSW probes into `installed`, `absent`, or `unknown`.
+Only proven absence enters registration. A query failure refuses the bare command with status
+guidance, because treating `unknown` as absent can rerun elevated `schtasks /create` against an
+existing task. Explicit `ocx service install` remains the operator-owned registration request.
+
+> Decision record: [ADR-0028](../decisions/ADR-0028-background-service-command-selection.md)
+
+## Windows startup ownership listing reuse
+
+One proxy startup asks service-home ownership twice before listen: once before cache invalidation and
+again immediately before native-main lifecycle preparation. The second targeted Task Scheduler query
+is a deliberate race check and remains mandatory. On a localized host, however, the same nonzero
+targeted answer can require a full task listing with a 20-second ceiling; running that identical
+enumeration twice made a measured 12.3-second fallback cost roughly 25 seconds before listen.
+
+> Decision record: [ADR-0029](../decisions/ADR-0029-windows-startup-ownership-listing-reuse.md)
+
+## Stable service launcher (launchd and systemd)
+
+Launchd and systemd installation resolve the first absolute `ocx` PATH candidate that is both a regular file
+and executable, keeps that path lexical so a version-manager shim remains an indirection, and
+records the same single resolution in the service definition and service state. Definition
+construction (`buildPlist`, `buildUnit`) never performs PATH discovery itself: callers provide either the resolved launcher or an explicit direct Bun/CLI
+fallback, keeping diagnostics and tests independent of the host PATH.
+
+Launcher mode omits the package-local Bun provenance pair because an upgrade may delete that
+versioned tree. The only runtime path carried through the launcher is a pre-Bun, proof-bound
+`OPENCODEX_BUN_PATH` whose durable runtime source is `override`; bundled and process fallbacks are
+rediscovered by the current launcher. The API-auth token remains file-backed and is loaded only by
+the service shell at start. On macOS, `start` and detailed `status` compare the live launchd job
+against `expectedLaunchdCommand`, which follows the recorded `launcherPath` rather than re-walking
+PATH, so a launcher-backed job is never misreported as an older plist (#3464).
+
+> Decision record: [ADR-0030](../decisions/ADR-0030-stable-service-launcher-launchd-and-systemd.md)
+
+## Sidecars
+
+Web search and vision sidecars run only when the main request needs that capability and a usable
+sidecar authority exists. Vision has two possible backends; web search's config union additionally
+admits `xai`, `gemini`, and `exa`. xAI is a live explicit-only backend through stored Grok OAuth;
+Gemini and Exa remain inert until their executors ship. Selection differs per sidecar:
+
+| Sidecar | Backend selection | Default model | Activation |
+| --- | --- | --- | --- |
+| `web-search/` | Explicit configuration only: unset always resolves to the OpenAI forward path. No backend — Anthropic or otherwise — is auto-selected from credential availability (doing so once sent OpenAI model ids to the Anthropic API). Explicit xAI requires usable stored Grok OAuth and may add hosted `x_search`; explicit Gemini/Exa remain fail-closed until their executors land. | `gpt-5.6-luna` (OpenAI), `claude-sonnet-5` (Anthropic), `grok-4.6` (xAI) | Hosted `web_search` requested by a non-passthrough routed model. |
+| `vision/` | Explicit configuration wins for both backends. Only an unset backend auto-selects: Anthropic when a usable Anthropic OAuth provider exists, otherwise the OpenAI forward authority. An explicitly selected backend whose authority is unavailable produces no plan rather than falling back. | `claude-sonnet-5` (Anthropic), `gpt-5.6-luna` (OpenAI) | Input contains images for a model listed in `noVisionModels`. |
+
+The asymmetry is in the unset case only: vision may describe an image with whichever model can see
+it, while a hosted search tool is tied to a provider-specific tool contract, so search never infers
+Anthropic from credentials alone.
+
+On the OpenAI path there is one deterministic `openai` sidecar candidate and its current account mode
+owns credential selection; API-key OpenAI is not a ChatGPT forward sidecar candidate.
+
+Sidecar failures must degrade to text markers or skipped capability, not abort the main request.
+
+### Grok snapshot module ownership
+
+The client-specific tracker lives in `grok-responses-snapshot-repair.ts`; the
+provider-opt-in tracker remains in `responses-snapshot-repair.ts`. Their unchanged
+object guard, JSON block encoder and retained-item shape live in the dependency-
+free `responses-snapshot-codec.ts`. Core imports each tracker directly. No existing
+snapshot export moves, and neither tracker imports the core dispatcher. The Grok
+marker selects compatibility behavior and conveys no authenticated client identity.
+
+Manual and automatic OAuth/API-key selection commit through their shared selection owners before
+dispatch. Selection revisions fence stale retries and reselection; request identity includes the
+actual committed account/key. Generic proactive selection is opt-in and preserves a healthy active
+account, while reactive429 recovery remains enabled even with the pool off. Post-commit selection
+events immediately invalidate dashboard roster state; see`structure/gui-and-management-api.md`.
+
+
+### Incomplete quota terminals
+
+A native forward response that ends with quota or rate-limit evidence in an
+`incomplete` terminal records account quota failure and spawn-fallback health.
+Structured `incomplete_details.reason` and error codes are accepted without a
+message; ordinary output-limit, filtering, steering and stall incompletes do not
+cool an account. Cyber-policy classification retains precedence. The terminal is
+not replayed after output, and fixed-account request selection remains fixed.
+
+Remote compact requests release the server request-idle timeout only after a complete
+JSON object with a valid model has been read. Partial or invalid uploads retain
+the listener guard; admitted compaction then uses the upstream operation's own
+deadlines and client cancellation.
+
+Buffered routed compaction treats nonempty text and reasoning deltas as progress
+without exposing partial summary text. Comments, empty deltas and gateway
+keepalives do not reset the adapter-event stall watchdog. The default stall
+timeout stays 300 seconds; encrypted compaction content is preserved unchanged.
+
+Native compact response buffering also enforces a body-byte inactivity deadline
+using `stallTimeoutSec` (300 seconds by default). Nonempty chunks reset that
+deadline; a stalled body returns HTTP 504, client cancellation retains HTTP 499,
+and cleanup does not wait for a stuck upstream cancellation promise. The 32 MiB
+response ceiling and the original body bytes are preserved.
+
+A canonical upstream WebSocket refused-create error can become an HTTP 4xx only
+before the response is committed and after stream correlation checks. Permitted
+quota headers are bounded and rebuilt without upstream framing headers; the JSON
+response is not cacheable. Post-commit and 5xx errors keep the no-resend path.
+
+When encrypted agent-task recovery refuses a routed task, its existing 400 error
+can include a bounded `recovery_reason`: `unsupported_envelope`,
+`admission_denied`, `recovery_unavailable`, `caller_cancelled`, `input_changed`,
+`recovery_http_rejected`, `recovery_timeout`, `recovery_aborted`,
+`recovery_transport_error`, or `recovery_invalid_output`.
+HTTP rejection requires an observed non-success response. Invalid output includes
+invalid UTF-8, oversized bodies, malformed or incomplete recovery streams, and
+invalid or conflicting assignments. A caller's cancellation takes precedence over
+an owned deadline, which takes precedence over decode/transport failures.
+`recovery_aborted` describes a shared recovery cancelled independently of that caller.
+Shared-flight waiters receive the same underlying failure unless individually cancelled;
+only successful plaintext is cached. Diagnostics contain no upstream error or payload text.
+The field is omitted when no classified recovery result exists, and existing combo
+branches that return the original target failure keep that response.
+`recovery_unavailable` includes cache/singleflight capacity and does not prove an
+upstream request was attempted. No retry or broader envelope acceptance is enabled.
+
+## Voice diagnostic metadata
+
+`src/server/live.ts` owns optional `OCX_LIVE_FRAME_LOG` diagnostics for both sideband directions.
+The JSONL schema contains only `ts`, `dir`, `kind`, `bytes`, and `fffd`. It never stores frame
+content or transcript excerpts, and logging failures do not affect transparent frame delivery.
+Binary detection decodes only the supplied buffer view; malformed UTF-8 can itself produce U+FFFD,
+so the flag does not identify the peer responsible for corruption. Existing diagnostic files are
+not rewritten. Audio devices, WebRTC media negotiation, captions and spoken handoff delivery remain
+client responsibilities.
+
+Chat helper admission in `src/server/responses/core.ts` follows the
+[deferred stored-main contract](../providers/openai-tiers.md): only a needed Direct OpenAI helper
+claims stored main, after terminal vision, routed vision and search exclusions.
+
+The management quota DTO keeps Combo editing aligned with scoped inference evidence;
+see [Combo editor routing quota](../gui-and-management-api.md#combo-editor-routing-quota).
+
+Claude replay carries [Go conversation affinity](../data-planes/inbound-compat.md#claude-affinity-at-final-go-dispatch)
+privately to final dispatch; preliminary route selection does not inject Go-only headers.
diff --git a/structure/00_overview.md b/structure/overview.md
similarity index 55%
rename from structure/00_overview.md
rename to structure/overview.md
index 4ca10c0e16..d5d1a2207a 100644
--- a/structure/00_overview.md
+++ b/structure/overview.md
@@ -1,33 +1,10 @@
-# opencodex Structure
-
-This folder is the maintainer source of truth for the current system shape. Public user workflows
-belong in `docs-site/`. Development work is recorded in `devlog/` units — `_plan/` while open,
-`_fin/` once closed — while `docs/` keeps investigations and diagnostic notes worth retaining for
-archaeology, debugging, or source research.
-
-## Reading order
-
-| File | Purpose |
-| --- | --- |
-| [`00_overview.md`](00_overview.md) | Product boundary, local state, and non-negotiable invariants. |
-| [`01_runtime.md`](01_runtime.md) | Process lifecycle, CLI, server endpoints, config, providers, adapters. |
-| [`02_config-and-codex-home.md`](02_config-and-codex-home.md) | `CODEX_HOME`, the config surface, both injection forms, profile files, restore rules, and Codex-home diagnostics. |
-| [`03_catalog-and-subagents.md`](03_catalog-and-subagents.md) | Shared Codex catalog and per-catalog backups, account namespaces and pool rotation, model cache, effort ceilings, multi-agent surface mode, and subagent ordering. |
-| [`04_transports-and-sidecars.md`](04_transports-and-sidecars.md) | Responses HTTP/SSE, WebSocket opt-in, per-provider transport hardening, the transport inventory, sidecars, and compatibility guards. |
-| [`05_gui-and-management-api.md`](05_gui-and-management-api.md) | Dashboard serving and surfaces, plus the `/api/*` management surface and which module owns each route area. |
-| [`06_docs-and-release.md`](06_docs-and-release.md) | Public docs site, GitHub Pages, the workflow map, branch and devlog policy, README ownership, release flow. |
-| [`07_design-methodology.md`](07_design-methodology.md) | Design process discipline for new GUI, CLI, and user-facing surfaces. |
-| [`08_openai-provider-tiers.md`](08_openai-provider-tiers.md) | OpenAI Pool/Direct account-mode and API credential/routing invariants. |
-| [`09_client-integrations.md`](09_client-integrations.md) | Third-party client config ownership, state classification, snapshots, refresh, disable, and restore. |
-| [`09_compatibility-lab.md`](09_compatibility-lab.md) | Optional Compatibility Lab evidence, automation, and core-runtime isolation. |
-| [`10_adapter-registry.md`](10_adapter-registry.md) | Adapter construction authority and registry-derived contract inheritance. |
-| [`11_compatibility-contracts.md`](11_compatibility-contracts.md) | Versioned provider compatibility claims and fixture-evidence boundaries. |
+# Overview
 
 ## Product boundary
 
 opencodex is a local proxy for Codex. It does not patch Codex binaries. It changes local Codex
 state by writing root routing keys and a model catalog — a provider table only in the
-API-auth-header form described in [`02_config-and-codex-home.md`](02_config-and-codex-home.md) —
+API-auth-header form described in [`config.md`](config.md) —
 then serves the Responses data plane:
 
 ```text
@@ -53,13 +30,7 @@ pay-as-you-go, Coding Plan, and Agent Plan endpoints. Additional
 providers are routed by explicit `provider/model`, provider model lists, or the configured
 `defaultProvider`.
 
-[Decision Log]
-- 목적과 의도: Add two widely used API-key providers through the canonical registry so CLI, GUI, login, routing, and documentation remain in parity.
-- 기존 구현 및 제약 조건: Tencent Coding Plan is OpenAI-compatible but contractually restricted to interactive coding tools and has a dynamic, text-only model set. SiliconFlow exposes a dynamic OpenAI-compatible catalog whose reasoning controls vary by model.
-- 검토한 주요 대안: Treat both as custom providers only; freeze a large SiliconFlow model list and reasoning map; expose Tencent without a usage warning.
-- 선택한 방식: Add registry-derived key presets, keep live discovery enabled, seed only Tencent's currently documented coding-plan models, and surface Tencent's usage restriction in both the preset note and public docs.
-- 다른 대안 대신 이 방식을 선택한 이유: Registry presets remove setup friction while live discovery avoids claiming that mutable catalogs are permanent. Avoiding speculative SiliconFlow reasoning metadata prevents invalid vendor-specific parameters.
-- 장점, 단점 및 영향: Both providers appear consistently across supported setup surfaces. Tencent users receive an explicit policy warning; SiliconFlow reasoning controls remain conservative until model-specific limits can be represented safely.
+> Decision record: [ADR-0001](decisions/ADR-0001-product-boundary.md)
 
 ## Local state
 
@@ -79,7 +50,7 @@ opencodex state root does not undo those writes. Putting native Codex back is th
 | `~/.opencodex/config.json` | opencodex | Init creates via private temp plus no-replace hard link; dashboard and explicit updates use atomic replacement. |
 | `~/.opencodex/auth.json` | opencodex | OAuth tokens; not committed. Multiauth shape: `provider -> { activeAccountId, accounts[] }` (legacy single-credential values normalize on load; a one-time `auth.json.pre-multiauth` backup guards downgrades). ChatGPT scratch OAuth stays separate from the Codex account store. For multi-slot providers, credentials without `accountId`/email replace the active slot on a normal login; an explicit add-account login preserves the prior slot and appends a distinct one. Single-slot providers such as ChatGPT remain replacement-only. |
 | `~/.opencodex/codex-accounts.json` | opencodex | Hardened main-plus-added credential store used by `openai` in Pool mode. |
-| `~/.opencodex/catalog-backup.json` | opencodex | One-time pristine Codex catalog backup for restore; per-catalog copies are hashed variants (see [`03_catalog-and-subagents.md`](03_catalog-and-subagents.md)). |
+| `~/.opencodex/catalog-backup.json` | opencodex | One-time pristine Codex catalog backup for restore; per-catalog copies are hashed variants (see [`catalog.md`](catalog.md)). |
 | `~/.opencodex/usage.jsonl` | opencodex | Append-only request usage log (0o600); request metadata + token counts only, never prompts or auth. |
 | `~/.opencodex/ocx.pid`, `runtime-port.json`, `system-env-port` | opencodex runtime | Live process identity and the port a client should reach; rewritten on start. `runtime-port.json` also carries the protected per-process listener-attestation key used before CLI diagnostics attach a management bearer. |
 | `~/.opencodex/codex-runtime.json`, `codex-runtime-clamp.json` | opencodex Codex runtime | Selected Codex executable/version state and effort-clamp diagnostics. Not process identity: these persist a resolved choice and a diagnostic, so losing them changes behavior until re-resolved. |
@@ -96,21 +67,44 @@ opencodex state root does not undo those writes. Putting native Codex back is th
 
 ## Non-negotiable invariants
 
-- `websockets` defaults to `false`; only `true` advertises `supports_websockets`.
-- `CODEX_HOME` wins over `~/.codex` when present and valid.
-- Root TOML keys such as `model_provider` and `model_catalog_json` must stay before any table.
-- Routed model slugs use `provider/model`.
-- OpenAI has one `openai` Codex-login provider with Pool(default)/Direct modes and a separate `openai-apikey`; see [`08_openai-provider-tiers.md`](08_openai-provider-tiers.md).
-- Codex `spawn_agent` visibility depends on the first five featured catalog entries.
-- The management plane (`/api/*`) and the data plane (`/v1/*`) never share an admission credential.
-- `ocx stop`, `ocx restore`, and service stop/uninstall must leave native Codex usable.
-- `tests/` is organised by domain (`tests/<domain>/`, mirroring `src/`); the map is
-  `scripts/test-layout/layout.json` and `tests/test-layout.test.ts` rejects a test outside its
+Each invariant carries a stable id. A bound invariant names one test, and that test names the id
+back, so deleting or renaming the test fails `bun run structure:check` instead of quietly unbinding the
+rule. The binding proves the test EXISTS and is claimed; it does not prove the assertions inside it
+still cover the rule, which is a judgement only review makes.
+
+- **INV-WS-01** — `websockets` defaults to `false`; only `true` advertises `supports_websockets`.
+  Enforced by `tests/codex-integration/codex-catalog.test.ts`.
+- **INV-TOML-01** — Root TOML keys such as `model_provider` and `model_catalog_json` must stay
+  before any table.
+  Enforced by `tests/codex-integration/codex-inject.test.ts`.
+- **INV-OPENAI-01** — OpenAI has one `openai` Codex-login provider with Pool(default)/Direct modes
+  and a separate `openai-apikey`; see [`openai-tiers.md`](providers/openai-tiers.md).
+  Enforced by `tests/adapters/openai/openai-provider-option.test.ts`.
+- **INV-AGENT-01** — Codex `spawn_agent` visibility depends on the first five featured catalog
+  entries.
+  Enforced by `tests/codex-integration/catalog-full-picker-order.test.ts`.
+- **INV-AUTH-01** — The management plane (`/api/*`) and the data plane (`/v1/*`) never share an
+  admission credential.
+  Enforced by `tests/server/server-management-auth.test.ts`.
+- **INV-RESTORE-01** — `ocx restore` returns the pristine Codex catalog, so a restored install is a
+  usable native Codex. The service-stop and uninstall paths of the same promise are covered
+  separately in `tests/cli/restore-completes-shared-teardown.test.ts` and are not bound to this id.
+  Enforced by `tests/codex-integration/codex-catalog-restore.test.ts`.
+- **INV-TESTS-01** — `tests/` is organised by domain (`tests/<domain>/`, mirroring `src/`); the map
+  is `scripts/test-layout/layout.json` and `tests/test-layout.test.ts` rejects a test outside its
   domain. Only the two layout guards sit at the root. Source-oracle tests reach the repository
   through `tests/helpers/repo-root.ts`, never `import.meta.dir + "/.."`.
+  Enforced by `tests/test-layout.test.ts`.
 
-## Writing rule
+Two invariants are stated here without a binding, and `grace.unboundInvariants` in
+[`manifest.json`](manifest.json) carries the reason for each. They are true statements about the system;
+no test in this repository currently pins them, and saying so is more useful than naming a test that
+would pass while the rule was violated.
 
-Keep this directory flat. Add or extend lexicographically ordered `NN_topic.md` files; do not add
-subdirectories. If one file grows too broad, split the next stable topic into the next unused number
-instead of creating nested folders.
+- **INV-HOME-01** — `CODEX_HOME` wins over `~/.codex` when present and valid.
+- **INV-SLUG-01** — Routed model slugs use `provider/model`.
+
+The management quota DTO keeps Combo editing aligned with scoped inference evidence;
+see [Combo editor routing quota](gui-and-management-api.md#combo-editor-routing-quota).
+
+Cline CLI is a managed file integration: its provider settings and catalog share one recoverable journal operation. The [paired-file contract](clients/integrations.md#cline-paired-files) defines its stop/restart requirement.
diff --git a/structure/providers/chat-compat.md b/structure/providers/chat-compat.md
new file mode 100644
index 0000000000..e0b87add2d
--- /dev/null
+++ b/structure/providers/chat-compat.md
@@ -0,0 +1,266 @@
+# Chat Provider Compatibility
+
+## Reasoning and tool-result compatibility
+
+Kiro groups only consecutive original-message tool results whose raw call ID exactly matches
+the originating call. Its wire-ID map retains the original ID privately so replacement or
+truncation collisions cannot join unrelated results. Every non-tool message ends the group,
+including a reasoning-only assistant omitted from the Kiro turns. Group finalization preserves
+single-result normalization, ordered meaningful raw text and whitespace in multi-result output,
+failure text, image order and sticky error status. Empty hints are applied once for an entirely
+text-empty group, not once per chunk; local grouping state never enters the wire payload.
+
+`src/responses/task-input.ts` recognizes complete external Codex task-input envelopes
+before translated Responses adapters: `function_call_output`, no `call_id` property,
+nonblank `id`/`name`/`namespace`, and fully representable nonempty text/image output.
+`parser.ts` emits a user turn, clears pending reasoning and includes that turn in the
+existing continuation conversation-boundary calculation. The metadata is structural,
+not authentication. Unknown/opaque/malformed parts reject the entire conversion;
+ordinary missing/empty tool call ids retain the existing translated-route 400 guard.
+Native passthrough and compaction retain raw-body handling. The leaf reuses the input
+content converter after validation and imports no optional subsystem.
+Stateful developer-guidance injection reuses that validator for its raw insertion
+boundary, so parsed messages and stored raw history retain the same task/guidance order.
+
+Native OpenAI passthrough sanitizes routed reasoning history so `reasoning` input items do not send
+non-empty `content` arrays to upstream models that reject them. Chat Completions bridging repairs
+orphan `toolResult` messages by inserting a synthetic assistant `tool_call` before tool messages.
+It also repairs the opposite direction (260718): an assistant `tool_calls` round left dangling —
+by an intervening user/developer barrier or an interrupted turn — is closed by deferring barrier
+messages until the round completes, reattaching real results to their original call occurrence,
+and synthesizing explicit "no tool result was recorded" answers only when no real result exists
+(Kimi/Moonshot 400 `ocx-mrqaiw05-269`; unit `devlog/_fin/260718_dangling_toolcall_hardening`).
+
+Forward-mode OpenAI passthrough also repairs replayed `call_id` values longer than the Responses
+API's 64-character limit. Sidechat/fork replay can namespace routed-provider ids beyond that limit,
+so each oversized id and all matching call/output items receive the same deterministic,
+request-local alias. Raw API-key continuations deliberately preserve ids because an output-only
+continuation may reference a call stored upstream under its original id; proxy-expanded API-key
+replays are explicit and receive the same repair.
+
+These compatibility guards are covered by focused tests and should stay close to the adapters that
+need them.
+
+Responses passthrough always removes output-only `status` from `reasoning` input items, including
+items that retain opaque `encrypted_content`. The prior retains-blob-keeps-status invariant was
+defensive rather than observed: measured OpenAI reasoning items never contain `status`, and Grok
+accepts its own blob with `status` removed. Keeping it on a cold cross-backend replay instead made
+OpenAI reject the unknown field before validating the blob, starving opaque-blob recovery of the
+provenance error it needs. The established raw-`content` rule remains separate: ChatGPT accepts
+reasoning input only with empty `content`, so a native blob plus raw content keeps the blob but still
+blanks `content`. The blob is kept unless the in-process thread record proves that the current
+provider, destination, adapter, model, or credential differs from the route recorded for the prior
+request on that client thread. On a proven change the blob is removed while the reasoning item and
+its summary survive; `status` has already been removed on every path. Missing, expired, or evicted
+identity state is unknown. The comparison uses the durable destination and credential identities
+with the provider, adapter, and model, so OAuth token-generation refreshes do not look like backend
+changes; when either durable dimension is unavailable it refuses to record rather than falling back
+to a volatile identity. Route binding only compares: it does not replace the recorded identity until
+the destination successfully serves the turn. Bridged streams commit on a completed or incomplete
+terminal; native passthrough streams use the non-error upstream status before relay as their success
+boundary so the proxy does not retain request state across the whole stream. This deterministic
+pre-flight is the primary path and covers threads the process has served while their record remains
+inside the TTL/LRU bounds. Missing, expired, evicted, and
+pre-process history stays fail-soft on the first send. If a Responses upstream then returns its own
+self-identifying opaque-blob 4xx (`invalid_encrypted_content`, or xAI's two `invalid-argument`
+decoder errors), the proxy rebuilds once through the same sanitation path: reasoning
+`encrypted_content` is removed and compaction blobs use the existing text degradation. A one-shot
+guard makes a second rejection terminal, and a successful recovery records the current serving
+identity so later route changes return to deterministic pre-flight. A cold-record cross-backend
+switch therefore costs one extra upstream round trip and one turn of degraded reasoning, rather than
+wedging the thread; unrelated 4xx responses and requests whose outbound body carries no blob never
+enter this recovery.
+
+After a self-identified opaque-blob rejection, the proxy also keeps a five-minute rejection memo.
+The memo key is the resolved conversation identity plus the durable serving identity: provider,
+destination, adapter, model, and credential. It is recorded only when the blobless recovery resend
+succeeds. A missing durable destination or credential prevents memo creation and lookup. On a later
+request with the same key, pre-flight sanitation removes opaque reasoning `encrypted_content` and
+degrades compaction blobs before the first upstream send. This skips the rejected first send and
+the recovery round trip. A different serving identity does not match the memo. Route changes still
+follow the normal pre-flight stripping rule. Memo expiry returns to the fail-soft recovery path.
+
+A combo target rotation between turns legitimately changes that serving identity, so the following
+turn drops blobs minted by the prior target. This is correct because the new target cannot decode
+them, but it is intentionally unobvious to the client: `pickComboTarget` keys selection state only by
+combo id, without a conversation dimension, and the SSE model-name rewrite preserves the requested
+combo name instead of exposing the concrete target switch. A user can therefore observe a reasoning
+cache drop with no visible model change.
+
+The image and web-search auxiliary loops consume `_reasoningReplayScope` for bridge-level replay but
+never call `bindRouteReasoningReplayScope`, so their internal small-model requests do not update the
+serving-identity record. That omission is intentional: binding those routes would poison the main
+conversation's last-serving identity and cause a later main-model turn to strip valid blobs.
+
+> Decision record: [ADR-0051](../decisions/ADR-0051-reasoning-and-tool-result-compatibility.md)
+
+DeepSeek's stateless Responses compatibility pass normalizes only unambiguous tool-call batches.
+Calls emitted before the first matched output stay together as one assistant batch, followed by
+their outputs in call order; hook-injected messages that split the batch move after it without being
+dropped. This preserves #1292's single-call adjacency repair without splitting a same-turn parallel
+batch away from its preceding plaintext reasoning (#1477). Tolerant providers never enter this pass,
+and duplicate, missing, or backwards call/result pairs are left for the upstream to reject rather than guessed.
+
+> Decision record: [ADR-0052](../decisions/ADR-0052-reasoning-and-tool-result-compatibility.md)
+
+## OpenRouter provider routing
+
+The canonical OpenRouter `openai-chat` transport may carry optional provider-routing preferences
+from `OcxProviderConfig.openRouterRouting`, with exact model-id replacements in
+`modelOpenRouterRouting`. The adapter maps camel-case config to OpenRouter's request wire
+(`order`, `only`, `allow_fallbacks`) after the Codex-facing routed slug has been decoded to the
+native model id.
+
+Preferences are accepted only for `https://openrouter.ai/api/v1` (an optional trailing slash is
+equivalent) and the `openai-chat` adapter. Alternate ports, credentials, query strings, fragments,
+lookalike hosts, and custom proxy paths fail validation. A model override replaces rather than
+merges the provider-wide default, keeping precedence deterministic. With no preference configured,
+the request body is byte-for-byte unchanged in this area and OpenRouter retains its default routing.
+
+## Kimi Coding Plan prompt-cache affinity
+
+The canonical `kimi` OAuth and `kimi-code` API-key presets opt into forwarding the internal
+request's `prompt_cache_key` to Kimi's Chat Completions body. Kimi Code Plan documents a stable
+session/task key as required to improve cache hit rates. The chat adapter never invents a key of
+its own: it forwards what the request already carries — Codex's session key on
+`/v1/responses`, or the session-scoped key the Claude `/v1/messages` inbound derives
+(metadata.user_id hash, else the system+tools cohort hash) — and a request with no key stays
+keyless. An explicit provider-level `promptCacheKey: false` continues to opt out, and the flag is
+persisted through `providerConfigSeed`/`enrichProviderFromRegistry` for new configs; key-pool 429
+rotation keeps it — along with every other registry backfill — because the retry starts from the
+fresh committed provider row and routes it again (`rotateProviderTransportOn429` in
+src/providers/key-failover.ts). Stale request-time config fields are deliberately discarded so a
+concurrent deletion stays authoritative; only runtime `fetch` state and generated OpenCode session
+affinity survive the rebuild. If an opted-in upstream rejects the field, OpenCodex does not strip it and retry or mutate the
+saved configuration. Other OpenAI-compatible providers remain deny-by-default because strict
+backends may reject the OpenAI-specific field.
+
+## Parallel tool calls (default-on for chat providers)
+
+The openai-chat adapter buffers ALL streamed `tool_calls` deltas (keyed by `index`, falling back to
+`id`, then last-seen) and flushes them as atomic start/delta/end sequences at the terminal signal.
+This is required by the bridge's sequential tool-call contract and makes interleaved parallel
+deltas, id-only-first-chunk continuations, and whole-chunk multi-call frames all safe.
+
+Parallel tool calls are DEFAULT-ON for openai-chat providers: the adapter follows Codex's
+request-level `parallel_tool_calls` bit (default true) and routed catalog entries advertise
+`supports_parallel_tool_calls`. `OcxProviderConfig.parallelToolCalls: false` is the per-provider
+opt-out (registry-seeded, router-backfilled; an explicit user value always wins). Non-chat
+adapters advertise the catalog bit only on explicit `true`; cursor keeps its own special-casing.
+Providers with flaky parallel streaming can be opted out individually. Evidence and provider
+ledger: `devlog/_fin/260709_parallel_tool_calls/`.
+
+## Volcengine Ark assistant continuation shapes
+
+The `openai-chat` adapter keeps Volcengine's pay-as-you-go Chat endpoint and Coding Plan endpoint
+on separate empty-assistant contracts. The pay-as-you-go `/api/v3` route retains the structured
+`[{ "type": "text", "text": "" }]` placeholder inferred for #796, while `/api/coding/v3` uses the
+ordinary empty string accepted by its live tool-call continuation contract (#1571). Matching only
+the shared Ark hostname is too broad because the two endpoint families reject opposite shapes.
+
+> Decision record: [ADR-0063](../decisions/ADR-0063-volcengine-ark-assistant-continuation-shapes.md)
+
+## Chat structured-output compatibility
+
+First-party Kimi and Moonshot Chat destinations normalize a `$ref` with sibling keywords because
+their wire rejects that valid JSON Schema 2020-12 shape. Inlining preserves conjunction semantics:
+`required` members are unioned, lower numeric bounds take the maximum, upper numeric bounds take the
+minimum, and overlapping `properties` recurse with the same rules. The walk remains depth-, node-,
+and expansion-bounded. Unresolvable or cyclic references keep the existing bare-`$ref` fallback,
+and unrelated OpenAI-compatible providers retain the caller's schema unchanged.
+
+> Decision record: [ADR-0064](../decisions/ADR-0064-chat-structured-output-compatibility.md)
+
+The `openai-chat` adapter translates Responses `text.format` and Chat Completions
+`response_format` through one internal format, then emits `response_format` on the upstream chat
+wire. That remains the default because silently returning prose breaks clients that requested a
+JSON object or schema. A mixed-capability gateway may list exact native model ids in
+`noStructuredOutputModels`; only those models omit the wire field, while siblings keep the normal
+translation. The proxy does not infer this from provider names, localhost destinations, or a model
+family shared by unrelated upstreams.
+
+> Decision record: [ADR-0065](../decisions/ADR-0065-chat-structured-output-compatibility.md)
+
+## Anthropic structured-output compatibility
+
+The Anthropic adapter lowers Responses `text.format` and Chat Completions `response_format` JSON
+Schema requests to `output_config.format`. The local transform follows Anthropic's TypeScript SDK
+subset so upstream rejects neither OpenAI-only envelope fields nor unsupported schema constraints.
+The adapter merges `format` into an existing adaptive-thinking `output_config` rather than replacing
+it, so a compatible `output_config.effort` remains alongside the structured-output format.
+Routed Anthropic Messages input carries `output_config.format` through internal `text.format`, so
+stored-OAuth requests regain the same native format when the Anthropic adapter rebuilds the wire body.
+Unsupported constraints remain in `description` as model guidance instead of disappearing. Root
+`$defs` stay beside a root `$ref`, intentionally differing from the current SDK transform's early
+`$ref` return so local references remain resolvable.
+
+> Decision record: [ADR-0066](../decisions/ADR-0066-anthropic-structured-output-compatibility.md)
+
+## Reasoning display parity (hideThinkingSummary)
+
+Reasoning-envelope serialization uses preflight byte sizing and transient reservations before
+creating JSON, UTF-8, or base64 copies. Encoding also admits the matching decode projection, so
+a successfully encoded standalone envelope fits the standalone decoder's limit. Callers retain
+ownership of returned values; the helper releases only its temporary reservation. Inbound
+Anthropic translation carries one budget across all assistant blocks and accounts for retained
+envelopes until the response lifecycle disposes it. Standalone translation owns a temporary
+budget and disposes it on success or failure. Final translated-request sizing uses plain-JSON
+measurement rather than allocating a serialized copy just to measure it.
+
+> Decision record: [ADR-0067](../decisions/ADR-0067-reasoning-display-parity-hidethinkingsummary.md)
+
+`hideThinkingSummary` (request reasoning summary absent/"none" — the routed catalog default) is
+honored by BOTH reasoning paths: anthropic `thinking_delta` AND raw `reasoning_raw_delta`
+(openai-chat `reasoning_content`, kiro tags). Hidden reasoning emits an envelope-only reasoning
+item (`summary: []`, txt-only `ocxr1:` `encrypted_content`, no text deltas) — invisible in the
+Codex app, so tool cells group like native models — while the text still round-trips for
+`preserveReasoningContentModels` replay. Visible mode (summary "auto") keeps the raw
+`content[reasoning_text]` shape. Diagnosis and codex-rs grouping evidence:
+`devlog/_fin/260709_native_response_pattern/`.
+
+The content-to-summary channel rewrite skips any reasoning item that carries a native
+`encrypted_content` blob. The blob is opaque, state-bearing provider data, so the item must
+round-trip unchanged unless that backend has an explicit replay contract permitting a rewrite.
+This defensively protects providers that issue blobs and later join the route through
+`preserveReasoningContentModels`. The rewrite's round trip was verified against DeepSeek, which is
+`statelessResponses` and issues no blob. Grok is unaffected in practice because it natively emits
+summary-channel reasoning and no `reasoning_text` events, so this content-to-summary item rewrite
+does not engage on its route. Only the stored item is exempt — `reasoning_text` delta events carry
+no blob and still route to the summary channel, so the live expandable trace is unchanged.
+
+The process-local raw-reasoning fallback is fail-closed unless a request has an explicit client
+thread plus an exact provider destination, wire adapter, final model, and physical credential
+identity. API-key material is represented only by a process-keyed HMAC; OAuth replay is bound to the
+existing credential slot and exact credential generation, and an authentication-header override is
+folded into that identity without retaining the raw value. A token refresh intentionally starts a
+new fail-closed replay namespace. The destination is likewise process-HMACed because a configured
+base-URL path may itself be a credential. Header-only/keyless routes cannot establish a physical
+credential identity and therefore fail closed. Parsed-request copies and already-created bridges
+share one scope holder, and key/account rotation replaces its current identity before rebuilding
+the request. A retry may therefore reuse reasoning on the same physical target, but a provider, model, or
+credential failover receives the provider's configured placeholder instead of another target's raw
+reasoning.
+
+> Decision record: [ADR-0068](../decisions/ADR-0068-reasoning-display-parity-hidethinkingsummary.md)
+
+## Chat streamed tool-call identity
+
+`src/adapters/openai-chat.ts` retains a call's first observed non-negative safe integer
+index as an alias when the call started by ID. Every present, non-null index must
+be a number in that range: strings (including numeric and empty strings), booleans,
+objects, arrays, negative numbers, fractions and unsafe integers terminate the stream
+before any key, alias, ID or last-call matching. `Number.MAX_SAFE_INTEGER` is accepted;
+larger integers are rejected because distinct wire literals can parse to the same number.
+The invalid-index error releases all pending call reservations without emitting
+those calls or a successful completion; invalid indexes are never treated as absent.
+Only missing and null indexes are absent-index placeholders. Repeated ID, name and
+argument string-field tolerance retains its existing rules.
+
+For valid indexes, lookup preserves direct-key precedence, then index alias, then
+ID fallback. The initial key continues to own all translator budget reservations
+and release; learning an alias creates no additional owner. Unassociated index-only
+fragments are not guessed onto pending ID-only calls.
+`tests/adapters/openai/openai-chat-parallel-stream.test.ts` covers late aliases,
+parallel/colliding identities, distinct unsafe raw JSON index literals, the maximum
+safe-integer boundary, invalid index types, missing/null continuations and UTF-8
+byte-limit boundaries.
diff --git a/structure/providers/cursor.md b/structure/providers/cursor.md
new file mode 100644
index 0000000000..be42793e0b
--- /dev/null
+++ b/structure/providers/cursor.md
@@ -0,0 +1,84 @@
+# Cursor Provider
+
+## Cursor Native Exec
+
+Cursor's experimental live transport can receive server-driven local read/write/delete/ls/grep,
+shell, and fetch exec frames. These frames are denied by default because they bypass Codex's normal
+approval and sandbox path. `nativeLocalExec: "on"` is the explicit config-owner opt-in for trusted
+local experiments; `off` and the backwards-compatible `codex-sandbox` spelling both fail closed.
+MCP, screen recording, and computer-use stay on their separate explicit executor/MCP config paths.
+
+> Decision record: [ADR-0047](../decisions/ADR-0047-cursor-native-exec.md)
+
+Cursor's generic tool-use prompt filter must preserve every Responses-owned execution-path tool
+that survives the transport budget: unified Desktop `exec` as well as the legacy
+`exec_command`/`shell_command` aliases. The legacy aliases receive Cursor-specific shell guidance;
+unified `exec` keeps its own schema and is surfaced back to Codex as a client tool. It must never
+fall through to the separate native-local-exec dispatcher.
+
+> Decision record: [ADR-0048](../decisions/ADR-0048-cursor-native-exec.md)
+
+## Cursor parameterized models
+
+Cursor Router's parameterized `default` model is represented in Codex by four catalog rows:
+`cursor/auto` preserves Cursor's team/account default, while `cursor/auto-cost`,
+`cursor/auto-balance`, and `cursor/auto-intelligence` make each optimization level explicit.
+All four route to the `default` Cursor wire model. Explicit variants additionally populate
+`AgentRunRequest.requested_model.parameters` with the `optimization` parameter; this is the same
+parameterized-model channel used by current Cursor clients. Router rows are static capabilities and
+must survive a live `GetUsableModels` response that omits `default`.
+
+`cursor/grok-4.5-fast` and `cursor/grok-4.6-fast` are stable Codex-facing rows, but current Cursor
+clients do not request them as flat model slugs. OpenCodex sends the matching Grok base id through
+`requested_model` with separate `effort` and `fast=true` parameters, leaving legacy `model_details`
+unset for that parameterized external selection. Grok 4.5 stops at `high`; Grok 4.6 additionally
+advertises and sends `xhigh`. Live discovery recognizes Cursor's flattened
+`cursor-grok-{version}-{effort}-fast` variants, plus the older
+`grok-{version}-fast-{effort}` ordering, as availability evidence only.
+
+## Cursor active-context usage
+
+Cursor's `conversationCheckpointUpdate.tokenDetails.usedTokens` is treated as the authoritative
+absolute active-context size for a Cursor conversation. Some client-tool suspension turns must end
+before Cursor emits a new checkpoint; those turns carry forward the last observed total for the same
+Cursor conversation instead of reporting only the tiny current-turn output delta. The carry-forward
+cache is process-local, numeric-only, bounded, and keyed by Cursor conversation id. Compaction
+boundaries clear the carry so pre-compaction totals are not reused after Codex replaces history.
+Historical compaction markers restored by `previous_response_id` expansion are acknowledged as a
+replayed prefix and do not clear a fresh post-compaction checkpoint again on every later turn.
+Compaction summarizer turns may still report their own checkpoint for that response, but their
+pre-compaction checkpoint is not persisted for later carry-forward.
+
+> Decision record: [ADR-0053](../decisions/ADR-0053-cursor-active-context-usage.md)
+
+## Cursor conversation checkpoint reuse
+
+After a successful no-tool turn, the Cursor adapter keeps the returned ConversationStateStructure in
+a process-local store and reuses that snapshot on the next validated linear continuation instead of
+rebuilding rootPromptMessagesJson and conversationTurns. Tool-result turns reuse the last completed
+checkpoint plus only the uncovered suffix. A request without checkpointRef may use the prefix index
+only when a remembered Cursor conversation or stable client thread owns the resolved conversation id.
+The stable owner may be the Codex parent-thread header or the existing bounded process-local HMAC of
+the complete Desktop session-id/thread-id pair. The request must also have a covered message prefix
+and system/developer digest that match exactly one snapshot for that same
+conversation. Headerless requests without a stable owner full-replay. Isolated helper/shadow turns
+never join the parent or sibling conversation. An explicit missing checkpointRef full-replays. Compaction, account or model mismatch, missing refs, decode failures, and
+invalid_argument recovery keep the existing full-replay path. previous_response_id may select a
+branch's opaque checkpointRef; it is never a Cursor conversation ownership key. Cursor Connect still
+does not expose authoritative cache_read_tokens.
+
+> Decision record: [ADR-0054](../decisions/ADR-0054-cursor-conversation-checkpoint-reuse.md)
+
+## Cursor executable tool schema ownership
+
+`src/adapters/cursor/tool-schemas.ts` owns advertised and argument-normalization
+schemas; `tool-definitions.ts` remains the public facade and protobuf encoder.
+Advertisement and normalization intentionally differ for shell bridges: Cursor may
+emit `cmd`, while the declared Responses contract decides whether it becomes
+`command`. Both paths preserve execution-control fields. Freeform tools use one
+required string `input` in a closed object, retaining that tool's string-valued
+input description from the parser (including patch-envelope guidance). Other input
+constraints cannot widen the canonical shape. Bare shell bridge names are rejected
+on the freeform path.
+Namespaced tools do not acquire bare-shell behavior. Regression coverage lives in
+`tests/providers/cursor/cursor-tool-definitions.test.ts`.
diff --git a/structure/providers/google.md b/structure/providers/google.md
new file mode 100644
index 0000000000..26187aeebf
--- /dev/null
+++ b/structure/providers/google.md
@@ -0,0 +1,47 @@
+# Google Provider
+
+## Google thought-text visibility boundary
+
+Google-family responses may represent model-internal reasoning as a text-bearing part with
+`thought: true`. The Google adapter maps that text to the internal `reasoning_raw_delta` event;
+only text without the marker becomes visible `text_delta`. Streaming SSE and buffered JSON share
+one classifier so transport selection cannot change whether provider-declared reasoning is shown
+as assistant output. Thought-signature observation still runs on the original parts before text
+classification, preserving the opaque continuation state independently of display semantics.
+
+> Decision record: [ADR-0055](../decisions/ADR-0055-google-thought-text-visibility-boundary.md)
+
+## Google response-part field boundary
+
+Google-family adapters validate the values inside an otherwise well-formed response part before
+they become `AdapterEvent`s. A present `functionCall` must be an object with a nonblank string
+`name`; because Gemini delivers that call atomically rather than across deltas, an invalid name is a
+terminal protocol error and is never dispatched. A non-string optional `text` value is dropped
+without coercion, while the rest of the part and turn continue. Structured `functionCall.args`
+remain provider-native and are serialized as before.
+
+> Decision record: [ADR-0056](../decisions/ADR-0056-google-response-part-field-boundary.md)
+
+## Google tool-call thought-signature replay
+
+Gemini may attach an opaque `thoughtSignature` to a `functionCall` and requires that exact value on
+the matching model turn when its tool result is submitted. Antigravity and Vertex share the existing
+bounded TTL/LRU replay store, keyed by compiled function-call name plus canonical arguments. Vertex
+prefixes its cache model key with the transport, project, and location identity, so a signature
+minted by Vertex cannot be sent to Antigravity even when both routes expose the same public model id.
+Vertex prefers Codex's opaque `prompt_cache_key` for session identity and falls back to the existing
+first-user-message derivation for clients that omit it; only the fixed hash is retained.
+Both streaming and non-streaming responses feed the store; request compilation happens before replay
+so matching uses the provider-visible tool name.
+
+> Decision record: [ADR-0057](../decisions/ADR-0057-google-tool-call-thought-signature-replay.md)
+
+## Google tool-result adjacency repair
+
+Google-family requests serialize a model tool-call turn and its results as one adjacent
+`model -> user` pair. The user turn contains exactly one `functionResponse` for every representable
+call in original call order. Missing results use an explicit unknown-history marker; duplicate,
+mismatched, and standalone results become marked text instead of unpaired function responses.
+Representable data-URL images remain sibling `inline_data` parts in either case.
+
+> Decision record: [ADR-0058](../decisions/ADR-0058-google-tool-result-adjacency-repair.md)
diff --git a/structure/providers/kiro.md b/structure/providers/kiro.md
new file mode 100644
index 0000000000..4650e912dc
--- /dev/null
+++ b/structure/providers/kiro.md
@@ -0,0 +1,61 @@
+# Kiro Provider
+
+## Kiro client parallel-tool hint
+
+Kiro's wire remains serialized even when an OpenAI Responses client sends
+`parallel_tool_calls: true`. That request field is permissive: it allows parallel calls but does not
+require the routed transport to expose a matching flag. The Kiro catalog therefore continues to
+advertise `supports_parallel_tool_calls: false`, and the adapter emits no parallel-control field,
+while accepting the client hint and translating the ordinary tool catalog normally.
+
+> Decision record: [ADR-0060](../decisions/ADR-0060-kiro-client-parallel-tool-hint.md)
+
+## Kiro Responses text controls
+
+Kiro refuses structured output and tolerates every other Responses `text` member. `text.format`
+of type `json_schema` or `json_object` is a contract the CodeWhisperer wire cannot honour, so the
+adapter rejects it rather than returning prose to a caller expecting JSON. `text.verbosity` and
+`text.format: {"type":"text"}` are preferences, not contracts; they are accepted and dropped,
+because `buildKiroPayload` composes `conversationState` from parsed fields and never forwards the
+raw body.
+
+> Decision record: [ADR-0061](../decisions/ADR-0061-kiro-responses-text-controls.md)
+
+## Kiro reasoning round-trip (`redactedContent`)
+
+Kiro never returns plaintext reasoning for its **GPT-5.6 family** (`gpt-5.6-sol`, `-terra`,
+`-luna`): `reasoningContentEvent` carries a KMS-encrypted `redactedContent` blob, never `text`.
+Their `additionalModelRequestFieldsSchema` (`ListAvailableModels`) accepts only `reasoning.effort`
+with `additionalProperties: false` — there is no display/summary opt-in, so this is the only
+reasoning these models can return. Kiro's own CLI replays the blob on the matching
+`assistantResponseMessage.reasoningContent` to preserve model reasoning across turns; dropping it
+makes every turn restart without the previous turn's reasoning. Verified on kiro-cli 2.14.1 and
+2.16.0, all three models.
+
+The Claude 4.6+/5 entries advertise a different, richer contract (`thinking.type` adaptive/disabled,
+`thinking.display` summarized/omitted, `output_config.effort`, `max_tokens`) and are not covered by
+that measurement; older Claude, deepseek, minimax, glm, and qwen entries advertise no additional
+fields at all. The handling below keys off the wire field, not the model id, so any model that
+sends `redactedContent` round-trips.
+
+- The blob rides the existing `ocxr1:` envelope as `krc` (`src/responses/reasoning-envelope.ts`) on
+  an envelope-only reasoning item — `summary: []`, no text deltas — so it stays invisible in the
+  Codex app while round-tripping, exactly like the hidden-thinking path.
+- **Pairing is backwards.** Kiro emits `reasoningContentEvent` at the END of an assistant turn,
+  after content AND tool calls. A `krc`-only item therefore belongs to the turn that already
+  closed, so the parser attaches it to the PRECEDING assistant message rather than folding it into
+  the following turn like ordinary reasoning (`src/responses/parser.ts`). With no assistant turn to
+  own it, the blob is dropped rather than mis-paired.
+- The blob lives on `OcxAssistantMessage.kiroRedactedReasoning`, not on a thinking content part, so
+  no other adapter replays provider-private state if the conversation switches providers.
+
+Kiro reports context pressure in its own `contextUsageEvent`, which is the authoritative source. On
+every capture taken (2.14.1 and 2.16.0) `metadataEvent` carried only `stopReason` — which is why
+reading the percentage from `metadataEvent` alone never saw a value — but the parser still accepts a
+finite `contextUsagePercentage` (and a `tokenUsage` block) there as a fallback, so a value parsed
+from `metadataEvent` is legitimate rather than impossible. Both feed the same field, and any
+positive value overwrites an earlier one.
+
+Spend arrives in `meteringEvent` as **credits, not tokens**. No captured response carried
+`tokenUsage` on any event, which is why Kiro usage stays estimated; `meteringEvent` is currently
+ignored because a credit is not a token count.
diff --git a/structure/08_openai-provider-tiers.md b/structure/providers/openai-tiers.md
similarity index 78%
rename from structure/08_openai-provider-tiers.md
rename to structure/providers/openai-tiers.md
index f53cdb9b0c..ff5f33d9a3 100644
--- a/structure/08_openai-provider-tiers.md
+++ b/structure/providers/openai-tiers.md
@@ -1,4 +1,4 @@
-# OpenAI Provider Account-Mode SOT
+# OpenAI Provider Account Modes
 
 This current contract supersedes the provider-identity and account-selection sections of
 `devlog/_fin/260717_openai_hardening`; that archived unit remains historical evidence for the
@@ -51,19 +51,22 @@ alternate-main retry authentication; the original caller's native snapshot is se
 Optional Chat/Claude stored-main enrichment still requires
 the native-main turn claim.
 
+Chat's noncanonical caller-auth branch passes only an internal permission to resolve stored
+sidecar auth later. Final helper planning checks vision terminal/routed-backend and search
+tool-choice/compaction/runTurn exclusions before requesting a canonical Direct candidate.
+Only that concrete need, without an existing explicit snapshot or exact-account selection,
+can acquire a startup- and drain-fenced native-main claim and read the stored token. The pair
+stays local to sidecar headers; caller, primary, and retry authority are unchanged. Unrelated
+Cursor turns therefore leave native main switchable while their upstream remains active.
+Pool and exact-account sidecars continue through their existing account-selection path.
+
 The two routes also keep separate request-compatibility contracts. The canonical ChatGPT Codex
 forward destination removes public `prompt_cache_options` because that backend rejects the field
 before inference; `prompt_cache_key` remains supported. `openai-apikey` and noncanonical/custom
 Responses destinations preserve caller-provided options because their upstream contracts may
 support them.
 
-[Decision Log]
-- 목적과 의도: Let public Responses clients use the Codex-login route without one unsupported prompt-cache extension failing the whole turn.
-- 기존 구현 및 제약 조건: Parsing already preserves unknown top-level fields in `_rawBody`, and the canonical backend rejects `prompt_cache_options`; API-key and custom providers may accept the same field.
-- 검토한 주요 대안: Add the field to the Zod schema; strip it for every Responses provider; translate it to a legacy retention hint; remove it only at the canonical destination boundary.
-- 선택한 방식: Keep parser passthrough unchanged and strip the caller field only after `isCanonicalOpenAiForwardProvider` succeeds.
-- 다른 대안 대신 이 방식을 선택한 이유: Schema admission does not change `_rawBody`, global stripping would remove supported public API behavior, and translation would invent cache policy.
-- 장점, 단점 및 영향: VS Code and other public-shape clients avoid the canonical backend rejection while API-key/custom routes retain their wire options; canonical callers cannot request this cache option through OpenCodex.
+> Decision record: [ADR-0084](../decisions/ADR-0084-public-provider-contract.md)
 
 Pool affinity preserves the existing `x-codex-parent-thread-id` supplied by ordinary Codex clients.
 The parent id is trimmed and bounded under the same 512-byte component limit as the Desktop
@@ -75,23 +78,7 @@ and terminal outcome accounting carry the same key so route planning cannot prev
 and authenticate another, and a transient failure clears the binding that actually selected the
 account.
 
-[Decision Log]
-- 목적과 의도: Keep Desktop reconnects on the account selected for the App task without persisting
-  or exposing its session and thread identifiers.
-- 기존 구현 및 제약 조건: Pool affinity used only `x-codex-parent-thread-id`; Desktop requests can
-  omit it while stable `session-id` and `thread-id` headers remain available. Exact account
-  selectors must stay outside automatic Pool affinity.
-- 검토한 주요 대안: Leave reconnects unbound, persist a plain hash, bind from either header alone,
-  delete App turn metadata, or derive one process-local key from the complete pair.
-- 선택한 방식: Preserve the parent-thread key when present; otherwise HMAC the two bounded headers
-  under a random per-process key and carry that opaque value through selection, subagent preview,
-  and outcome handling.
-- 다른 대안 대신 이 방식을 선택한 이유: A complete pair avoids weak partial identities, a
-  process-local HMAC prevents durable correlation or dictionary recovery, and no upstream metadata
-  needs to be mutated before the first-403 cause is proven.
-- 장점, 단점 및 영향: Reconnects stop rotating among Pool accounts and failure accounting clears
-  the correct binding. Affinity intentionally resets on process restart, and requests missing either
-  component retain the prior unbound behavior.
+> Decision record: [ADR-0085](../decisions/ADR-0085-public-provider-contract.md)
 
 An explicit `Retry-After` or an unclassified quota 429 is account-wide. A reset-derived native-model
 429 is advisory and remains within its confirmed quota group: `gpt-5.3-codex-spark` is separate from
@@ -105,6 +92,24 @@ requests keep their captured credential. An all-paused pool fails closed.
 The dashboard's bulk pause action refreshes all account quotas and mutates only accounts whose
 plan-relevant window is freshly confirmed at exactly 100%; unknown and failed refreshes are skipped.
 
+A quota refusal that announces a reset carries two durations, not one. The hard cooldown governs
+blocking and keeps its cap, and a separate avoidance window records the period the refusal actually
+announced, bounded at six hours so a reset days out cannot take an account out of rotation for that
+long. Selection and affinity reuse both pass over an account while its window is live. The window
+binds the stable `__main__` alias on the same terms as an added account: the main login is not in
+the configured pool and enters candidacy through its own re-insertion path, which applies the same
+avoidance check the pool filters apply. Avoidance stays soft. Last-resort selection still reaches
+the account when nothing else can serve, a successful recovery probe drops the window with the
+cooldown it belonged to, and both operator escapes remove it: clearing a cooldown and naming an
+account each clear the window from the account-wide entry and from every scoped entry, because a
+reset-derived refusal records only the scoped one.
+
+Clearing a cooldown is also the management operation for a window whose cooldown has already
+lapsed. Because the cooldown is the shorter of the two durations, the state an operator usually
+finds is an expired cooldown and a live window, so a live window alone makes the operation
+succeed and report a clear. An account with neither reports no change, which is what keeps the
+route from disclosing whether an account exists.
+
 A confirmed manual reset-credit consumption may immediately reconcile that account's
 eligible pre-existing ordinary reset-derived cooldown after a complete, non-exhausted usage
 observation started after the reset. Paused or reauthentication-required accounts and
@@ -173,6 +178,27 @@ ordinary Luna or another account. Native vision/search helpers and standalone se
 under this compatibility opt-in; ordinary helper/default behavior is unchanged.
 Upstream remains the entitlement authority.
 
+### Quota cache and short-window history
+
+`src/codex/quota.ts` drops an omitted account-level short tuple from the display/rotation
+cache when its stored reset instant has elapsed. Seconds and milliseconds are accepted;
+future or missing deadlines remain carried, and explicit incoming short readings remain stored.
+This stops partial weekly/Spark or credits-only refreshes from renewing obsolete Spark-derived
+5h rows through the cache-wide `updatedAt` timestamp. Plan labels do not suppress real windows.
+
+The separately retained main-policy snapshot preserves omitted short evidence even after its
+reset clock passes. Credits-only, weekly-only, and metadata-only updates cannot remove an
+existing short usage reading or release its hard lock; a fresh short reading can replace it.
+
+The Codex writer explicitly asks `src/quota/reset-observer.ts` to retain an absent short window
+in `src/quota/reset-seen-store.ts`, with its original observation time. Detection compares only
+incoming windows, so eviction emits nothing and a later real rollover still has its baseline.
+Account cleanup forgets that baseline; other provider writers keep replacement semantics.
+Auto-refresh uses its separately retained reset boundary after display eviction.
+Regression coverage lives in `tests/codex-integration/codex-quota-parser-parity.test.ts`,
+`tests/codex-integration/main-account-hard-lock-policy.test.ts`,
+`tests/usage/quota-reset-observation.test.ts`, and `tests/usage/quota-reset-seen-store.test.ts`.
+
 `codexMainAccountHardLock` is a separate opt-in local admission policy, off by default.
 It blocks newly admitted identity-matched main-account requests at 99% of the 5h/short window
 when present, otherwise the weekly window (monthly for monthly-only accounts). It does not take
@@ -255,19 +281,7 @@ If the caller lacks the requested model, a stored-account model detour may serve
 clearing the healthy shared main pin. A paused or quota-drained main skips this exception and follows the
 ordinary Pool promotion path.
 
-[Decision Log]
-- 목적과 의도: Keep an explicit healthy main selection from being replaced by an exhausted stored
-  account merely because the client supplied main through a request-owned keyring bearer.
-- 기존 구현 및 제약 조건: Request-owned credentials are deliberately excluded from stored-account
-  entitlement discovery, but shared-state preservation interpreted that exclusion as a dead main login.
-- 검토한 주요 대안: Persist the caller credential, read the physical main token for identity, ignore
-  the manual pin, or validate the caller independently before stored-Pool selection.
-- 선택한 방식: Use only the effective pin, pause state, cached quota, and the caller credential's own
-  gated-model check; synthesize shared-state liveness only while main stays request-ineligible.
-- 다른 대안 대신 이 방식을 선택한 이유: It preserves credential isolation and explicit operator
-  intent without admitting an unentitled model or binding an ephemeral bearer into durable Pool state.
-- 장점, 단점 및 영향: Healthy main pins survive keyring requests and model-only detours; cached quota
-  remains the only proactive drain evidence available without crossing the physical credential boundary.
+> Decision record: [ADR-0086](../decisions/ADR-0086-public-provider-contract.md)
 
 ```text
 gpt-5.6-sol                         # openai; Pool or Direct follows the provider option
@@ -338,37 +352,9 @@ preserving a stale one would block every later migration.
   The optional `prompt_cache_retention` hint is removed on this route because Daybreak's
   authenticated catalog does not advertise it and upstream rejects it before execution.
 
-[Decision Log]
-- 목적과 의도: Preserve the account-gated Daybreak UX while avoiding shard-dependent selector
-  rejection and the unsupported prompt-cache retention parameter.
-- 기존 구현 및 제약 조건: The authenticated roster grants Daybreak, but live successful
-  responses report `gpt-5.6-sol`; the selector can still fail eight consecutive times.
-- 검토한 주요 대안: Increase retries indefinitely, hide Daybreak entirely, or canonicalize only
-  the credential-bearing wire model after entitlement selection.
-- 선택한 방식: Keep Daybreak for visibility and account authorization, then send the stable
-  serving id and remove only the unsupported optional retention hint.
-- 다른 대안 대신 이 방식을 선택한 이유: It keeps fail-closed entitlement checks and avoids
-  unbounded duplicate requests while preserving the user-facing model choice.
-- 장점, 단점 및 영향: Requests become deterministic and cheaper; this relies on the serving id
-  observed from successful upstream responses and must be revisited if the roster exposes a
-  first-class wire id later.
-
-[Decision Log]
-- 목적과 의도: Prevent account-gated native models from being shown or dispatched through a
-  ChatGPT account that upstream does not authorize.
-- 기존 구현 및 제약 조건: A static global Daybreak row solved clean-install discovery for
-  entitled accounts, but Pool accounts can hold different grants and Codex's injected catalog does
-  not refresh itself.
-- 검토한 주요 대안: Infer grants from plan labels, learn only from prompt failures, bind Daybreak
-  permanently to main, or rewrite the wire id to `gpt-5.6-sol`.
-- 선택한 방식: Share bounded authenticated per-account model-roster evidence between catalog sync,
-  `/v1/models`, and Pool auth selection.
-- 다른 대안 대신 이 방식을 선택한 이유: Plan labels and account position do not prove a grant;
-  failure-only learning wastes a turn; permanent main binding rejects valid secondary grants; wire
-  rewriting changes the requested product identity.
-- 장점, 단점 및 영향: Entitled accounts retain clean-install discovery while unentitled accounts
-  never receive the gated dispatch. A cold gated request may pay one bounded roster fetch per
-  account, and an unavailable discovery temporarily hides the model rather than guessing.
+> Decision record: [ADR-0087](../decisions/ADR-0087-model-and-wire-identity.md)
+
+> Decision record: [ADR-0088](../decisions/ADR-0088-model-and-wire-identity.md)
 - The two GPT-5.6 surfaces advertise different windows on purpose. API rows use 1,050,000
   context with 922,000 max input. Codex-login rows default to the live catalog 272,000
   (auto-compact 244,800) and only rise to 922,000 / 829,800 when the user turns the 1M
@@ -380,7 +366,7 @@ preserving a stale one would block every later migration.
   spending budget, not a label: Codex fills `context_window * effective_context_window_percent`
   (95% by default, codex-rs `turn_context.rs`). Advertising 1,050,000 there spent 997,500 and
   blew past the ceiling. The 922,000 opt-in yields a 875,900-token budget and keeps ~46k of
-  headroom. Evidence: `devlog/_plan/260817_native_gpt56_1m_context/001_measurement_evidence.md`
+  headroom. Evidence: `devlog/_fin/260817_native_gpt56_1m_context/001_measurement_evidence.md`
   and `014_final_922k_with_margin.md`.
 - `*-pro` selected ids rewrite to the base wire id with `reasoning.mode: "pro"`; request logs,
   usage, model visibility, subagent state, and injection state retain the selected virtual id.
@@ -397,15 +383,7 @@ use the same process-local tags, while unknown fields contribute only a count. O
 classified without hashing. The diagnostic is observational: it cannot strip headers, retry,
 switch accounts, reset threads, or mutate affinity.
 
-```text
-[Decision Log]
-- 목적과 의도: Identify which combined Codex affinity values survive a Plus-to-K12 credential substitution without collecting private thread or account data.
-- 기존 구현 및 제약 조건: Pool auth intentionally copies the curated caller metadata and replaces only authorization plus chatgpt-account-id. Individual header probes did not reproduce the workspace denial, while raw captures would expose account-bound identifiers.
-- 검토한 주요 대안: Delete all affinity metadata; log raw values; persist ordinary hashes; perform automatic header-ablation retries; or emit process-local keyed equality evidence only when provider debug is enabled.
-- 선택한 방식: Emit bounded pre-stream diagnostics with a random per-process HMAC key, a fixed non-credential header allowlist, known turn-field summaries, and no request mutation.
-- 다른 대안 대신 이 방식을 선택한 이유: Equality across two requests in one run is enough to narrow the incompatible combination; process-local HMACs prevent durable correlation and make offline guessing useless, while observation-only capture cannot change production semantics.
-- 장점, 단점 및 영향: Maintainers can compare a Plus success and exact-K12 denial safely. Tags cannot be compared across restarts, and the diagnostic does not itself identify an upstream policy rule or fix the rejection.
-```
+> Decision record: [ADR-0089](../decisions/ADR-0089-process-local-affinity-diagnostics.md)
 
 ## Account identity and store concurrency
 
@@ -438,3 +416,40 @@ model settings, and noncanonical `openai` rows never receive that recovery path.
 `GET /api/codex-auth/accounts?refresh=1` treats missing main credentials, HTTP 401, and allowlisted
 terminal 403 codes as `needsReauth`; generic permission failures remain non-terminal, and a
 successful main usage refresh clears the runtime mark.
+
+## Paginated history writer boundary
+
+`src/codex/history-provider.ts` refuses external writes to paginated or migration-capable history. `src/codex/inject.ts` checks affected rows and manifest-owned restore targets before artifact changes and compensates detected migration. Failed config restore stops later catalog/history work. See the [history writer contract](../codex-home.md#paginated-history-writer-boundary) for guarantees and concurrent-writer limits.
+
+## Context relay ownership
+
+`src/codex/context-owner.ts` records which account actually served a root session, taken from the
+final materialized outbound headers of an accepted model attempt, after refresh and failover.
+Entries are bounded, process-local and expiring, and are keyed by the admission principal that
+`src/server/auth-cors.ts` mints for the matched opencodex API key, plus the destination and the
+root session. Two keys therefore cannot observe or overwrite each other's ownership even when both
+resolve to one ChatGPT workspace, and rotating a key mints a new principal instead of inheriting
+the previous holder's sessions. `resolveContextPrincipal` resolves that principal from the opencodex API key the request
+presents, on both the recording and the relay path so the two agree. A remote bind supplies it
+through admission. A loopback bind admits without reading a token, so the key is resolved from the
+request only for a loopback admission; this adds identity where the caller volunteered it rather
+than admitting anyone new, and changes neither admission nor which credential goes upstream. The
+built-in loopback injection cannot carry that header, so the relay is unavailable through the
+default Codex integration and refuses instead of inferring an owner. Making loopback callers
+identifiable is an open maintainer decision, not a gap to be closed by relaxing the refusal.
+
+A workspace id identifies an organization, so an entry also binds the stable user claim carried by
+the accepted credential. That claim is read without signature verification, which is why upstream
+acceptance stays the evidence: a credential proving a different user does not continue the session,
+conflicting claims are never recorded, and an entry with no proven user continues only for the
+exact accepted credential. Conflicting observations stay ambiguous, and ambiguous, unknown,
+expired, evicted or restart-lost ownership fails closed before account selection or upstream I/O.
+
+`src/server/context-history.ts` relays the native history and notes endpoints under one deadline
+that starts on route entry, before the body is read and before credential selection, so an
+unfinished body cannot hold an admitted turn. Client cancellation and deadline expiry are reported
+separately, nothing is dispatched upstream after either, and notes writes are never retried.
+
+Context relay dispatch rechecks the native experimental opt-in after body and credential waits.
+A disabled gate prevents upstream dispatch even when the request entered while enabled. Final
+materialized headers pass the proxy-credential exclusion check before owner matching.
diff --git a/structure/providers/xai-grok.md b/structure/providers/xai-grok.md
new file mode 100644
index 0000000000..c6e7cd48f3
--- /dev/null
+++ b/structure/providers/xai-grok.md
@@ -0,0 +1,69 @@
+# xAI Grok Provider
+
+## xAI Grok hardening (official Grok Build contract parity)
+
+Grounded in the open-sourced official client (xai-org/grok-build); unit + evidence:
+`devlog/_fin/260716_grok_build_hardening/`.
+
+- **Reasoning folding:** the Responses parser folds `reasoning` items into the FOLLOWING
+  assistant turn (`pendingReasoning` in `src/responses/parser.ts`) so the Grok chat wire carries
+  ONE assistant message with `reasoning_content` — exact-prefix cache stability. Unsigned
+  siblings newline-join; `ocxr1`-signed siblings stay separate parts (Anthropic replay keeps
+  each signature on its own text); boundaries (user/tool-result/agent) clear pending state;
+  call items fold pending reasoning into the same turn.
+- **Grok CLI credential ownership:** `source:"local-cli"` xAI credentials re-read
+  `~/.grok/auth.json` (read-only) before any refresh and adopt a newer usable generation with
+  zero IdP calls (`shouldAdoptGrokGeneration`, later-expiresAt authority); an IdP refresh
+  detaches the credential to `source:"oauth"`.
+- **Browser login callback:** Grok's browser login uses the shared `OAuthCallbackFlow` listener
+  on a per-provider FIXED loopback port, so every response it sends closes its connection. A
+  retired flow that kept a pooled socket would capture the NEXT login's callback and reject it
+  as a state mismatch; see `src/oauth/callback-server.ts`.
+- **Two-lock refresh transaction:** per-provider+account intent lock held across the IdP
+  exchange plus a short global store-write lock + async mutation funnel around every
+  `auth.json` load-merge-persist (`src/oauth/store.ts`); generation-guarded persist
+  (`expectedGeneration` → superseded adoption), conditional `needsReauth`, bounded jittered
+  retry for transient token-endpoint failures.
+- **Reactive 401 replay:** both the adapter recovery loop and native Responses passthrough branch
+  force-refresh once (singleflight, generation-checked) and replay OAuth-backed xAI requests
+  exactly once with a re-resolved transport; API-key/BYOK paths are excluded
+  (`src/server/responses/core.ts`).
+- **Header parity:** per-attempt `x-grok-req-id` (fresh UUID inside the transport fetch
+  wrapper), stable session/conv affinity headers, always-set User-Agent, and a single
+  compatibility profile const for the Grok client version (`src/providers/xai-transport.ts`);
+  `fetchWithHeaderTimeout` takes an executor so provider fetch wrappers stay inside the
+  timeout race.
+
+The generated Grok client marker also enables a client-facing sparse-terminal repair for native
+Responses streams. Grok Build renders text deltas immediately but derives its durable assistant
+turn from `response.completed.response.output`; an OpenAI-compatible stream may instead place the
+complete items in `response.output_item.done` and finish with an explicit empty output array. For
+that marked client only, OpenCodex uses a terminal-only tracker: it retains bounded, contiguous,
+unique and semantically valid raw completed items, then backfills a missing or empty terminal
+snapshot. It never promotes locally synthesized or merely repaired items. Unmarked callers continue
+to treat an explicit empty array as authoritative. Within this marked client-facing repair,
+malformed, gapped, oversized, contradictory, failed, or incomplete streams stay fail-closed.
+
+> Decision record: [ADR-0059](../decisions/ADR-0059-xai-grok-hardening-official-grok-build-contract.md)
+
+### Grok Reset Coupons (Billing API Parity)
+
+- **Upstream RPCs:** `prod_mc_billing.ConsumerUiSvc/GetRemainingResets` (inspection) and `prod_mc_billing.ConsumerUiSvc/RedeemReset` (redemption).
+- **Transport:** Binary gRPC-Web over HTTP/1.1 or HTTP/2 with 5-byte frame envelope (`0x00` data / `0x80` trailers) and protobuf wire format. Plain JSON is rejected with empty responses upstream.
+- **Authentication:** `Authorization: Bearer <xai OIDC access token>` + `X-XAI-Token-Auth: xai-grok-cli`. No cookies required.
+- **Safety & Idempotency:** Managed via `src/grok/reset-coupon-ledger.ts` using UUIDv4 operation tracking before upstream dispatch to prevent duplicate consumption during network flakes.
+- **Surfaces:** `ocx account grok-reset-coupons` in the terminal, and the dashboard at Providers > xAI Grok > Accounts, where each OAuth row carries a ticket badge with its remaining count and opens a redemption dialog (`gui/src/hooks/useGrokResetCoupons.ts`, `gui/src/components/provider-workspace/GrokResetCoupons.tsx`). The dashboard reads one `GET /api/grok/reset-coupons` per account with at most three in flight, always sends an explicit `tokenId` and a client-minted `operationId`, and treats redemption truth as the settled `code` rather than HTTP 200 — a replayed *failure* returns 200 with `replayed: true`. After a request times out it issues no further consume call, because a redemption whose ledger record is still `open` re-executes.
+
+Chat helper admission in `src/server/responses/core.ts` follows the
+[deferred stored-main contract](openai-tiers.md): only a needed Direct OpenAI helper
+claims stored main, after terminal vision, routed vision and search exclusions.
+
+Account-scoped OAuth quota remains display evidence for provider-level Combo selection; it does not acquire single-key inference-veto authority. See [scoped provider quota](../runtime.md#scoped-provider-quota-for-combo-selection).
+
+The management quota DTO keeps Combo editing aligned with scoped inference evidence;
+see [Combo editor routing quota](../gui-and-management-api.md#combo-editor-routing-quota).
+
+Claude replay carries [Go conversation affinity](../data-planes/inbound-compat.md#claude-affinity-at-final-go-dispatch)
+privately to final dispatch; preliminary route selection does not inject Go-only headers.
+
+Devin CLI credential path composition in `src/oauth/devin-cli.ts` follows the selected platform: Windows uses Win32 APPDATA paths, other platforms use POSIX XDG-data paths. The explicit absolute override remains verbatim; credential parsing and login behavior are unchanged.
diff --git a/structure/remote-workspace.md b/structure/remote-workspace.md
new file mode 100644
index 0000000000..534c649471
--- /dev/null
+++ b/structure/remote-workspace.md
@@ -0,0 +1,11 @@
+# Remote Workspace protocol
+
+`src/remote-control/` is an inactive protocol library. Importing it registers no HTTP route, opens no connection and starts no process or timer. Existing Remote Hub provider routing remains in `src/remote/` and is a separate capability.
+
+`src/remote-control/protocol.ts` owns versioned frame, identity and capability contracts. `src/remote-control/crypto.ts` uses Ed25519 signatures, P-256 ephemeral agreement and directional AES-GCM counters. `src/remote-control/workspace-agent-protocol.ts` bounds and parses control envelopes. `src/remote-control/workspace-tools.ts` describes the remote tool namespace and capability mapping.
+
+`src/remote-control/workspace-rpc-framing.ts` fragments logical messages and bounds reassembly size, count and expiry. Expiry timers exist only after explicit incomplete-fragment acceptance. `src/remote-control/workspace-utf8.ts` bounds text without splitting surrogate pairs.
+
+`src/remote-control/host.ts` accepts an explicitly supplied terminal factory. Authenticated application traffic can invoke that factory; no production factory is supplied here. `src/remote-control/relay.ts` forwards opaque envelopes after its caller authorizes the peer. Neither adapter is wired into server startup.
+
+The public exports in `src/remote-control/index.ts` expose only this foundation. Device enrollment, executor operations and UI activation are not part of this layer. Tests in `tests/clients/remote-control-prototype.test.ts`, `tests/clients/remote-workspace-rpc-framing.test.ts` and `tests/clients/remote-workspace-protocol.test.ts` cover the protocol contracts; they do not prove platform command confinement.
diff --git a/structure/01_runtime.md b/structure/runtime.md
similarity index 78%
rename from structure/01_runtime.md
rename to structure/runtime.md
index 36c9a282be..365fb04e07 100644
--- a/structure/01_runtime.md
+++ b/structure/runtime.md
@@ -1,4 +1,4 @@
-# Runtime SOT
+# Runtime
 
 ## Entrypoints
 
@@ -76,13 +76,7 @@ sockets before lifecycle release. The existing launchd/systemd installer remains
 and continues loading the data token from `service-api-token`; hub mode adds no service-manager
 fork and no token-bearing unit/plist field.
 
-[Decision Log]
-- 목적과 의도: Give a headless hub a browser management ingress without widening its data plane or trusting spoofable forwarding headers on the public listener.
-- 기존 구현 및 제약 조건: `startServer` is synchronous through Lab activation, already owns an optional-listener transaction, and the service installer already has an owner-only token-file flow.
-- 검토한 주요 대안: Add management routes to the public listener; infer trusted ingress from `Host`/`Forwarded`/Tailscale headers; create a separate service manager; extend the existing composition root.
-- 선택한 방식: Bind a third socket exactly to `127.0.0.1`, select trust by receiving `Bun.serve` instance, keep a fixed route allowlist, and reuse the current launchd/systemd definitions.
-- 다른 대안 대신 이 방식을 선택한 이유: Headers do not prove which transport received a request, while a kernel loopback bind plus Tailscale Serve supplies a concrete ingress boundary without duplicating lifecycle or secret delivery.
-- 장점, 단점 및 영향: Public/default behavior stays unchanged and management can use Tailscale identity; operators must provide a co-located HTTPS frontend and pairing remains necessary for generic TLS proxies.
+> Decision record: [ADR-0002](decisions/ADR-0002-lifecycle.md)
 
 The process-state boundary deliberately exposes two PID checks. `readAlivePid()` is the cheap
 non-destructive probe used by liveness polling. `readPid()` and `verifyPidIdentity()` include the
@@ -97,13 +91,13 @@ scans may proceed if verification succeeds or the holder exits. The allowlist na
 eligibility and supplies no identity evidence by itself. This contract uses the existing verifier;
 it does not add process-instance proof or change the classification cache.
 
-[Decision Log]
-- 목적과 의도: Separate proxy process ownership from persisted configuration without changing lifecycle behavior.
-- 기존 구현 및 제약 조건: `src/config.ts` mixed config transactions with cross-platform PID identity, runtime-port attestation, and stale-state cleanup; process writes still require the same config-home and atomic-write protections.
-- 검토한 주요 대안: Keep the mixed module; create a process-state module that imports `config.ts`; duplicate atomic writes inside the new module; split the minimal path and atomic-write foundations first.
-- 선택한 방식: `paths.ts` and `atomic-write.ts` are dependency leaves, `process-state.ts` depends only on those leaves, and `config.ts` remains a compatibility facade.
-- 다른 대안 대신 이 방식을 선택한 이유: Importing the facade would create a cycle, while duplicated writes could drift on ACL, symlink, residual-secret, and atomic-sequence behavior.
-- 장점, 단점 및 영향: Lifecycle callers have a narrow owner and behavior remains characterized; the temporary facade and three small config modules add files but preserve downstream imports.
+Pinned post-update retries in `src/update/job.ts` retire a child after an observed exit, signal, spawn error, or close event.
+Both retry and final-timeout cleanup check the retained child object; a late exit from an older
+child cannot clear its replacement. Retirement removes only its own event listeners and preserves
+separate logging. A healthy child remains running. This does not provide an
+atomic OS guarantee against unobserved PID reuse.
+
+> Decision record: [ADR-0003](decisions/ADR-0003-lifecycle.md)
 
 An installed Codex shim is checked on ordinary CLI startup with a regular-file/1 MiB state bound plus
 bounded metadata and prefix reads. A complete replacement must produce identical fingerprints and
@@ -143,13 +137,7 @@ the client never sees a completed call ahead of `response.failed` / `response.in
 The server exposes `POST /api/stop` which restores native Codex config, stops any installed service
 (to prevent respawn), and exits the process. The GUI sidebar stop button calls this endpoint.
 
-[Decision Log]
-- 목적과 의도: Prevent repository dotenv data from becoming a durable executable or an OAuth-bearing Claude destination.
-- 기존 구현 및 제약 조건: Bun auto-loads project dotenv before OpenCodex TypeScript evaluates, while provider interpolation still depends on that behavior and cannot be disabled globally.
-- 검토한 주요 대안: Reject only relative Bun paths; disable Bun dotenv; trust a plain environment marker; capture provenance in the Node launcher and bind it to an argv proof.
-- 선택한 방식: The Node launcher selects Bun and snapshots Anthropic credential/destination slots before Bun starts. Durable runtime selection uses only the stamped current executable, while Claude accepts the snapshot only when its random argv proof matches.
-- 다른 대안 대신 이 방식을 선택한 이유: Absolute dotenv expansion bypasses a relative-path check, global dotenv removal breaks supported configuration, and an environment-only marker can itself come from dotenv.
-- 장점, 단점 및 영향: Normal npm launches preserve genuine shell overrides. Direct Bun or legacy launches have no provenance signal and fail closed for all three ambient Anthropic slots — credentials included, because subscription mode leaves `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` unset by design (#253) and a `settings.env` merge can still replace the destination after launch, so a preserved key would travel with it. The cost is that `bun src/cli/index.ts` loses ambient Anthropic values; the escape hatch is running through the published `ocx` bin, where genuine shell exports are preserved by proof. Durable artifacts use the running or bundled Bun.
+> Decision record: [ADR-0004](decisions/ADR-0004-lifecycle.md)
 
 ## Providers and adapters
 
@@ -157,7 +145,7 @@ The server exposes `POST /api/stop` which restores native Codex config, stops an
 | --- | --- |
 | `src/providers/registry.ts` | Canonical provider presets for CLI, dashboard, OAuth, key providers, and metadata. |
 | `src/providers/derive.ts` | Enrichment from provider presets into user config. |
-| `src/oauth/` | OAuth providers, token storage, refresh, and auth-token resolution. |
+| `src/oauth/` | OAuth providers, token storage, refresh, and auth-token resolution. The login callback listener binds a per-provider FIXED loopback port, so consecutive logins reuse the same number; every response it sends ends its connection (`Connection: close`, including non-callback paths such as a stray `/favicon.ico` 404). Stopping the listener does not close an established socket, so without that a pooled client would deliver the next login's callback to the retired flow, which rejects the unknown state as a CSRF mismatch while the live flow waits. |
 | `src/adapters/openai-responses.ts` | Native OpenAI/ChatGPT Responses passthrough. |
 | `src/adapters/openai-chat.ts` | OpenAI-compatible Chat Completions bridge. |
 | `src/adapters/anthropic.ts` | Anthropic Messages bridge. |
@@ -200,6 +188,50 @@ an unowned client remains disconnected. OpenCodex omits Raycast API-key fields
 and exports only to eligible local targets. Pro detection is an advisory hint,
 not an authentication or entitlement decision.
 
+Routed Responses continuations whose local replay state is missing resolve their recovery decision from the selected wire protocol, not the model name; the contract lives in [Responses transport](transports/responses.md).
+
 ## Remote Hub hardening ownership
 
 `src/remote/protocol.ts` owns pure interval/feature negotiation. `src/remote/hub-state.ts` owns the `GET|HEAD /v1/hub-state` contract, its caps, and the parser both sides share. `src/client/hub-client.ts` owns bounded, schema-validated remote catalog consumption, hub-state reads, and key-id probes; `src/client/hub-state.ts` owns the resolution and the owner-stamped 0600 cache, and a failed read reports "unavailable" rather than degrading to the client's own local provider and login state. `src/client/hub-relay.ts` is a fixed-authority management relay with URL, header, body, redirect, and stream bounds. The public data listener remains the direct client→hub path; the loopback management ingress never serves data-plane routes.
+
+Codex display-cache expiry, retained main-policy evidence, and reset history follow the
+[quota cache contract](providers/openai-tiers.md#quota-cache-and-short-window-history).
+
+Chat helper admission in `src/server/responses/core.ts` follows the
+[deferred stored-main contract](providers/openai-tiers.md): only a needed Direct OpenAI helper
+claims stored main, after terminal vision, routed vision and search exclusions.
+
+## Scoped provider quota for Combo selection
+
+`src/providers/quota.ts` publishes routing evidence only when a producer explicitly supplies its
+inference-wide projection. A matching credential alone does not grant veto authority. Display-only
+account, model-group, search and legacy MCP windows remain visible but cannot exclude a provider.
+The private WeakMap binds provider name, adapter, destination and captured credential; neither
+credential nor binding enters report JSON.
+
+`src/providers/quota-routing-cache.ts` rechecks the live single key, effective authentication,
+static credential headers and key-pool size. Unknown, invalid, future or 30-minute-old evidence
+cannot rank or veto a provider. `src/combos/resolve.ts` uses that same scoped getter for selection,
+reset-window ordering and catalog inactivity. Changing a key, destination or adapter invalidates
+the old binding; restoring the same configuration may reuse still-fresh evidence. Account admission,
+cooldowns and response-driven retry remain authoritative.
+
+The management quota DTO keeps Combo editing aligned with scoped inference evidence;
+see [Combo editor routing quota](gui-and-management-api.md#combo-editor-routing-quota).
+
+## Paginated history writer boundary
+
+`src/codex/history-provider.ts` refuses external writes to paginated or migration-capable history. `src/codex/inject.ts` checks affected rows and manifest-owned restore targets before artifact changes and compensates detected migration. Failed config restore stops later catalog/history work. See the [history writer contract](codex-home.md#paginated-history-writer-boundary) for guarantees and concurrent-writer limits.
+
+Claude replay carries [Go conversation affinity](data-planes/inbound-compat.md#claude-affinity-at-final-go-dispatch)
+privately to final dispatch; preliminary route selection does not inject Go-only headers.
+
+Cline CLI joins the existing export/client integration registries. Explicit CLI sync and POST /api/sync refresh its owned pair; unattended catalog refresh excludes it. See [Cline paired files](clients/integrations.md#cline-paired-files).
+
+`claudeCode.stabilizePromptCache` is a default-off operator setting for
+[translated instruction stabilization](data-planes/inbound-compat.md#opt-in-claude-instruction-stabilization).
+Config JSON preserves the boolean; only literal true activates the role-changing transform.
+
+The lightweight top-level CLI help counts Cline CLI among the fifteen registered export clients; registry parity remains covered by the client help and integration tests.
+
+Devin CLI credential path composition in `src/oauth/devin-cli.ts` follows the selected platform: Windows uses Win32 APPDATA paths, other platforms use POSIX XDG-data paths. The explicit absolute override remains verbatim; credential parsing and login behavior are unchanged.
diff --git a/structure/subagents.md b/structure/subagents.md
new file mode 100644
index 0000000000..f190aab084
--- /dev/null
+++ b/structure/subagents.md
@@ -0,0 +1,216 @@
+# Subagents And Multi-Agent Surface
+
+## Multi-agent surface mode (3-state)
+
+`OcxConfig.multiAgentMode` controls the `multi_agent_version` field stamped on catalog entries:
+
+| Mode | Behavior |
+| --- | --- |
+| `"v1"` | Force ALL entries to `multi_agent_version = "v1"` — overrides upstream pins (sol/terra included). |
+| `"default"` (install default) | Respect upstream model pins (sol/terra=v2, luna=v1, others=null → codex feature flag decides). On sync, stale forced values are cleared and upstream pins restored. |
+| `"v2"` | Force ALL entries to `multi_agent_version = "v2"` — overrides upstream pins (luna included). |
+
+The override is applied as a final pass in both `buildCatalogEntries` (live `/v1/models` path) and
+`mergeCatalogEntriesForSync` (on-disk sync), AFTER all normalization and visibility processing. This
+ensures `normalizeRoutedCatalogEntry` (which deletes `multi_agent_version` from routed entries) does
+not clobber the forced value.
+
+CLI: `ocx v2 mode v1|default|v2`. GUI: segmented control on the Models page. API: `GET/PUT /api/v2`
+with `multiAgentMode` field.
+
+The `multi_agent_v2` feature flag and the logical maximum thread count are separate from
+`multiAgentMode` (`src/codex/features.ts`): the mode decides which surface Codex advertises, while
+the flag and thread count decide what the native runtime allows.
+
+`keepNativeChatGptOnV1` makes mode `v2` a catalog-driven hybrid: OpenCodex disables the global
+`multi_agent_v2` override because codex-rs resolves that override before a model row's explicit
+`multi_agent_version`. Native ChatGPT rows then select v1 from the catalog and routed rows select
+v2. An explicit attempt to enable the global flag while the hybrid pin is active is rejected.
+
+### What the five-model `spawn_agent` window is, and how V1 differs from V2
+
+`MAX_SPAWN_AGENT_MODEL_OVERRIDES = 5` (mirrored in `src/codex/catalog/sync.ts`) is **not** a
+subagent concurrency limit and **not** an eligibility limit. Upstream uses it in exactly two
+places: the model list rendered into the `spawn_agent` tool description
+(`multi_agents_spec.rs:789`) and the "Available models:" suggestions in an unknown-model error
+(`multi_agents_common.rs:448`, inside the `ok_or_else` closure that runs only *after* the lookup
+already failed). The success path `find_spawn_agent_model_name` (`:431-442`) scans the whole
+catalog with neither the cap nor a `show_in_picker` filter, so a model outside the advertised
+five is still accepted when named exactly.
+
+Three different numbers, often conflated:
+
+| Quantity | Value | Source |
+| --- | --- | --- |
+| Models **advertised** as overrides | `min(5, picker-visible eligible rows)` | `multi_agents_spec.rs:785-790` |
+| Models **eligible** as targets | no numeric cap (only `"disabled"` is excluded, and only on V2) | `multi_agents_common.rs:36-42` |
+| **Concurrent** subagents | V1 6 children (root excluded); V2 total 4 including root → 3 children | `config/mod.rs:211-212`, `:1497-1506` |
+
+**The cap is the same 5 on both surfaces, but the window's contents are not.** The eligibility
+filter runs *before* `.take(5)`, and it behaves differently per surface: on a V1 call
+`model_supports_multi_agent_backend` short-circuits true for every row (including `disabled`
+ones), while a V2 call drops `Some(Disabled)` first — which lets a later row move into the five.
+Same catalog, different advertised list:
+
+| # | Model | pin | V1 advertises | V2 advertises |
+| ---: | --- | --- | :---: | :---: |
+| 1 | `v2-a` | `v2` | ✅ | ✅ |
+| 2 | `disabled-a` | `disabled` | ✅ | — |
+| 3 | `v1-a` | `v1` | ✅ | ✅ |
+| 4 | `null-a` | absent | ✅ | ✅ |
+| 5 | `v2-b` | `v2` | ✅ | ✅ |
+| 6 | `disabled-b` | `disabled` | — | — |
+| 7 | `null-b` | absent | — | ✅ |
+
+opencodex already matches this: `effectiveSubagentRoster` filters with
+`surface !== "v2" || isEligibleV2SubagentEntry(entry)`, so the V1 path skips the eligibility
+filter exactly as upstream does. opencodex also injects no roster on V1
+(`src/server/responses/collaboration.ts` emits only proactive text at the top effort tier), so
+the upstream tool description remains the authority there.
+
+Two further V1/V2 differences worth knowing: the list gate is
+`hide_agent_type_model_reasoning` on V1 (hard-coded `false` at registration, so V1 always
+advertises) but `expose_spawn_agent_model_overrides` on V2 (default `true`; when false the list
+is omitted *and* the `model`/`reasoning_effort` schema fields are removed). And V2's
+`hide_spawn_agent_metadata` defaults true, which removes `service_tier`.
+
+`modelPickerOrder` (#1649) separates **OpenCodex guidance** from native advertisement.
+`SPAWN_PRIORITY_FIELD` preserves the natural priority used by `effectiveSubagentRoster`, so
+OpenCodex's preferred/guidance candidate calculation stays independent of display order.
+Native Codex ignores that private field: its advertised five on V1 and exposed V2 follow the
+native `priority` and may change when the picker is reordered. Exact-name override lookup is
+not restricted to those five advertised rows. V1 receives no OpenCodex preferred-roster
+injection; V2 can additionally receive natural-priority guidance when its catalog state permits.
+The helper tests pin guidance behavior, not native tool-description equivalence.
+
+A nonblank bare id in `modelPickerOrder` opts into complete-picker display ordering. Exact
+ids take precedence over raw/encoded equivalents; routed-only and empty lists keep the legacy
+ordering behavior. This does not change the separate `opencodex_spawn_priority` contract.
+Retained rows recompute their natural ranks from the current featured roster and account-selector
+stride before display order is applied, so a discovery outage cannot preserve an obsolete
+featured or picker rank. Canonical `opencode-go` rows retain their configured reasoning ladder
+both when generated and when merged from retained catalog state; synthetic max/ultra choices
+are not added to that provider's declared ladder.
+
+Full derivation with per-line citations: `devlog/_plan/260816_codexrs_multiagent_v2_and_history_perf/013_five_cap_v1_vs_v2.md`.
+
+## Subagents
+
+New non-OAuth provider registrations carry `initialModelSelection` with a unique
+registration identity. Until reliable live/static discovery completes, public
+catalogs and model candidates withhold those providers' models; the provider itself
+stays active. At 20 or more canonical Models switch rows, initialization appends
+all corresponding disabled selectors once. Existing registrations and later manual
+choices are not reinitialized. OAuth/ChatGPT forwarding is exempt using the same
+usable-key override predicate as routing. Display aliases do not add switch rows.
+
+`src/providers/initial-model-selection-runtime.ts` commits the decision against a
+matching registration/inventory snapshot before catalog authority is captured.
+Ordinary management discovery also completes it with Codex integration OFF. The
+final catalog merge fences pending retained rows, including delete/re-add recovery.
+Raw management rows remain visible as pending/OFF. Config listener bindings are
+excluded from inventory identity because live and persisted bindings may differ.
+
+Codex `spawn_agent` advertises only the highest-priority first five picker-visible catalog rows.
+Use at most five configured `subagentModels` ids; they may contain bare catalog ids, routed
+`provider/model` ids, or exact account-qualified `<selector>/<native-openai-model>` ids. The
+dashboard offers bare native and routed choices; exact account-qualified choices are configured
+through `ocx agent subagents set` or the opencodex configuration.
+
+When account selectors are active, one featured bare native id expands into a complete selector row
+group. Catalog priorities use the selector count as a stride so each group stays together without
+widening Codex's five-row advertisement window. Fresh defaults are Astra, Sol, Terra, Luna, 5.5.
+Startup upgrades unmarked rosters once: prepend `gpt-6-astra`, retain the first four unique
+non-Astra choices, then move retained bare `gpt-5.5` last. The old fifth choice is dropped;
+an unmarked empty list becomes Astra only, and an unset list receives the fresh defaults.
+`subagentModelsVersion: 1` records completion, so later user edits (including an empty list or
+removing Astra) persist. The migration rebases on the latest disk config under the existing
+mutation lock; failed persistence degrades to an in-memory roster for that run without a stale
+whole-config overwrite. Existing disabled-model visibility rules remain unchanged.
+
+Quota-aware fallback walks a configured chain when the featured model is exhausted, probing
+availability on a bounded interval (default 60 s, `src/codex/subagent-model-fallback.ts`). It rewrites
+the requested model id only; effort remains owned by the caps described under
+[Ultra reasoning level](catalog.md#ultra-reasoning-level).
+
+`injectionModel` and `injectionEffort` are shared selections with two independent consumers.
+`multiAgentGuidanceEnabled` controls only OpenCodex-authored delegation guidance.
+`syncCodexSubagentDefaults` is a separate, default-off opt-in that applies the selected values to
+Codex's native `[agents]` defaults on sync/restart for newly created Codex tasks when OpenCodex owns
+the active Codex routing; external user-managed provider configs remain untouched. It does not itself
+cause delegation. The TOML edit owns only marker-tagged values, preserves existing unmarked
+user-owned `[agents]` defaults rather than overwriting them, and rejects ambiguous table shapes
+without changing the file.
+
+V2 proxy guidance uses `<opencodex_subagent_guidance>` for both built-in metadata and
+custom `injectionPrompt` bodies. The built-in text reports the resolved preferred model,
+effort, roster and fallback chain without prescribing delegation, spawn overrides or
+`fork_turns`. Custom bodies retain their placeholder behavior. The guidance switch and
+catalog-state gates still apply; stale or unknown catalog state suppresses proxy guidance.
+V1 uses the shared `MULTI_AGENT_MODE_HINT_RECOMMENDATION.text` inside `<multi_agent_mode>`
+at `max` or `ultra`. Only the separate explicit delegation-request trigger changes; user,
+authority, task-scope and collaboration-tool rules remain applicable. This is guidance,
+not an enforcement mechanism or a change to native settings or tool access.
+
+Replay deduplication compares the latest exact generated developer text separately for
+each tag family, preserving built-in → custom → built-in transitions without duplicating
+unchanged proxy metadata after a native policy change. Native and legacy-tagged history
+remain intact: tags do not establish historical authorship or revoke old instructions,
+and mixed-version transition detection is not guaranteed.
+
+The native mode hint is separate from proxy guidance and native `[agents]` defaults.
+`src/codex/multi-agent-mode-policy.ts` owns the proactive recommendation; the dashboard
+obtains it from `/api/v2` rather than maintaining its own preset. An explicit dashboard,
+API or CLI hint write passes through `setMultiAgentModeHintText`, which replaces only
+the two byte-exact released OpenCodex presets with the current recommendation. Other
+valid custom text, including whitespace variants, is preserved. Reads, unrelated writes
+and upgrades do not migrate stored hints. The writer retains its native capability check
+and stores only `features.multi_agent_v2.multi_agent_mode_hint_text` in Codex TOML;
+`null` removes that key. The hint affects new native Codex sessions when their v2 surface
+is active, without changing reasoning effort or the proxy guidance switch.
+
+Claude Code `ocx-*` agent definitions consume the same effective `claudeCode.blockedSkills` policy
+as inbound bundle elision. When the list is non-empty (default: `claude-api`), generated definitions
+whose marker-stripped model resolves to a routed id receive a preventive instruction not to invoke
+those skills. Direct `provider/model` selectors are routed even when their inbound resolution is
+identity. The only unguarded `ocx-self` case is an identity-resolved `claude|anthropic` model while
+native passthrough is enabled; `modelMap` claims and `nativePassthrough:false` restore the guard. The
+guard avoids creating oversized skill messages before the proxy can intervene; inbound elision remains
+the fallback if a client still sends a blocked bundle. An explicit empty list disables both routed-model
+behaviors.
+
+> Decision record: [ADR-0027](decisions/ADR-0027-subagents.md)
+
+
+### Saved picker presets
+
+The Models page saves routed snapshots in `modelPickerOrder` and records their origin in
+`modelPickerOrderMode` (`alphabetical`, `provider`, `most-used`). Mode is UI provenance, not a
+catalog sorting policy: catalog writers consume the saved array. Routed-only featured/native
+bands and complete-picker natural-rank preservation remain as described above. Public
+`buildCatalogEntries` accepts the order as its final argument and applies the complete-order
+pass after building. On-disk convergence retains its existing post-merge final pass.
+
+Claude ModelInfo ordering receives optional `{ modelPickerOrder, featured }` after `fastRows`.
+It orders routed output groups after alias deduplication, preserving the collision winner and
+base/1M/Fast siblings. Native groups and explicit Desktop profile ownership are unchanged.
+Native Codex advertisements still follow display priority; private guidance ranks do not freeze them.
+
+Codex display-cache expiry, retained main-policy evidence, and reset history follow the
+[quota cache contract](providers/openai-tiers.md#quota-cache-and-short-window-history).
+
+Chat helper admission in `src/server/responses/core.ts` follows the
+[deferred stored-main contract](providers/openai-tiers.md): only a needed Direct OpenAI helper
+claims stored main, after terminal vision, routed vision and search exclusions.
+
+Provider-level Combo eligibility uses explicit inference evidence for the current single credential; account-specific admission remains separate. See [scoped provider quota](runtime.md#scoped-provider-quota-for-combo-selection).
+
+The management quota DTO keeps Combo editing aligned with scoped inference evidence;
+see [Combo editor routing quota](gui-and-management-api.md#combo-editor-routing-quota).
+
+## Paginated history writer boundary
+
+`src/codex/history-provider.ts` refuses external writes to paginated or migration-capable history. `src/codex/inject.ts` checks affected rows and manifest-owned restore targets before artifact changes and compensates detected migration. Failed config restore stops later catalog/history work. See the [history writer contract](codex-home.md#paginated-history-writer-boundary) for guarantees and concurrent-writer limits.
+
+Claude replay carries [Go conversation affinity](data-planes/inbound-compat.md#claude-affinity-at-final-go-dispatch)
+privately to final dispatch; preliminary route selection does not inject Go-only headers.
diff --git a/structure/transports/inventory.md b/structure/transports/inventory.md
new file mode 100644
index 0000000000..88a26d3500
--- /dev/null
+++ b/structure/transports/inventory.md
@@ -0,0 +1,74 @@
+# Transport Inventory
+
+## Transport inventory
+
+The sections above cover the transports with load-bearing invariants. The rest of the transport
+surface is listed here so a maintainer can find the owner without grepping:
+
+| Transport | Owner | Invariant worth knowing |
+| --- | --- | --- |
+| Azure OpenAI Responses | `src/adapters/azure.ts` | Deployment-shaped URLs on top of the Responses contract. |
+| Google / Vertex / Antigravity | `src/adapters/google.ts`, `src/adapters/google-http.ts`, `src/adapters/google-wire-compiler.ts`, `src/adapters/google-tool-schema.ts`, `src/adapters/google-truncation.ts`, `src/adapters/google-errors.ts`, `src/adapters/google-antigravity-wire.ts`, `src/adapters/google-antigravity-replay.ts` | Vertex and Antigravity install a Google-family `fetchResponse` and so own their retry policy, while AI Studio Gemini leaves it undefined and uses the default server fetch path. The Google-family wrapper reuses the shared abort/deadline helpers (`src/lib/upstream-retry.ts`), wire-body repair, and upstream error normalization. |
+| Mimo Free | `src/adapters/mimo-free.ts` | Client identity and JWT handling are transport-local; the per-install client id lives in the opencodex state root. |
+| Anthropic image ingress | `src/adapters/anthropic-image-guard.ts`, `src/adapters/anthropic-image-normalize.ts` | Oversized or unsupported images are normalized or rejected before reaching upstream. |
+| Adapter execution support | `src/adapters/run-turn-queue.ts`, `src/adapters/tool-catalog-nudge.ts`, `src/adapters/identity.ts`, `src/adapters/image.ts`, `src/adapters/upstream-http-error.ts` | Shared machinery: turn ordering, tool-catalog nudging, client fingerprinting, image conversion, upstream error normalization. |
+| Cursor (beyond the sections above) | `src/adapters/cursor/live-transport.ts`, `src/adapters/cursor/http1-bidi.ts`, `src/adapters/cursor/live-models.ts`, `src/adapters/cursor/transport-retry.ts`, `src/adapters/cursor/mcp-manager.ts`, `src/adapters/cursor/thread-continuity.ts`, `src/adapters/cursor/checkpoint-store.ts` | Thread continuity is the point: a retry must not start a new Cursor thread, and a validated checkpoint must not rebuild the full root history. HTTP/2 remains the default; an explicit `http1.1`/`h1` pin maps the bidi run onto Cursor's `RunSSE` receive stream plus sequenced `BidiAppend` sends, and applies to live discovery too. |
+| Claude Messages | `src/server/claude-messages.ts` | Routed translation, a native Anthropic passthrough branch, and `count_tokens`. |
+| Chat Completions inbound | `src/server/chat-completions.ts`, `src/chat/` | Inbound translation onto the same routing pipeline. The content mapper preserves image URLs and supported detail, including screenshot-bearing tool results; target adapters own image placement on their wire. Image-free tool results stay strings. |
+| Hosted search relay | `src/server/search.ts` | Direct relay; distinct from the web-search sidecar loop below. |
+| Image/video generation loop | `src/images/loop.ts`, `src/images/plan.ts`, `src/images/fulfill.ts`, `src/images/xai-client.ts`, `src/images/xai-video-client.ts`, `src/images/artifacts.ts` | A provider-returned image URL is downloaded into a local artifact once, then served locally; warnings stay URL-free because provider CDN URLs may embed credentials. |
+| GitHub Copilot | `src/providers/xai-transport.ts` (`resolveProviderTransport`), `src/providers/github-copilot-transport.ts` | `resolveProviderTransport` selects the Copilot transport when the routed provider name is `github-copilot`; the Copilot module then resolves its headers and base URL, and the registry seeds the provider row and model fallback. |
+| API-key pools | `src/providers/api-key-selection.ts`, `src/providers/key-failover.ts` | A configured `apiKeyPoolStrategy` plus a cooling committed key rotates before the first send (`selectProactiveApiKeyTransport`); a 429 still rotates after the send and records a cooldown. `provider.apiKey` keeps mirroring the active entry so routing stays single-key. The pick is inert without a strategy or while the committed key is healthy. |
+| OAuth account failover | `src/oauth/generic-account-failover.ts`, `src/oauth/anthropic-routing.ts` | Reactive pre-output 429 recovery is presence-driven with 2+ eligible accounts. Pool and `oauthAccountFailover` flags govern proactive routing, not the reactive retry: a disabled Anthropic pool recovers through quota ordering rather than its dormant strategy, and a per-provider `enabled` beats the global default in either direction. |
+| OAuth login callback (inbound) | `src/oauth/callback-server.ts` | Every response, including non-callback 404s, closes its connection so a pooled socket cannot deliver a later login to a retired flow on the same callback port. |
+| Alibaba regions | `src/providers/alibaba-region-backup.ts`, `src/providers/alibaba-region-migration.ts`, `src/providers/alibaba-region-startup.ts` | Region migration backs up before rewriting and is idempotent across restarts. |
+| Discovery and quota | `src/providers/model-discovery.ts`, `src/providers/quota.ts` | Discovery rejects a response over 4 MiB or past 2,000 raw rows before caching it. |
+
+> Decision record: [ADR-0072](../decisions/ADR-0072-transport-inventory.md)
+
+Cursor external-model continuations attach data-URL screenshots from the contiguous active
+tool-result batch through the existing image preparation and selected-context owners. The batch
+shares the 12-image active cap. Bounded source labels are emitted in active user-action text so
+root pruning cannot erase attachment provenance; the same text participates in token estimation.
+Native Composer/MCP behavior and text-only historical replay remain unchanged.
+
+## Provider diagnostic outbound safety
+
+Provider connection tests and live model discovery share the GET-only provider outbound wrapper.
+Direct HTTP(S) resolves once and pins the validated address; HTTPS preserves the original Host/SNI
+and always verifies certificates. Proxy-configured requests stay on Bun fetch so HTTP(S)_PROXY,
+ALL_PROXY, and NO_PROXY semantics remain authoritative. The wrapper classifies successful local DNS answers, but
+only a typed DNS-resolution failure degrades to proxy resolution; every literal, metadata, and
+resolved-address policy error still rejects. Proxy mode logs once that the proxy-selected peer
+cannot be pinned. Private destinations additionally require allowPrivateNetwork plus NO_PROXY.
+
+Two fake-IP DNS accommodations exist, both for resolved answers only (a literal address in the URL
+still rejects). The IANA benchmark range (198.18/15 and its IPv4-mapped IPv6 spellings) is admitted
+whenever any outbound proxy applies to the host, because the range itself marks the answer synthetic.
+Mihomo's default IPv6 fake-IP range (fdfe:dcba:9876::/48) is ULA and carries no such mark, so it is
+admitted only when the proxy variable that matches the URL scheme is set (HTTPS_PROXY for https:,
+HTTP_PROXY for http:; ALL_PROXY is not consulted because Bun fetch does not honour it), the host is
+not in NO_PROXY, and the request is then bound to that proxy through Bun's explicit `proxy` option
+rather than environment inference. Both gates live in the outbound wrapper, not in classification:
+`classifyIpv6` and config-time validation (`providerDestinationResolvedError`) never admit the
+ULA, so provider save-time checks are unaffected (#3462).
+
+Both paths reject redirects and expose only credential-stripped final-address guidance. This phase
+does not cover ordinary requests, streaming, retries, or per-hop redirect review on those paths.
+Caller-owned `provider.fetch` executors are also deferred: they receive literal/config checks and
+redirect blocking, but cannot inherit DNS classification or peer pinning without a verified-peer
+executor contract. Main-request migration must not treat that branch as fixed-transport equivalent.
+
+Chat helper admission in `src/server/responses/core.ts` follows the
+[deferred stored-main contract](../providers/openai-tiers.md): only a needed Direct OpenAI helper
+claims stored main, after terminal vision, routed vision and search exclusions.
+
+Quota publication distinguishes display reports from explicitly supplied inference projections; a credential-bound cache read validates the current destination and key. See [scoped provider quota](../runtime.md#scoped-provider-quota-for-combo-selection).
+
+The management quota DTO keeps Combo editing aligned with scoped inference evidence;
+see [Combo editor routing quota](../gui-and-management-api.md#combo-editor-routing-quota).
+
+Claude replay carries [Go conversation affinity](../data-planes/inbound-compat.md#claude-affinity-at-final-go-dispatch)
+privately to final dispatch; preliminary route selection does not inject Go-only headers.
+
+Devin CLI credential path composition in `src/oauth/devin-cli.ts` follows the selected platform: Windows uses Win32 APPDATA paths, other platforms use POSIX XDG-data paths. The explicit absolute override remains verbatim; credential parsing and login behavior are unchanged.
diff --git a/structure/transports/responses.md b/structure/transports/responses.md
new file mode 100644
index 0000000000..2321d78dd6
--- /dev/null
+++ b/structure/transports/responses.md
@@ -0,0 +1,525 @@
+# Responses Transport
+
+## Responses HTTP/SSE
+
+`/v1/responses` is the main Codex-facing endpoint. The server parses Responses input, routes to a
+provider, lets the selected adapter speak the upstream protocol, then bridges adapter events back to
+Responses-compatible streaming output.
+
+### Credential-bearing HTTP redirects
+
+Credential/body-bearing HTTP sends use `redirect: "manual"` at the final executor boundary,
+including dispatch overrides and adapter/sidecar retries. `fetchWithHeaderTimeout` retains its
+legacy final argument for callers but no longer permits default-follow sends. Both same-origin
+and cross-origin redirects remain observable responses: retry helpers must not synthesize a 502
+before the owning route can apply its existing response and health policy. Native Responses and
+compact retain their 3xx/Location relay contract; image and search sidecar owners consume 3xx
+through their existing upstream-error path without relaying Location. This server policy does not govern client-side
+redirect following; providers requiring a redirect must be configured with their final API URL.
+
+### Fetch-helper import boundary
+
+`src/server/responses/fetch-helpers.ts` is a transport leaf shared by Responses, compact, and native
+Chat. Its runtime imports are limited to the Codex WebSocket transport, provider request pacing, and
+the upstream HTTP-version helper. Server, provider, and WebSocket data types remain type-only edges.
+It must not import routing, combos, OAuth, adapters, sidecars, response parsing, logging, or relay
+modules merely because those imports existed in the pre-split `responses.ts` monolith.
+
+### Semantic progress ownership
+
+The Responses proxy does not treat transcript growth as repository progress. It can observe request
+boundaries, response items, tool names and payloads, adapter events, retained bytes, and elapsed
+silence. It cannot observe the client's workspace or prove whether a successful tool result changed
+repository state. Consequently, the active-turn and session-lane gates are concurrency admission
+limits, the translator budget is a live retained-byte limit, the response-state caps are cache
+retention limits, and the stall watchdog is a silence limit. None is a cumulative continuation or
+semantic no-progress budget.
+
+> Decision record: [ADR-0031](../decisions/ADR-0031-responses-http-sse.md)
+
+> Decision record: [ADR-0032](../decisions/ADR-0032-responses-http-sse.md)
+
+> Decision record: [ADR-0033](../decisions/ADR-0033-responses-http-sse.md)
+
+> Decision record: [ADR-0034](../decisions/ADR-0034-responses-http-sse.md)
+
+> Decision record: [ADR-0035](../decisions/ADR-0035-responses-http-sse.md)
+
+> Decision record: [ADR-0036](../decisions/ADR-0036-responses-http-sse.md)
+
+> Decision record: [ADR-0037](../decisions/ADR-0037-responses-http-sse.md)
+
+Two coordinates that lower to the same wire name are treated as one tool when they denote one:
+`buildTools` flattens the reserved `functions` group without a namespace, so a bare declaration and
+a `functions` child of the same name are the duplicate the parser already tolerates — and the one
+`promoteClientLoadedTools` produces. The declaration is emitted once instead of failing the request.
+
+Replayed call items are lowered whether or not this turn declares the group they name. A catalog can
+be absent or change mid-session, but the client is still replaying items this layer's own response
+restoration stamped with a private `namespace`. Routed compaction runs this boundary before removing
+the tool surface so request-local aliases remain available for response restoration. Only
+`tool_choice` resolves a bare name through the catalog: a history
+item records which tool actually ran, so re-pointing it at a same-named namespace child would
+rewrite that record on a coincidence rather than translate it.
+
+Codex-private tool fields are removed at the same boundary from one table
+(`CANONICAL_ONLY_TOOL_FIELDS`) rather than one bespoke pass each: `external_web_access` on either
+web-search variant, and `defer_loading` on any declaration, which `activateDeferredTool` clears only
+for tools a `tool_search_output` already loaded. A new private bit is a row there.
+
+After that namespace boundary has produced public function tools, the Grok CLI Responses transport
+applies the same root-schema policy as its Chat transport. A root `oneOf`/`anyOf` is flattened only
+when the shared xAI normalizer can preserve its meaning; an unsafe function is omitted instead of
+letting one incompatible declaration reject the entire request before inference. This is scoped to
+`cli-chat-proxy.grok.com`: public `api.x.ai` keeps native root unions, as do unrelated Responses
+gateways. Both top-level `tools` and Responses Lite `additional_tools` pass through this policy.
+
+Only the ROOT rejects a union, so exclusivity is preserved by moving it down rather than widening
+it: a root `oneOf` whose branches differ in one property becomes that property's `oneOf`, or its
+`anyOf` when the branches are provably disjoint and the two keywords describe the same set. That
+property is also promoted into `required`, because absent it matched every branch — which the root
+`oneOf` rejects. Branches that are wholly identical validate nothing and have no faithful
+flattening, so they omit the tool. The walk carries depth, node, and variant budgets, since nested
+unions are combinatorial and a `$ref` diamond amplifies the same way without ever cycling;
+exceeding a budget omits that one function rather than expanding until memory is gone.
+
+Omitting a function makes `tool_choice` the loose end. A selector naming a dropped tool would reach
+Grok as a dangling reference, and relaxing it to `auto` is worse — the turn would quietly run
+without the tool the caller required. So an `allowed_tools` list drops the omitted entries while any
+remain, and a selection with nothing left to point at fails locally with the same 400 a tool catalog
+this proxy cannot lower already returns.
+
+The same noncanonical boundary strips ChatGPT's private `external_web_access` bit from routed
+`web_search` declarations. The public tool remains enabled and all other options remain intact;
+canonical OpenAI forwarding preserves the bit. xAI's public Responses schema enables browsing by
+the presence of `web_search` and rejects the private argument, so forwarding it made the first
+post-namespace request fail with HTTP 400.
+
+The option-aware `openai` provider uses `openai-responses` with `authMode: "forward"`. Pool mode
+resolves main plus added accounts through affinity/quota/cooldown ownership; Direct forwards only
+the allowed Codex/OpenAI auth/session headers from the current request and short-circuits pool
+state. `openai-apikey` uses its configured key and canonical API base URL. Missing credentials fail
+within their route; neither route falls through to the other. See
+[`openai-tiers.md`](../providers/openai-tiers.md).
+
+### Pre-dispatch API-key pool pick
+
+Key-auth routes with a configured `apiKeyPoolStrategy` and two or more pool entries pick a
+warm key before the first send (`selectProactiveApiKeyTransport` in
+`src/providers/key-failover.ts`). The pick is inert unless that strategy is set and the
+committed key is already cooling or missing from the pool: a healthy committed key, including
+a manual selection, is left alone and the common path returns null without a config write.
+`forgetApiKeyRotationCursor` drops the process-local round-robin cursor when the operator
+edits the pool, so a later pick cannot second-guess that choice.
+
+On the shared Responses path the assignment lands in `src/server/responses/core.ts`
+immediately before `resolveProviderTransport`. `route.provider` is copied into
+`adapterProvider` on the next lines, and later `providerFetch` consumers (the HTTP send,
+the image bridge, web search) read that pinned object with no stale-selection re-read. A
+pick after the pin would leave the first attempt on the cooled key.
+
+Native Chat Completions is a separate entry path: `src/server/chat-completions.ts` routes
+eligible `openai-chat` requests to `src/server/chat-native.ts` and never through Responses
+core, so that file repeats the same call before it binds the adapter. Native compact
+(`src/server/responses/compact.ts`) and the keyed Images relay (`src/server/images.ts`)
+do the same for the same reason. Request paths assign the Transport variant, not the bare
+`selectProactiveApiKey` snapshot: the snapshot is the persisted row, so it carries none of the
+backfills `routedProviderConfig` merges in at request time and none of the route's explicit
+runtime transport state. The load-bearing one is the credential -- a stored `\${VAR}` or
+keychain reference is resolved in `routedProviderConfig` and nowhere in the adapter, so a
+wholesale assignment sends the literal reference as the bearer token. `adapter` and `baseUrl`
+are not at risk on a stored row, because the config schema requires both.
+
+Reactive 429 rotation (`rotateProviderTransportOn429`) remains the recovery path after a
+send has already earned a throttle.
+
+### Routed service-tier capability
+
+OpenAI-compatible service-tier support is resolved only after the final provider/model wire is
+known. `supportsServiceTier` remains the provider fallback, while the exact
+`modelSupportsServiceTier` map can override it per upstream model, including an explicit `false`.
+The catalog and request path share this decision: a routed row publishes `service_tiers` only when
+the resolved policy is eligible, and the final-route normalizer applies the same gate to
+`service_tier`. Both `openai-responses` and `openai-chat` use the resolved provider/model capability
+for catalog publication, routing evidence, and fingerprints. Canonical Fast injection additionally
+requires a compatible FastWire mapping on the final adapter and an eligible policy. Setting
+`fastMode: false` drops it. On classified Chat routes, `chatServiceTier` separately authorizes
+foreign caller values; an exact-model `true` does not grant that forwarding permission. On
+unclassified Chat routes it gates every caller tier because no canonical Fast capability has been
+validated. An object-form registry wire default may also set `forwardCallerServiceTier: false` to
+close a known subscription gateway while leaving generic unclassified Responses passthrough
+unchanged. Exact `false`
+narrows provider defaults, and provider-level `supportsServiceTier: false` cannot be reopened.
+Capability is namespaced by the selected provider and model; model-name similarity and adapter type
+alone never opt a gateway in.
+
+`POST /v1/responses/compact` handles remote compaction v1 before the generic `/v1/responses` branch
+and before the `/v1/*` guard. Unknown `/v1/*` paths return JSON 404 errors instead of falling through
+to GUI static serving.
+
+Combo compaction recall uses accepted completed-response callbacks to record the final client-visible
+model and originating combo target. The existing child callback gate defers publication until an
+attempt is accepted and drops discarded/failed attempts. Both compaction entry points preserve
+explicit configured selectors before consulting bounded lane state. The existing state-store
+reconciliation owns removal of obsolete targets and generation fencing; core imports no registration
+composition root or Lab code. Recall retains routing identity only, never account credentials.
+
+> Decision record: [ADR-0038](../decisions/ADR-0038-responses-http-sse.md)
+
+A replayed compaction item carries an `encrypted_content` blob only its minting backend can decode,
+and the client replays it on every later turn. The proxy's own `ocx1:` envelopes are transparent
+base64, so they always lower to plain user messages. A native blob is relayed only when there is no
+known serving-identity mismatch and the destination is known to decode native blobs — the canonical
+ChatGPT forward surface, the official OpenAI API, or a provider with the explicit
+`decodesNativeCompactionBlobs` capability. The destination gate alone is insufficient because more
+than one backend, including OpenAI and xAI, mints native blobs: a destination can decode its own blob
+without being able to decode the previous backend's. The same serving-identity mismatch signal
+therefore strips reasoning `encrypted_content` and degrades native compaction blobs through the
+existing opaque-note path. When the thread has no recorded identity, the destination-only behavior
+is deliberately unchanged. Forward auth alone is not evidence: noncanonical forward providers
+receive no caller credentials and may point at any backend. On any other routed destination the blob
+also degrades to the same opaque note the bridged parser uses, because forwarding it there fails the
+turn and the item outlives the failure in the client transcript, repeating on every later turn
+including the compaction turn the proxy itself drives. With `store: false`, request sanitization
+strips ids from every input item, including compact-wire items, matching codex-rs
+(`core/src/client.rs:918-925`). Compact-wire items remain exempt from response-side field backfill.
+
+> Decision record: [ADR-0039](../decisions/ADR-0039-responses-http-sse.md)
+
+### Mixed-wire provider defaults
+
+Registry `modelWireDefaults` select an evidence-backed upstream protocol for an exact model without
+changing the provider-wide adapter. Explicit, allowed `modelAdapters` configuration always wins,
+including an entry that opts the model back into the provider-wide wire. Defaults are applied only
+while the configured provider still matches the registry transport, so reusing a preset name for a
+different custom destination does not inherit its upstream assumptions. Object-form defaults may
+also narrow the decision by inbound protocol and authentication mode; an auth-scoped default must
+not leak from a subscription transport into an API-key or forwarded-credential route.
+
+xAI keeps `openai-chat` as its provider-wide compatibility wire, but Grok 4.5/4.6 subscription
+Responses requests default to native `openai-responses`. Existing namespace, hosted-search and
+reasoning-replay normalization remains in force. The reserved `xai` OAuth transport is name-pinned
+to the Grok CLI gateway even if its saved base URL differs; custom provider IDs do not inherit this
+default. API-key requests, translated Chat/Anthropic defaults and other Grok models retain their
+existing wire and tier policy. OAuth still drops caller-owned `service_tier` on either wire.
+
+Native Responses participates in the same pre-stream OAuth HTTP-429 account rotation as the Chat
+bridge. It uses the existing account quorum, cooldown and three-rotation request cap, refreshes
+the complete credential/transport/replay identity, and attributes usage to the serving account.
+Single-account installs do not retry; a missing alternate credential preserves the original error.
+
+Startup removes legacy Grok 4.5/4.6 Chat overrides once and persists the provider-owned
+`xaiResponsesDefaultVersion` marker. Later explicit Chat choices survive restarts. The migration
+rebases under the config mutation lock; unavailable persistence warns and uses an isolated in-memory
+projection without overwriting invalid disk state. Read-only config loading does not migrate.
+
+The Z.AI coding plan gets the same shape for a different reason. Its registry row owns a fixed
+destination, so `routedProviderConfig()` already rewrites a config written against the retired
+Chat endpoint (`/api/coding/paas/v4`, `openai-chat`) onto Responses at `https://api.z.ai` on every
+request. Startup persists that same canonical pair to the `zai` row once and records
+`zaiResponsesDefaultVersion`, so the dashboard, `ocx doctor` and direct config readers stop showing
+an endpoint the runtime never uses and the per-boot discarded-base-URL warning stops. The rewrite is
+behavior-preserving because it only touches a row the router canonicalizes anyway; Chat stays
+reachable per model through `modelAdapters`. A custom-named provider at the retired endpoint is not
+migrated — the router leaves its wire alone, and `destinationAliases` already supplies its metadata.
+
+The dashboard's Chat Completions switch and `ocx provider edit xai --xai-chat on|off` share the
+existing `modelAdapters` lane. On writes Chat for both models; off writes Responses. Unrelated
+overrides remain intact. The legacy PATCH field `xaiResponsesOptIn` retains its direction:
+true selects Responses, false now writes explicit Chat rather than deleting entries. Its derived
+`xaiResponsesOptInState` reflects effective Responses-inbound routing, including registry defaults;
+only genuinely different effective wires report mixed. A switch write also records the migration
+version (without lowering a future version), and provider-form overwrites retain omitted choices.
+
+Native routed Responses code-mode turns also receive the shared result-emission contract in both
+instructions and the lowered exec input description: a bare awaited helper return is discarded by
+the host, so visible results need `text(...)` or `notify(...)` in that first call. Paired exec outputs
+containing only an empty completion/failure wrapper use the shared explanatory annotation. The
+whole result is examined; populated text, image/file parts, unpaired results, shell-only catalogs,
+compaction and OpenAI-operated destinations are untouched. This does not rewrite valid JavaScript
+or reconstruct output that the code-mode host never emitted.
+
+Routed code-mode turns also carry the host contract for the nested helpers, stated in the same three
+injection sites as the result-emission rule (shared catalog nudge, Cursor code-mode guidance, native
+routed Responses instructions): `tools.apply_patch` takes one string that opens and closes with the
+bare patch marker lines (blank lines or indentation around them are tolerated; a decorated or missing
+marker is rejected), the isolate has no `import`/`require`, and a command that outlives
+`yield_time_ms` is polled through `write_stdin` with empty `chars` rather than a shell sleep loop.
+When a code-mode exec result still carries one of the host's failure strings ("expects a string
+input", "The first line of the patch must be", "The last line of the patch must be", "Unsupported
+import in exec"), the native routed Responses, Kiro, and Cursor result paths append a one-line
+recovery hint naming the broken rule; flat shell bridges and foreign MCP namespaces are never
+annotated, Responses and Kiro additionally require the request's verified code-mode catalog, Cursor
+matches the exact `exec` name under its `opencodex-responses` provider without catalog context, and
+Cursor's error classification and Kiro's whitespace and failed-wrapper grouping are unchanged. Both
+halves live in `src/adapters/exec-tool-result-normalize.ts`
+so the pre-call and post-hoc wording cannot drift. This guidance and annotation change rewrites
+neither the model's JavaScript nor its patch payload; the existing name-alias delimiter
+normalization in `src/responses/code-mode-helper-compat.ts` is unchanged, and the host still rejects a
+malformed call exactly as before. Anthropic, Google, OpenAI-chat and command-code result paths
+have no exec-result seam today and are not annotated.
+
+> Decision record: [ADR-0040](../decisions/ADR-0040-responses-http-sse.md)
+
+> Decision record: [ADR-0041](../decisions/ADR-0041-responses-http-sse.md)
+
+### xAI string agent-message continuation
+
+`normalizeRoutedAgentMessages` owns raw Responses `agent_message` lowering. Its existing
+nonempty all-readable array behavior remains shared by non-forward destinations. The optional
+`allowStringContent` argument defaults to false and is enabled only by the non-forward adapter
+call when `isXaiResponsesDestination` recognizes HTTPS `api.x.ai` or `cli-chat-proxy.grok.com`
+on the standard port. A nonblank string becomes one `input_text` part with the original text;
+the same author/recipient attribution is retained and the private transport item id is removed.
+
+This addresses readable child-result delivery (#3907), not scheduling or decryption. Blank,
+malformed, ciphertext-only and mixed unknown/encrypted content retains the existing fail-closed
+path. Forward destinations never enable the option. The parser and encrypted-task recovery
+owners are unchanged, and no broad content-schema validation or adapter-wide string conversion
+is introduced. Mocked server fixtures cover parent, child, and parent-result continuation over
+SSE and JSON while preserving actual tool-call/result pairs.
+
+OpenCode Go documents `gpt-5.6-luna` on `/zen/go/v1/responses` while sibling models use its Chat or
+Anthropic endpoints. The built-in preset therefore selects `openai-responses` only for Luna and
+keeps the provider-wide `openai-chat` default for other non-pinned models. This endpoint correction
+does not set `modelResponsesUpstreamStreaming`: client `stream: true` remains real upstream
+streaming until a current-runtime reproduction justifies a separate bounded-JSON compatibility
+policy.
+
+Go's non-forward Responses request path moves valid `additional_tools` wrappers into top-level
+`tools` through `src/adapters/opencode-go-additional-tools.ts`. Placement runs after existing
+custom/search/namespace lowering and before code-mode, compaction and final hosted-tool pruning.
+It does not recalculate wire identities or response aliases. The matcher reads the constructed
+send URL, resolving it with URL semantics, and requires HTTPS `opencode.ai`, the standard port
+and exact `/zen/go/v1/responses`. Normal and endpoint-inclusive bases or split `responsesPath`
+configurations agree; a custom path resolving to Zen or elsewhere does not acquire Go placement.
+Credentials, query, fragment, foreign hosts and other resource paths are excluded. The existing
+URL constructor canonicalizes trailing base slashes before this check. Malformed wrappers remain unchanged and
+the shared mixed-ciphertext agent-message gate remains fail-closed.
+
+The canonical `opencode-go` registry entry defaults to `statelessResponses: true` because Go
+rejects reasoning ciphertext combined with `previous_response_id` (#3838). Existing derive
+logic fills absent values and preserves explicit false; renamed custom configurations receive
+no new destination-based migration. The existing stateless pass sets `store: false`, removes
+stored continuation parameters, and repairs orphan calls/results without claiming execution
+success. A local replay-cache hit supplies history; a miss cannot reconstruct it, so callers
+receive `previous_response_not_found` before upstream dispatch and must resend complete history
+without `previous_response_id`. Routed custom-tool lowering requires the same recovery when a delta
+custom result has no local call, because its original wire type cannot be established and guessing it
+would send an unmatched result upstream. The check resolves the selected wire protocol and the
+request's own tool declarations after final route selection, so stateful destinations keep their
+upstream-owned native function and native-only custom continuations. Explicit input still receives
+orphan repair; this path asks the client to replay rather than reconstructing history. This flag also enables the existing
+visible content-to-summary rewrite for SSE and JSON; summary-channel items and opaque reasoning
+blobs keep their existing response handling. The shared recording callback applies the same
+reasoning rewrite under the exact client-visible predicate before caching output, after tool
+restoration and function normalization. This keeps full-content replay fingerprints comparable
+for both full-history-plus-ID and delta continuations without weakening identity checks. Hidden
+summaries and opaque blobs keep their existing cache representation. It does not change streaming selection or Chat
+model routes. Go fixtures cover Luna, Grok and Muse against both response formats.
+
+The canonical OpenCode Go transport also derives `x-opencode-session` from the existing hashed
+session lane before per-model wire selection. One conversation keeps one opaque affinity value
+across Responses, Chat, retries, and key rotation, while sibling subagents remain distinct. An
+operator-supplied header wins case-insensitively. Renamed providers are covered only when their
+fixed key-auth destination still matches the registry; custom and lookalike URLs receive nothing.
+Muse Spark's Responses sanitizer also drops the provider-rejected `search_content_types` and
+`indexed_web_access` fields from plain `web_search` tools while preserving preview tools and
+unrelated models.
+
+> Decision record: [ADR-0042](../decisions/ADR-0042-responses-http-sse.md)
+
+> Decision record: [ADR-0043](../decisions/ADR-0043-responses-http-sse.md)
+
+### Passthrough SSE stream shapes (#314)
+
+Native passthrough SSE has TWO shapes, selected per request in
+`src/server/responses/core.ts`:
+
+- **Default outside Windows: tee + background inspection.** `upstreamResponse.body.tee()` sends
+  branch[0] through a terminal-aware client relay while branch[1] is
+  drained eagerly by `consumeForInspection`/`consumeForResponseLogMetadata`
+  for terminal-outcome recording, quota, the passthrough continuation cache,
+  and request logs. This remains the default shape on bundled Bun 1.3.14.
+- **Terminal-aware eager bounded relay** (`src/server/relay-eager.ts`). Windows
+  uses this single-reader shape for rewrite traffic and for no-rewrite traffic
+  selected by `selectEagerPath` in `src/lib/bun-stream-caps.ts`; the latter keeps
+  `legacy-tee` and known-bad-runtime `auto` on tee as documented. When selected,
+  `response.completed` closes the client stream even if upstream keeps HTTP/SSE
+  alive. Darwin uses it for no-client-rewrite traffic only (neither image-gen
+  aliases nor item-id repair) and is explicit-only: `auto` stays tee even after
+  a future threshold bump. One eager reader + byte-bounded
+  client queue + post-cancel bounded discard-drain replaces the tee and goes
+  directly to the response without a JS rewrite wrapper, preserving the full
+  inspection side-effect set (shared `createSseInspector` factory in `relay.ts`)
+  including the #44 late-terminal semantics.
+
+Both client readers also retain a bounded, redacted message from a bare upstream
+`error` event. If EOF arrives without a real Responses terminal, they synthesize
+one `response.failed` with that message instead of replacing it with `adapter_eof`.
+The delivering reader owns this evidence; an asynchronous tee inspection branch
+cannot reliably supply it before EOF. Inspection independently applies the same
+bare-error rule when EOF arrives, so account health records failure instead of
+clearing avoidance as if the turn had succeeded. Existing real terminals and
+caller cancellation retain precedence on both branches. Native recovery preflight
+also preserves a rejected body reader and its bounded prefix for the normal
+mid-stream failure path; it does not turn that rejection into a decrypt retry.
+
+Native Responses may rebuild once when encrypted function/custom-tool output or
+agent-message content receives the exact known decrypt rejection before output
+commits. Recovery replaces only encrypted parts with an omission marker, preserves
+the raw request object used by continuation persistence guards, and uses the same
+adapter and cancellation path. A missing Content-Type is allowed only under the
+existing successful streaming condition. Default combo preflight classification
+is unchanged; only the native recovery caller supplies the exact error predicate.
+
+Both shapes carry the inbound caller-abort signal separately from the turn/shutdown
+controller. A caller-driven read rejection is 499/client_cancel without pool penalty;
+a genuine upstream reset remains synthetic 502. An already received terminal, including
+one completed by the error-path parser flush, retains its real outcome. Eager relays
+remove the caller listener when done and close signal-cancelled downstream streams even
+when the response-body cancel hook has not run.
+
+The two-shape contract is mirror-commented in `src/server/index.ts`; the real
+`core.ts` gate is source-invariant-tested by `tests/responses/passthrough-abort.test.ts`,
+and the platform matrix lives in `tests/lib/bun-stream-caps.test.ts`. Keep all three
+in lockstep with any passthrough-policy change.
+
+Canonical ChatGPT forward streaming has one transport-specific exception. A
+stable Bun runtime at or above 1.4.0 may use Codex's upstream
+`responses_websockets` transport; bundled Bun 1.3.14, prereleases, and
+unverifiable runtime identities stay on HTTP/SSE. A successful upstream WS
+response is re-encoded to the same SSE surface and forced through the bounded
+eager single-reader relay instead of `tee()`: raw and enveloped frames are capped
+at 4 MiB and the WS producer queue at 8 MiB. Overflow closes the upstream and
+the downstream relay emits its terminal `response.failed` event plus `[DONE]`.
+Pre-open HTTP fallback remains unmarked and follows the ordinary configured
+stream path.
+
+At the canonical ChatGPT destination, HTTP Responses Lite intent is copied into
+the native per-frame WS metadata key, and the routing hint is derived from the
+final outgoing model/tier. No caller identity is synthesized. Noncanonical
+opt-in gateways keep their own metadata policy. Oversized/unsupported-runtime
+HTTP fallback preserves the original HTTP body and Lite header.
+
+Canonical WS quota and response metadata preceding the first Responses event
+are projected into bounded, allowlisted HTTP headers before the response is
+committed. Later quota observations update only the captured serving account;
+they cannot retroactively change HTTP headers already sent to the client.
+Control frames remain bounded, and provider credential/cookie headers are not
+forwarded. Once a WS create may have been sent, a missing prelude, overflow or
+disconnect settles as an errored SSE body rather than a retryable fetch failure,
+so HTTP fallback cannot duplicate that inference. A standalone no-response
+exchange has a 90-second prelude deadline in addition to the upgrade deadline.
+That prelude deadline is a ceiling, not a floor: the exchange runs under the
+caller's abort signal, so a `connectTimeoutMs` shorter than 90 seconds cancels
+an already-sent create before the prelude timer fires.
+These are transport-fidelity guarantees, not a provider-billing guarantee.
+
+Eligible complete-input creates can retain a canonical upstream socket within
+one selected account, credential, thread and turn. Model/tier and immutable
+handshake headers and the selected outbound proxy must also match. Turn-state and turn-metadata headers are
+projected into their same-name per-frame metadata slots; explicit body values win.
+The pool retains at most 32 sockets, expires idle sockets after 30 seconds, and
+retires a socket after five minutes or 32 successful exchanges (after active work
+finishes). Cancellation, errors, idle unsolicited frames and shutdown dispose it.
+A busy key uses a separate one-shot connection rather than interleaving requests.
+
+This is connection reuse, not native incremental-input synthesis: complete HTTP
+inputs are never trimmed and no previous response id is invented. Explicit
+continuation IDs, named lanes, warmup and background requests remain outside this
+pool. A fresh credential-dispatch guard runs before every warm send. Per-exchange
+listeners, response/item correlation and metadata ownership detach before release.
+No pool timer or shutdown registration exists before eligible traffic activates it.
+
+Translated response request-log tracking and the heartbeat relay also reuse
+`createSseInspector`. This keeps every client-facing SSE observation path on
+the same byte-bounded, discard-and-resynchronize frame policy and ensures the
+request-log, first-output, and terminal observers share one payload parse.
+The inspector records a structured `response.failed` status before invoking the
+terminal observer. Native Responses, Chat Completions, Claude Messages, and WebSocket
+request logs must therefore finalize through the context-aware terminal mapper; recognized
+`cyber_policy` terminals stay `400 / cyber_policy` rather than collapsing to a generic 502.
+
+The client-facing boundary treats the first Responses terminal as authoritative in both relay
+shapes. High-confidence policy errors carried as `response.incomplete`, `response.failed`, or a
+top-level `error` are normalized to one `response.failed / cyber_policy` event without changing the
+refusal outcome; later bytes cannot create a second terminal. A clean HTTP 200 EOF with no terminal
+instead emits one `response.incomplete` with `adapter_eof`, followed by one `[DONE]`. Delimiter-less
+EOF candidates follow the owning repair policy: the native boundary accepts a structurally valid
+terminal tail, while an opted-in terminal repair keeps its unframed suffix tainted and emits
+`missing_terminal_event`. Pull/tee and eager relays therefore agree on terminal, sentinel, and
+request-log accounting without promoting a truncated repair candidate.
+
+> Decision record: [ADR-0044](../decisions/ADR-0044-responses-http-sse.md)
+
+## Chat-to-Responses message phase inference
+
+Chat Completions streams do not carry the Responses `message.phase` field. The bridge keeps an
+unphased live message provisional while its deltas arrive, then assigns `commentary` when a later
+tool, search, reasoning, or assistant boundary proves that more work follows, and assigns
+`final_answer` only when a clean terminal `done` closes the current message. Explicit adapter
+phases always win. Streaming `output_item.added` remains unphased until that future boundary is
+known; `output_item.done` and the terminal response snapshot carry the authoritative inferred phase
+with the same item id. The batch/non-streaming bridge follows the same rule.
+
+> Decision record: [ADR-0069](../decisions/ADR-0069-chat-to-responses-message-phase-inference.md)
+
+## Upstream reset retry
+
+`src/lib/upstream-retry.ts` guards upstream fetches against stale pooled keep-alive sockets
+(Cloudflare closes idle connections; Bun's fetch reuses the dead socket and rejects with
+`ECONNRESET` before any response bytes). `fetchWithResetRetry` retries only
+connection-reset-shaped rejections (up to 3 total attempts, jittered backoff, warn-logged);
+timeouts, aborts, `ECONNREFUSED`, HTTP error statuses, and mid-stream SSE failures are never
+retried. Guarded paths: the ChatGPT passthrough and generic adapter fetch in
+`src/server/responses.ts`, the vision/web-search sidecars, and the web-search loop's direct-fetch
+fallback. Adapters with their own `fetchResponse` (kiro, cursor, google) keep their own retry
+policies; kiro imports the shared abort/sleep helpers from this module.
+
+## Same-provider combo quota fallback
+
+For a failover combo with multiple models on the same Codex-login OpenAI provider, a pre-stream
+429/402 carrying only `x-codex-*-reset-at` may advance to the later model on the same account. The
+failed physical combo target still enters its normal target cooldown. An explicit `Retry-After`
+remains an account-wide instruction and blocks the later target; a quota response with neither an
+explicit retry delay nor a usable reset timestamp keeps the conservative default account cooldown.
+This exception is request-scoped and is not applied to direct requests, round-robin combos, or a
+combo whose remaining eligible targets use other providers.
+
+> Decision record: [ADR-0070](../decisions/ADR-0070-same-provider-combo-quota-fallback.md)
+
+## Combo streaming commit boundary
+
+An HTTP 200 does not by itself commit a streaming combo child. The combo parent runs the child's
+downstream Responses SSE through `src/server/responses/combo-stream-preflight.ts`, which owns one
+reader and buffers only until one of these boundaries:
+
+- a non-control Responses event begins client-visible output or a tool/action item, after which the
+  target is committed and cross-target replay is forbidden;
+- a `response.failed` terminal arrives first, in which case the terminal is converted back through
+  the ordinary bounded combo-failure classifier and may advance to the next declared target;
+- a completed/incomplete terminal or the aggregate preflight byte or retained-chunk cap is reached,
+  in which case the current target is committed conservatively.
+
+The buffered bytes are replayed unchanged before the reader continues. Native passthrough and eager
+relay identity markers are restored on the wrapped response so Windows/Bun stream paths and deferred
+logging retain their existing owners. A failed child keeps its physical attempt receipt and usage,
+while the successful child remains the logical request result.
+
+HTTP 410 remains terminal by default. It advances and cools only the exact combo target when the
+structured code or message explicitly identifies a model lifecycle event (end-of-life, retired,
+deprecated, sunset, decommissioned, or no longer available). An unrelated application-level 410 is
+not retried.
+
+> Decision record: [ADR-0071](../decisions/ADR-0071-combo-streaming-commit-boundary.md)
+
+Chat helper admission in `src/server/responses/core.ts` follows the
+[deferred stored-main contract](../providers/openai-tiers.md): only a needed Direct OpenAI helper
+claims stored main, after terminal vision, routed vision and search exclusions.
+
+The management quota DTO keeps Combo editing aligned with scoped inference evidence;
+see [Combo editor routing quota](../gui-and-management-api.md#combo-editor-routing-quota).
+
+Claude replay carries [Go conversation affinity](../data-planes/inbound-compat.md#claude-affinity-at-final-go-dispatch)
+privately to final dispatch; preliminary route selection does not inject Go-only headers.
diff --git a/structure/transports/streaming-health.md b/structure/transports/streaming-health.md
new file mode 100644
index 0000000000..68093843ea
--- /dev/null
+++ b/structure/transports/streaming-health.md
@@ -0,0 +1,201 @@
+# Streaming Health And WebSocket
+
+## Heartbeat and stall deadline
+
+The HTTP/SSE bridge emits an SSE comment-line keep-alive (`: opencodex heartbeat`) during upstream
+silence to re-arm Codex's idle timer (Codex's default `stream_idle_timeout` is 300 s and ANY SSE
+bytes re-arm it). A comment line is discarded by every eventsource parser without producing an event,
+so strict Responses decoders never see an unknown variant. Those bridge-enqueued keepalive frames do
+NOT count as activity for the bridge's own watchdog: a bounded stall deadline (default 300 s,
+configurable via `stallTimeoutSec`, checked on the 2 s heartbeat tick) closes the stream with
+`response.incomplete` / `upstream_stall_timeout` and cancels the upstream request if no real
+adapter events arrive. Adapter-yielded `{ type: "heartbeat" }` events DO reset the watchdog.
+
+Top-level `emptyCompletionRetry: true` opts Responses turns into one identical replay when an
+upstream turn produces neither output text nor a tool call, including a stream that ends before a
+terminal event. A terminal-less stream is replayed only before actionable output; post-output EOF
+remains incomplete so text or tool calls cannot be duplicated. The default is off because the replay
+may be billable; `OCX_EMPTY_COMPLETION_RETRY=0` is a disable-only emergency override. Streaming and
+buffered HTTP adapters plus `runTurn` transports share the same guard, while combo attempts and
+routed compaction stay excluded. Pre-content reasoning is retained under named event-count and byte
+caps and emits liveness heartbeats while held. A second empty result or retry failure becomes typed
+502 `empty_completion_retry_failed`; usage is merged across sends, and the Logs attempt records
+recovery kind `empty-completion`.
+
+The web-search loop requests `stream: true` for every routed-model iteration, but buffers the events
+needed to decide whether to intercept a synthetic search call. Text explicitly phased as
+`commentary` is safe to forward live because it cannot terminate the turn; this keeps Kiro's
+progress visible. A Kiro stream EOF after user-facing text or reasoning gets one bounded completion
+retry, because neither the upstream text event nor `END_TURN` / `STOP_SEQUENCE` reliably distinguishes
+progress from a final answer. Those two clean-stop reasons prove only that the inference ended; on a
+tool-enabled turn, only the private completion tool authorizes `final_answer`. Any other explicit
+reason already terminated the inference upstream and is reported as a terminal state rather
+than converted into another model request: output-token limits become continuable incomplete output,
+context-window exhaustion becomes a non-retryable `context_length_exceeded` error, filtering becomes
+filtered incomplete output, and a `TOOL_USE` without an actual tool call is a contradiction. Since
+the stop reason arrives only at the end of the stream, `required`-mode assistant text is held inside
+the adapter until a real tool call starts or the stream ends, then released as `commentary` unless a
+private completion call supplied the final answer. Each held event yields a `heartbeat` in its place
+so the stall watchdog stays armed. Synthetic search calls, real tool calls,
+and terminal events remain buffered until the iteration validates. Only the first iteration's final
+response headers/status and any 429 key rotations are handled eagerly. A failure before downstream
+SSE starts returns non-2xx JSON; once headers have started the final response, a generation failure
+is emitted as `response.failed` SSE.
+
+### Pre-stream provider input overflow
+
+A provider HTTP 413 received before streaming starts is unambiguous request-size refusal, but raw
+relay is not compatible with Codex: Codex classifies the unknown status as retryable and resends the
+same oversized turn through its reconnect budget. For a streaming Responses caller, OpenCodex
+therefore converts the final 413 (after any adapter-owned bounded image retry) into one HTTP-200 SSE
+`response.failed` event with `error.code = context_length_exceeded` and `retryable = false`. Codex
+recognizes that terminal contract, marks the context as full, and can run its own compaction policy
+on the next turn. Combo routing treats 413 as a stop condition and performs the conversion only at
+the outer client boundary, so the failed target is never recorded as a successful combo attempt.
+
+Non-streaming Responses callers retain HTTP 413 and receive a JSON `error` with
+`type: invalid_request_error` and `code: context_length_exceeded`, including routed synthetic
+compaction. The upstream body is replaced with the same bounded, proxy-owned message used by SSE.
+Combo attempts retain their existing internal failure accounting; classification happens only at
+the outer client boundary. Local admission and configured outbound-byte refusals keep their own
+distinct codes. Classification does not shrink input or automatically retry compaction.
+The proxy never silently drops
+prompts or images: it does not own the client's transcript, and deleting input would hide data that
+was never analyzed. The streaming error message is proxy-owned and bounded instead of relaying the
+upstream 413 body, which may echo request content.
+
+> Decision record: [ADR-0049](../decisions/ADR-0049-heartbeat-and-stall-deadline.md)
+
+Kiro transient HTTP 429 recovery is coordinated process-wide after the first throttle: healthy
+traffic remains parallel, but throttled followers wait behind one abort-aware probe and share a
+deadline that is re-checked after every sleep. Event-stream `ThrottlingException` records the same
+deadline for the next client replay. Retries are bounded to three attempts; hard quota responses and
+ordinary 5xx errors are not replayed. Completion fallback rebuilds only replayable text, preserves
+the original user/tool-result turn for reasoning-only attempts, supplies neutral non-empty carriers
+for empty tool output, and validates role alternation plus tool-use/result pairing before transport.
+
+Provider-level `retryOn429` (devlog 260802_429_same_target_retry) is the generic, opt-in
+same-target 429 retry for API-key providers (`authMode: "key"`), primarily single-key pools
+that cannot use multi-key failover. In the pre-stream recovery loop, a 429 waits (`Retry-After`
+or the fixed interval, capped at `maxIntervalMs`) and replays the identical request on the same
+key before any failover, up to `attempts` extra times per request (the budget lives outside the
+recovery loop, so a 413/401 replay cannot re-arm it). The same wait-and-replay applies to every
+other key-auth surface that bypasses that loop: the Responses passthrough wire (e.g. the
+built-in DeepSeek preset), the image/video bridge and web-search sidecar loops (before their
+`on429` key rotation), and Anthropic terminal-guard continuations (before key/account
+failover). The policy covers HTTP-capable adapters only: custom `runTurn` transports in the
+image loop run through an event queue and never receive an HTTP status, so they are outside
+the HTTP retry scope and cannot replay a 429. Codex never retries 429 client-side (openai/codex#30471), so this is the only
+defense for those providers; the final 429 still carries `Retry-After` for clients that honor
+it. Concurrent requests each honor their own policy — there is no process-wide shared cooldown
+(unlike the Kiro pattern), so a rate-limit storm multiplies upstream volume by at most
+`attempts + poolKeys` per request (same-key replays, then failover keys; the pool size is the
+operator-configured `apiKeyPool` length, fixed for the duration of the request). Every surface
+releases (and awaits the cancellation of) the unread 429 body before the backoff, records the
+`rate-limit-429` recovery kind on replay sends, and the bridge loops clear the old
+response-header deadline before the wait and start a fresh one afterward — client cancellation
+is re-checked after the wait, so 499 always wins over a stale-deadline edge, and backoffs never
+consume the connect budget or surface as a 504. The wait is abort-aware:
+once the server observes the client disconnect (Bun propagates it asynchronously, observed
+1–10 s), the sleep is interrupted, the unread 429 body is released, and the request is
+cancelled with 499 before any replay; because the propagation is async, a replay may precede
+the cancel if the interval elapses first (bounded by the same `attempts` budget).
+
+Provider-level `requestPacing` is the proactive companion to `retryOn429`. It reserves outbound
+request-start slots before transport work begins, so a known RPM ceiling does not have to fail once
+before the proxy reacts. One provider-wide lane enforces the aggregate ceiling. Exact model lanes
+may add a slower interval without lowering the provider-wide interval or blocking an otherwise
+eligible sibling model. Queue wait is abort-aware and happens before the response-header timeout is
+armed. The shared fetch boundary covers HTTP and Responses WebSocket sends; explicit adapter
+`fetchResponse` and `runTurn` dispatches reserve the same lane at their call sites. Image-bridge
+iterations reserve before arming their per-attempt response-header deadline.
+
+> Decision record: [ADR-0050](../decisions/ADR-0050-heartbeat-and-stall-deadline.md)
+
+Historical `web_search_call` output items from previous Responses turns are not converted into
+assistant text. They are UI/search-cell evidence, not a replayable search result payload; turning
+them into strings risks routed models echoing an internal marker or implying a current search ran
+when the sidecar is unavailable. The active sidecar path is the only place that emits new
+`web_search_call_begin` / `web_search_call_end` events.
+
+Four independent clocks bound this path. `stallTimeoutSec` is the base bridge event-stall budget.
+`connectTimeoutMs` (default 200 s) covers only DNS/TCP/TLS and the wait for final response headers,
+not response-body generation. Config-file-only
+`webSearchSidecar.routedModelStallTimeoutMs` (default 200 s, integer 1..2147483647) bounds continuous
+raw response-byte inactivity for a routed-model iteration and resets on every non-empty byte.
+`webSearchSidecar.timeoutMs` (default 60 s) separately bounds one hosted search request (lowered
+from 200 s so an unavailable/limit-exhausted search backend degrades within ~1 min instead of
+hanging the whole turn, #398). The
+effective web-search bridge watchdog is
+`max(base stall, connect timeout, routed-model stall, sidecar timeout) + 30 s` (230 s at defaults,
+dominated by the routed-model stall clock),
+with seam heartbeats between bounded units. None of these clocks is a total generation deadline.
+
+## WebSocket
+
+The WebSocket endpoint exists at `/v1/responses`, but discovery is opt-in:
+
+```json
+{
+  "websockets": false
+}
+```
+
+`websocketsEnabled(config)` is true only for an explicit `true`. When false, opencodex removes
+`supports_websockets` from injected provider tables and routed catalog entries, keeping Codex on
+HTTP/SSE. When true, Codex may use Responses WebSocket frames handled by `src/server/ws-bridge.ts`.
+If Codex still attempts a WebSocket upgrade while the feature is disabled, `/v1/responses` rejects
+the upgrade with 426 so Codex falls back to HTTP cleanly.
+
+That setting controls the client-facing upgrade only. The transparent upstream
+ChatGPT WS optimization described above is selected independently and still
+returns the same downstream SSE contract. Its WSS route checks NO_PROXY first, then selects the
+first non-empty HTTPS_PROXY, https_proxy, ALL_PROXY, or all_proxy value. HTTP_PROXY alone does not
+route WSS. Unsupported or malformed selected proxy values skip the WebSocket attempt and use the
+existing SSE path immediately; they never fall through to a lower-priority proxy or direct WebSocket
+egress. HTTP/SSE fallback retains Bun fetch's own proxy rules, which do not consult ALL_PROXY.
+
+The endpoint handles `response.create`, ignores `response.processed`, supports warmup
+`generate: false`, and feeds the same request pipeline as HTTP/SSE.
+
+Registry-declared per-model compatibility hints (`modelResponsesUpstreamStreaming`) may ask the
+upstream Responses endpoint for bounded JSON on ANY client transport — WebSocket or ordinary
+HTTP/SSE. The bridge reframes that JSON into the same Responses event sequence
+(`src/server/responses-json-events.ts`): WS turns send the frames as WebSocket messages, while
+HTTP clients that requested streaming receive a synthesized terminal SSE body (created →
+output_item.done → terminal → `[DONE]`). No production registry entry currently opts in:
+DeepSeek V4 Flash used this path while its public-beta Responses stream was suspected of not
+closing on the terminal event, but the official guide documents a
+`response.completed`/`response.incomplete`/`response.failed` terminal with no `data: [DONE]`
+sentinel, and live probes (2026-08-07) confirm the stream closes on the terminal. The relay's
+terminal-output boundary (`src/server/relay.ts`) cuts the stream at that event and synthesizes
+`[DONE]` itself, so DeepSeek streams live again; the registry knob remains as a one-line
+rollback for upstreams that regress, kept suite-reachable by a synthetic-registry fixture in
+`tests/providers/deepseek-inbound-wire.test.ts`.
+Synthesized output is capped at 10,000 items across HTTP and WebSocket reframing. HTTP frames are
+encoded incrementally, so bounded upstream JSON cannot expand into an unbounded event array or SSE string.
+
+DeepSeek V4 Flash keeps native Responses streaming for progressive reasoning, text, and tool-call
+delivery. Its registry entry enables a model-scoped terminal repair before the existing
+inspection/client split. A real `response.completed`, `response.failed`, or `response.incomplete`
+event always passes through unchanged. If every opened output item has a structurally complete
+`output_item.done` and no real terminal arrives for five seconds, the repair emits exactly one
+`response.completed` snapshot and closes the upstream reader. EOF or `[DONE]` uses the same strict
+completion check; open, malformed, duplicate, contradictory, or unknown output graphs fail closed
+as `response.incomplete`, never synthetic success. The repair shares the per-turn translator byte
+budget, preserves backpressure, and composes ahead of item-id/snapshot rewrites so HTTP/SSE and
+WebSocket clients observe the same canonical lifecycle.
+
+`ws-bridge.ts` preserves upstream `failed` and `incomplete` status values in the final WebSocket
+frame rather than always emitting `response.completed`. If the response status is `failed`, a
+`response.failed` frame is sent; otherwise `response.completed` carries through the original status.
+
+Chat helper admission in `src/server/responses/core.ts` follows the
+[deferred stored-main contract](../providers/openai-tiers.md): only a needed Direct OpenAI helper
+claims stored main, after terminal vision, routed vision and search exclusions.
+
+The management quota DTO keeps Combo editing aligned with scoped inference evidence;
+see [Combo editor routing quota](../gui-and-management-api.md#combo-editor-routing-quota).
+
+Claude replay carries [Go conversation affinity](../data-planes/inbound-compat.md#claude-affinity-at-final-go-dispatch)
+privately to final dispatch; preliminary route selection does not inject Go-only headers.
diff --git a/tests/adapters/adapter-registry-authority.test.ts b/tests/adapters/adapter-registry-authority.test.ts
index d7bac03afe..08103c43f2 100644
--- a/tests/adapters/adapter-registry-authority.test.ts
+++ b/tests/adapters/adapter-registry-authority.test.ts
@@ -21,6 +21,8 @@ const EXPECTED_ADAPTER_NAMES = {
   azure: "azure-openai",
   "azure-openai": "azure-openai",
   cursor: "cursor",
+  "devin-cli": "devin-cli",
+  devin: "devin",
   "mimo-free": "mimo-free",
   qoder: "qoder",
 } as const;
diff --git a/tests/adapters/adapter-tool-conformance.test.ts b/tests/adapters/adapter-tool-conformance.test.ts
index 91fd5a399b..5b8fa543f7 100644
--- a/tests/adapters/adapter-tool-conformance.test.ts
+++ b/tests/adapters/adapter-tool-conformance.test.ts
@@ -420,10 +420,15 @@ describe("registry-derived routed tool conformance", () => {
   });
 
   const TOOL_LESS_ADAPTERS = new Set(["codebuddy", "qoder"]);
+  // Both Devin providers are runTurn-only: devin-cli drives a local CLI over ACP
+  // stdio and devin streams Connect-RPC from runTurn, so for both of them
+  // buildRequest returns a placeholder and tools never travel the wire path.
+  const RUN_TURN_ONLY_WIRES = new Set(["devin-cli", "devin"]);
 
   test("every registered adapter keeps the nested apply_patch helper in its final request", async () => {
     for (const [adapterId] of adapterDefinitions()) {
       if (TOOL_LESS_ADAPTERS.has(adapterId)) continue;
+      if (RUN_TURN_ONLY_WIRES.has(effectiveAdapterContract(adapterId).wire)) continue;
       const contract = effectiveAdapterContract(adapterId);
       const body = await outbound(adapterId, codeModeParsed(contract.wire));
       const advertised = advertisedToolNames(contract.wire, body);
@@ -438,6 +443,7 @@ describe("registry-derived routed tool conformance", () => {
   test("tool_choice none disables every registered adapter's callable tool surface", async () => {
     for (const [adapterId] of adapterDefinitions()) {
       if (TOOL_LESS_ADAPTERS.has(adapterId)) continue;
+      if (RUN_TURN_ONLY_WIRES.has(effectiveAdapterContract(adapterId).wire)) continue;
       const contract = effectiveAdapterContract(adapterId);
       const enabledBody = await outbound(adapterId, toolChoiceParsed(contract.wire));
       expect(advertisedToolNames(contract.wire, enabledBody).length, `${adapterId}:enabled`).toBeGreaterThan(0);
@@ -449,9 +455,10 @@ describe("registry-derived routed tool conformance", () => {
   test("every parsed streaming wire restores hostile freeform input exactly", async () => {
     for (const [adapterId] of adapterDefinitions()) {
       if (TOOL_LESS_ADAPTERS.has(adapterId)) continue;
+      if (RUN_TURN_ONLY_WIRES.has(effectiveAdapterContract(adapterId).wire)) continue;
       const contract = effectiveAdapterContract(adapterId);
       const driver = TOOL_WIRE_DRIVERS[contract.wire];
-      if (!driver.streamingToolCall) {
+      if (!driver?.streamingToolCall) {
         // OpenAI Responses is a normal passthrough here and only parses routed compaction;
         // Cursor's proprietary runTurn stream has focused parser coverage elsewhere.
         expect(["openai-responses", "cursor"]).toContain(contract.wire);
@@ -464,6 +471,7 @@ describe("registry-derived routed tool conformance", () => {
   test("every buffered adapter preserves same-name tools from different namespaces", async () => {
     for (const [adapterId] of adapterDefinitions()) {
       if (TOOL_LESS_ADAPTERS.has(adapterId)) continue;
+      if (RUN_TURN_ONLY_WIRES.has(effectiveAdapterContract(adapterId).wire)) continue;
       const contract = effectiveAdapterContract(adapterId);
       if (contract.wire === "openai-responses" || contract.wire === "cursor") {
         // Native Responses passthrough and Cursor's protobuf transport do not use the routed
@@ -479,6 +487,7 @@ describe("registry-derived routed tool conformance", () => {
   test("every routed adapter fails closed for an ambiguous bare selector", async () => {
     for (const [adapterId] of adapterDefinitions()) {
       if (TOOL_LESS_ADAPTERS.has(adapterId)) continue;
+      if (RUN_TURN_ONLY_WIRES.has(effectiveAdapterContract(adapterId).wire)) continue;
       const contract = effectiveAdapterContract(adapterId);
       if (contract.wire === "openai-responses" || contract.wire === "cursor") continue;
       const parsed = namespacedCollisionParsed(contract.wire);
@@ -505,9 +514,10 @@ describe("registry-derived routed tool conformance", () => {
   test("every streaming adapter restores namespaced custom/function collisions distinctly", async () => {
     for (const [adapterId] of adapterDefinitions()) {
       if (TOOL_LESS_ADAPTERS.has(adapterId)) continue;
+      if (RUN_TURN_ONLY_WIRES.has(effectiveAdapterContract(adapterId).wire)) continue;
       const contract = effectiveAdapterContract(adapterId);
       const driver = TOOL_WIRE_DRIVERS[contract.wire];
-      if (!driver.streamingToolCall || !driver.extractWireToolName) {
+      if (!driver?.streamingToolCall || !driver?.extractWireToolName) {
         expect(["openai-responses", "cursor"]).toContain(contract.wire);
         continue;
       }
@@ -548,7 +558,9 @@ describe("registry-derived routed tool conformance", () => {
   test("every registered adapter replays the exact apply_patch input on continuation", async () => {
     for (const [adapterId] of adapterDefinitions()) {
       if (TOOL_LESS_ADAPTERS.has(adapterId)) continue;
+      if (RUN_TURN_ONLY_WIRES.has(effectiveAdapterContract(adapterId).wire)) continue;
       const contract = effectiveAdapterContract(adapterId);
+      // Devin is a runTurn-only adapter; continuation replay is not expressed on buildRequest.
       const body = await outbound(adapterId, continuationParsed(contract.wire));
       expect(continuationInput(contract.wire, body), adapterId).toBe(PATCH);
     }
diff --git a/tests/adapters/bridge-legacy-shell-normalization.test.ts b/tests/adapters/bridge-legacy-shell-normalization.test.ts
index c6d5cdbe2d..0b4a94283c 100644
--- a/tests/adapters/bridge-legacy-shell-normalization.test.ts
+++ b/tests/adapters/bridge-legacy-shell-normalization.test.ts
@@ -87,6 +87,16 @@ describe("bridge normalizes code-mode helper names against the declared catalog"
     expect(sse).toContain("await tools.apply_patch");
   });
 
+  test("default.view_image echoes are normalized back to declared bare view_image (#4176)", async () => {
+    const sse = await drain(bridgeToResponsesSSE(
+      toolTurn("default.view_image", "{\"path\":\"image.png\"}"), "deepseek-x", undefined, undefined, undefined, undefined, 50_000,
+      { declaredToolNames: new Set(["view_image"]) },
+    ));
+    expect(sse).not.toContain("undeclared client tool");
+    expect(sse).toContain("\"name\":\"view_image\"");
+    expect(sse).toContain("image.png");
+  });
+
   test("a catalog that declares exec_command itself is never rewritten", async () => {
     const sse = await drain(bridgeToResponsesSSE(
       toolTurn("exec_command"), "deepseek-x", undefined, undefined, undefined, undefined, 50_000,
diff --git a/tests/adapters/bridge-nonstreaming-terminal.test.ts b/tests/adapters/bridge-nonstreaming-terminal.test.ts
index 7fe0a705ab..de6bfb37c9 100644
--- a/tests/adapters/bridge-nonstreaming-terminal.test.ts
+++ b/tests/adapters/bridge-nonstreaming-terminal.test.ts
@@ -310,3 +310,71 @@ describe("Command Code finishReason error is a failure, not a stop", () => {
     expect((json.output as { type: string }[]).some(o => o.type === "compaction")).toBe(false);
   });
 });
+
+
+describe("truncated done preserves open tool integrity (#4312)", () => {
+  const cases = [
+    ["refusal", "content_filter"],
+    ["content_filter", "content_filter"],
+    ["max_tokens", "max_output_tokens"],
+    ["length", "max_output_tokens"],
+  ] as const;
+  for (const [stopReason, reason] of cases) {
+    for (const kind of ["function_call", "custom_tool_call", "tool_search_call"] as const) {
+      test(`${stopReason}: open ${kind} stays incomplete in both projections`, async () => {
+        const options = {
+          freeformToolNames: kind === "custom_tool_call" ? new Set(["fixture"]) : undefined,
+          toolSearchToolNames: kind === "tool_search_call" ? new Set(["fixture"]) : undefined,
+        };
+        const args = kind === "custom_tool_call" ? "partial input" : '{"arg":"unfinished';
+        const events: AdapterEvent[] = [
+          { type: "text_delta", text: "partial answer" },
+          { type: "tool_call_start", id: "call_fixture", name: "fixture" },
+          { type: "tool_call_delta", arguments: args },
+          { type: "done", stopReason },
+        ];
+        async function* source(): AsyncGenerator<AdapterEvent> { yield* events; }
+        const text = await new Response(bridgeToResponsesSSE(
+          source(), "fixture/model", undefined, options.freeformToolNames, options.toolSearchToolNames,
+        )).text();
+        const frames = text.split("\n\n").flatMap(frame => {
+          const data = frame.split("\n").find(line => line.startsWith("data: "))?.slice(6);
+          return data && data !== "[DONE]" ? [JSON.parse(data)] : [];
+        });
+        expect(terminalEventNames(text)).toEqual(["response.incomplete"]);
+        expect(frames.some(frame => frame.type === "response.function_call_arguments.done"
+          || frame.type === "response.custom_tool_call_input.done")).toBe(false);
+        const terminal = frames.find(frame => frame.type === "response.incomplete");
+        const buffered = buildResponseJSON(events, "fixture/model", options);
+        for (const response of [terminal.response, buffered]) {
+          expect(response.status).toBe("incomplete");
+          expect(response.incomplete_details.reason).toBe(reason);
+          const call = response.output.find((item: { type: string }) => item.type === kind);
+          expect(call.status).toBe("incomplete");
+          if (kind === "function_call") expect(call.arguments).toBe(args);
+          if (kind === "custom_tool_call") expect(call.input).toBe(args);
+          expect(response.output.find((item: { type: string }) => item.type === "message")
+            .content[0].text).toBe("partial answer");
+        }
+        const itemDone = frames.find(frame => frame.type === "response.output_item.done" && frame.item.type === kind);
+        expect(itemDone.item.status).toBe("incomplete");
+      });
+    }
+    test(`${stopReason}: a previously completed call stays completed`, async () => {
+      const events: AdapterEvent[] = [
+        { type: "tool_call_start", id: "call_complete", name: "fixture" },
+        { type: "tool_call_delta", arguments: '{"arg":"complete"}' },
+        { type: "tool_call_end", id: "call_complete" },
+        { type: "done", stopReason },
+      ];
+      const buffered = buildResponseJSON(events, "fixture/model");
+      expect(buffered.status).toBe("incomplete");
+      const output = buffered.output as { type: string; status?: string }[];
+      expect(output.find(item => item.type === "function_call")?.status).toBe("completed");
+      const text = await sseText(events);
+      expect(terminalEventNames(text)).toEqual(["response.incomplete"]);
+      expect(text).toContain("event: response.function_call_arguments.done");
+      expect(text).toContain('"arguments":"{\\"arg\\":\\"complete\\"}","status":"completed"');
+    });
+  }
+});
diff --git a/tests/adapters/key-failover.test.ts b/tests/adapters/key-failover.test.ts
index 8efb505aa6..561c1cefa9 100644
--- a/tests/adapters/key-failover.test.ts
+++ b/tests/adapters/key-failover.test.ts
@@ -18,11 +18,18 @@ import {
   rotateProviderTransportOn429,
   rotateProviderTransportOn401,
 } from "../../src/providers/key-failover";
+import {
+  forgetApiKeyRotationCursor,
+  selectProactiveApiKey,
+  selectProactiveApiKeyTransport,
+} from "../../src/providers/key-failover";
 import { resolveOpenCodeGoTransport } from "../../src/providers/opencode-go-transport";
 import { deriveXaiConvId } from "../../src/providers/xai-transport";
 import { routeModel, routedProviderConfig } from "../../src/router";
 import { setProviderKeychainEntryFactoryForTests } from "../../src/providers/key-store";
 import { setActiveProviderApiKey } from "../../src/providers/api-keys";
+import { clearProviderApiKeyQuotaCache, setCachedProviderApiKeyQuotaForTests } from "../../src/providers/quota-key-accounts";
+import { ACCOUNT_QUOTA_TTL_MS } from "../../src/providers/quota-wire";
 import { subscribeAccountSelections } from "../../src/lib/account-selection-events";
 import { providerManagementConfigError, safeConfigDTO } from "../../src/server/auth-cors";
 import type { OcxConfig, OcxParsedRequest, OcxProviderConfig } from "../../src/types";
@@ -449,4 +456,188 @@ describe("rotateKeyOn401", () => {
     expect(rotated?.apiKey).toBe("key-beta-444555666777");
     expect(getKeyCooldownUntil("p", "k1", now)).toBe(now + 10 * 60_000);
   });
+
+  describe("proactive key selection", () => {
+    const now = 2_000_000;
+
+    test("does nothing without a configured strategy", () => {
+      const config = makeConfig({ apiKey: "key-alpha-000111222333", apiKeyPool: pool3() });
+      forgetApiKeyRotationCursor("p");
+      rotateKeyOn429(config, "p", null, now);
+      expect(selectProactiveApiKey(config, "p", now)).toBeNull();
+    });
+
+    test("keeps a healthy committed key instead of rotating off an operator choice", () => {
+      const config = makeConfig({
+        apiKey: "key-alpha-000111222333",
+        apiKeyPool: pool3(),
+        apiKeyPoolStrategy: "round-robin",
+      });
+      forgetApiKeyRotationCursor("p");
+      // No cooldown recorded, so the committed key is healthy and must survive untouched.
+      expect(selectProactiveApiKey(config, "p", now)).toBeNull();
+      expect(config.providers.p.apiKey).toBe("key-alpha-000111222333");
+    });
+
+    test("moves off a committed key that is already cooling", () => {
+      const config = makeConfig({
+        apiKey: "key-alpha-000111222333",
+        apiKeyPool: pool3(),
+        apiKeyPoolStrategy: "round-robin",
+      });
+      forgetApiKeyRotationCursor("p");
+      // Cool the committed key, then persist it back as active so the next request starts on
+      // it. Writing only the in-memory copy is not enough: the selector re-reads under the
+      // persistence lock, which is the guard that stops it clobbering a healthy choice.
+      rotateKeyOn429(config, "p", null, now);
+      setActiveProviderApiKey(config, "p", "k1");
+      const picked = selectProactiveApiKey(config, "p", now);
+      expect(picked).not.toBeNull();
+      expect(picked?.apiKey).not.toBe("key-alpha-000111222333");
+      expect(getKeyCooldownUntil("p", "k1", now)).toBeGreaterThan(now);
+    });
+
+    /**
+     * The picker answers with the PERSISTED row, so a request path that assigns it to a live
+     * route wholesale loses everything `routedProviderConfig` backfills at request time and
+     * every piece of explicit runtime transport state the route was carrying. The most
+     * load-bearing of those is the credential: a stored `\${VAR}` reference is resolved in
+     * `routedProviderConfig` and nowhere in the adapter, so the snapshot's `apiKey` is the
+     * reference itself.
+     *
+     * `selectProactiveApiKeyTransport` is the pre-dispatch twin of
+     * `rotateProviderTransportOn429` and goes through the same rebuild seam. Red control:
+     * return the snapshot from it and both the resolved credential and the retained `fetch`
+     * assertions below fail.
+     */
+    test("the Transport twin rebuilds the route the picker only snapshots", () => {
+      process.env.OCX_KEYFAILOVER_WARM = "resolved-warm-key";
+      try {
+        const config = makeConfig({
+          apiKey: "key-alpha-000111222333",
+          apiKeyPool: [
+            { id: "k1", key: "key-alpha-000111222333", addedAt: 1 },
+            { id: "k2", key: "\${OCX_KEYFAILOVER_WARM}", addedAt: 2 },
+          ],
+          apiKeyPoolStrategy: "round-robin",
+        });
+        forgetApiKeyRotationCursor("p");
+        rotateKeyOn429(config, "p", null, now);
+        setActiveProviderApiKey(config, "p", "k1");
+        const sentinelFetch = (async () => new Response("")) as typeof fetch;
+        const routed = { ...routedProviderConfig("p", config.providers.p!), fetch: sentinelFetch };
+        const transport = selectProactiveApiKeyTransport(config, "p", routed, undefined, now);
+        expect(transport).not.toBeNull();
+        // The route gets the RESOLVED credential.
+        expect(transport?.apiKey).toBe("resolved-warm-key");
+        // Explicit runtime transport state survives the rebuild, exactly as it does on 429.
+        expect(transport?.fetch).toBe(sentinelFetch);
+        // And the persisted row still holds the reference, which is what made the wholesale
+        // assignment wrong in the first place.
+        expect(loadConfig().providers.p!.apiKey).toBe("\${OCX_KEYFAILOVER_WARM}");
+      } finally {
+        delete process.env.OCX_KEYFAILOVER_WARM;
+      }
+    });
+
+    test("returns null when every key is cooling", () => {
+      const config = makeConfig({
+        apiKey: "key-alpha-000111222333",
+        apiKeyPool: pool3(),
+        apiKeyPoolStrategy: "round-robin",
+      });
+      forgetApiKeyRotationCursor("p");
+      rotateKeyOn429(config, "p", null, now);
+      rotateKeyOn429(config, "p", null, now);
+      rotateKeyOn429(config, "p", null, now);
+      config.providers.p.apiKey = "key-alpha-000111222333";
+      expect(selectProactiveApiKey(config, "p", now)).toBeNull();
+    });
+
+    test("a single-key pool is a no-op", () => {
+      const config = makeConfig({
+        apiKey: "key-alpha-000111222333",
+        apiKeyPool: [{ id: "k1", key: "key-alpha-000111222333" }],
+        apiKeyPoolStrategy: "round-robin",
+      });
+      forgetApiKeyRotationCursor("p");
+      expect(selectProactiveApiKey(config, "p", now)).toBeNull();
+    });
+
+    /** Quota rows live in a private cache keyed on the resolved secret; seed it through the seam. */
+    function seedQuota(config: OcxConfig, keyId: string, key: string, percent: number | null, unavailable?: true) {
+      setCachedProviderApiKeyQuotaForTests(
+        "p", config.providers.p!, keyId, key,
+        percent === null ? null : { weeklyPercent: percent, updatedAt: Date.now() } as never,
+        unavailable,
+      );
+    }
+
+    function cooledFirstKey(strategy: "round-robin" | "quota") {
+      const config = makeConfig({ apiKey: "key-alpha-000111222333", apiKeyPool: pool3(), apiKeyPoolStrategy: strategy });
+      forgetApiKeyRotationCursor("p");
+      clearProviderApiKeyQuotaCache();
+      rotateKeyOn429(config, "p", null, now);
+      setActiveProviderApiKey(config, "p", "k1");
+      return config;
+    }
+
+    test("quota picks the roomiest eligible key", () => {
+      const config = cooledFirstKey("quota");
+      // beta is nearly spent, gamma is barely touched. Round-robin would have taken beta simply
+      // because it is next; ranking is the entire difference.
+      seedQuota(config, "k2", "key-beta-444555666777", 80);
+      seedQuota(config, "k3", "key-gamma-888999000111", 10);
+      expect(selectProactiveApiKey(config, "p", now)?.apiKey).toBe("key-gamma-888999000111");
+    });
+
+    test("an unmeasured key outranks a measured-and-spent one", () => {
+      const config = cooledFirstKey("quota");
+      // beta is provably at its limit; gamma has never been measured. Unmeasured is not assumed
+      // fresh, but it is not assumed spent either -- and "spent" is the one thing we know here.
+      seedQuota(config, "k2", "key-beta-444555666777", 100);
+      expect(selectProactiveApiKey(config, "p", now)?.apiKey).toBe("key-gamma-888999000111");
+    });
+
+    test("a stale unavailable row is not evidence", () => {
+      const config = cooledFirstKey("quota");
+      // beta carries a roomy last-good measurement attached to a FAILING probe, which the cache
+      // keeps for half an hour. Ranking on it would prefer a number nothing currently supports.
+      seedQuota(config, "k2", "key-beta-444555666777", 0, true);
+      seedQuota(config, "k3", "key-gamma-888999000111", 70);
+      expect(selectProactiveApiKey(config, "p", now)?.apiKey).toBe("key-gamma-888999000111");
+    });
+
+    test("with nothing measured the first eligible key is taken", () => {
+      const config = cooledFirstKey("quota");
+      // A provider with no per-key quota reader must land on exactly today's behaviour.
+      expect(selectProactiveApiKey(config, "p", now)?.apiKey).toBe("key-beta-444555666777");
+    });
+
+    /**
+     * A SUCCESSFUL row expires too. Nothing on the selection path probes or sweeps, so once a
+     * dashboard or CLI read populated the cache, a ten-minute-old measurement could keep
+     * outranking a key with no evidence until some unrelated write swept it.
+     *
+     * gamma is the roomier key, so a cache that still counts as evidence picks gamma. Expired,
+     * neither row is evidence and the roster order decides -- beta, the same answer the
+     * nothing-measured case above gets. Red control: drop the two freshness checks in
+     * `cachedApiKeyQuota` and this returns gamma.
+     */
+    test("a successful row past its TTL is not evidence either", () => {
+      const config = cooledFirstKey("quota");
+      seedQuota(config, "k2", "key-beta-444555666777", 90);
+      seedQuota(config, "k3", "key-gamma-888999000111", 10);
+      const realNow = Date.now;
+      // Only the CACHE clock moves. The cooldown clock is the `now` the selector is handed, and
+      // the two are independent on purpose -- otherwise this would also un-cool k1.
+      Date.now = () => realNow() + ACCOUNT_QUOTA_TTL_MS + 1;
+      try {
+        expect(selectProactiveApiKey(config, "p", now)?.apiKey).toBe("key-beta-444555666777");
+      } finally {
+        Date.now = realNow;
+      }
+    });
+
+  });
 });
diff --git a/tests/adapters/openai/openai-api-virtual-models.test.ts b/tests/adapters/openai/openai-api-virtual-models.test.ts
index dc72ea8313..9a30f3b718 100644
--- a/tests/adapters/openai/openai-api-virtual-models.test.ts
+++ b/tests/adapters/openai/openai-api-virtual-models.test.ts
@@ -13,7 +13,8 @@ import {
 } from "../../../src/providers/openai-virtual-models";
 import { PROVIDER_REGISTRY } from "../../../src/providers/registry";
 import { resolveWireProtocolOverride } from "../../../src/server/adapter-resolve";
-import { saveConfig } from "../../../src/config";
+import { loadConfig, saveConfig } from "../../../src/config";
+import { clearKeyCooldowns, rotateKeyOn429 } from "../../../src/providers/key-failover";
 import { startServer } from "../../../src/server";
 import { usageLogPath } from "../../../src/usage/log";
 
@@ -176,6 +177,64 @@ describe("validateOpenAiVirtualModelDefinition", () => {
 });
 
 describe("OpenAI API compact transport", () => {
+
+  test("a cooled committed key is replaced before the first native compact send", async () => {
+    const originalFetch = globalThis.fetch;
+    const home = mkdtempSync(join(tmpdir(), "ocx-openai-api-compact-pool-"));
+    process.env.OPENCODEX_HOME = home;
+    clearKeyCooldowns();
+    saveConfig({
+      port: 0,
+      defaultProvider: "openai-apikey",
+      openaiProviderTierVersion: 2,
+      providers: {
+        "openai-apikey": {
+          adapter: "openai-responses",
+          baseUrl: "https://api.openai.com/v1",
+          authMode: "key",
+          apiKey: "sk-platform",
+          apiKeyPoolStrategy: "round-robin",
+          apiKeyPool: [
+            { id: "first", key: "sk-platform" },
+            { id: "second", key: "sk-warm" },
+          ],
+        },
+      },
+    } as never);
+
+    // Cool the committed key the way a real 429 does, then point the stored selection back at
+    // it. Native compact never enters handleResponses, so nothing else would move it.
+    const live = loadConfig();
+    rotateKeyOn429(live, "openai-apikey", null, Date.now(), "sk-platform");
+    const restored = loadConfig();
+    restored.providers["openai-apikey"]!.apiKey = "sk-platform";
+    saveConfig(restored);
+
+    const seen: Array<string | null> = [];
+    globalThis.fetch = async (input, init) => {
+      const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+      if (url !== "https://api.openai.com/v1/responses/compact") throw new Error(`unexpected upstream URL: ${url}`);
+      seen.push(new Headers(init?.headers).get("authorization"));
+      return new Response(JSON.stringify({ output: [] }), { headers: { "content-type": "application/json" } });
+    };
+
+    const server = startServer(0);
+    try {
+      const response = await originalFetch(new URL("/v1/responses/compact", server.url), {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ model: "openai-apikey/gpt-5.6-sol", input: [] }),
+      });
+      expect(response.status).toBe(200);
+      expect(seen).toEqual(["Bearer sk-warm"]);
+    } finally {
+      globalThis.fetch = originalFetch;
+      await server.stop(true);
+      clearKeyCooldowns();
+      removeTreeWithRetry(home);
+    }
+  });
+
   test("maps every Pro id to base, strips reasoning, buffers failures, caps bodies, and logs exactly once", async () => {
     const originalFetch = globalThis.fetch;
     const home = mkdtempSync(join(tmpdir(), "ocx-openai-api-compact-"));
diff --git a/tests/adapters/openai/openai-chat-hardening.test.ts b/tests/adapters/openai/openai-chat-hardening.test.ts
index 2279e4937e..b051817469 100644
--- a/tests/adapters/openai/openai-chat-hardening.test.ts
+++ b/tests/adapters/openai/openai-chat-hardening.test.ts
@@ -1377,6 +1377,55 @@ describe("openai-chat response_format emission", () => {
     });
   });
 
+  // Narrower neighbour of the kill switch: the upstream rejects the json_schema TYPE, so the
+  // request is downgraded to json_object rather than stripped. Both wires must agree.
+  describe("json_schema downgrade for noJsonSchemaModels", () => {
+    const schemaFormat = {
+      type: "json_schema",
+      json_schema: { name: "answer", schema: { type: "object" }, strict: true },
+    };
+    const passthrough = (
+      modelId: string,
+      providerOverrides: Partial<OcxProviderConfig>,
+      responseFormat: unknown = schemaFormat,
+    ) => JSON.parse(buildOpenAIChatPassthroughRequest(
+      provider(providerOverrides),
+      { messages: [{ role: "user", content: "hi" }], response_format: responseFormat },
+      modelId,
+      false,
+    ).body as string) as Record<string, unknown>;
+
+    test("downgrades json_schema to json_object on the native wire", () => {
+      expect(passthrough("test-model", { noJsonSchemaModels: ["test-model"] }).response_format)
+        .toEqual({ type: "json_object" });
+    });
+
+    test("leaves a json_object request untouched", () => {
+      expect(passthrough("test-model", { noJsonSchemaModels: ["test-model"] }, { type: "json_object" }).response_format)
+        .toEqual({ type: "json_object" });
+    });
+
+    test("keeps the schema for a :tag sibling the operator never listed", () => {
+      expect(passthrough("test-model:structured", { noJsonSchemaModels: ["test-model"] }).response_format)
+        .toEqual(schemaFormat);
+    });
+
+    test("the full kill switch still wins when a model is on both lists", () => {
+      expect(passthrough("test-model", {
+        noJsonSchemaModels: ["test-model"],
+        noStructuredOutputModels: ["test-model"],
+      }).response_format).toBeUndefined();
+    });
+
+    test("the translated wire downgrades the same request", () => {
+      const built = createOpenAIChatAdapter(provider({ noJsonSchemaModels: ["test-model"] })).buildRequest({
+        ...parsed(),
+        options: { textFormat: { type: "json_schema", name: "answer", schema: { type: "object" }, strict: true } },
+      });
+      expect(bodyOf(built).response_format).toEqual({ type: "json_object" });
+    });
+  });
+
 // Tool-call deltas are BUFFERED until a terminal signal, so this adapter can consume upstream
 // frames for a long time while yielding nothing downstream. The Responses bridge arms its
 // stall watchdog on ADAPTER activity, not socket activity, so a model streaming a large
diff --git a/tests/adapters/openai/openai-chat-model-suffix.test.ts b/tests/adapters/openai/openai-chat-model-suffix.test.ts
index 69dcee5b59..96ba37e1fc 100644
--- a/tests/adapters/openai/openai-chat-model-suffix.test.ts
+++ b/tests/adapters/openai/openai-chat-model-suffix.test.ts
@@ -1,5 +1,8 @@
 import { describe, expect, test } from "bun:test";
 import { createOpenAIChatAdapter, stripBracketedModelSuffix } from "../../../src/adapters/openai-chat";
+import { createResponsesPassthroughAdapter } from "../../../src/adapters/openai-responses";
+import { parseRequest } from "../../../src/responses/parser";
+import { withTestTranslatorBudget } from "../../helpers/translator-budget";
 import { createAnthropicAdapter } from "../../../src/adapters/anthropic";
 import { routeModel } from "../../../src/router";
 import type { OcxConfig, OcxParsedRequest, OcxProviderConfig } from "../../../src/types";
@@ -113,10 +116,26 @@ describe("openai-chat adapter wire model normalization", () => {
     expect(wireModel(req)).toBe("glm-5.2[1m]");
   });
 
-  test("a routed zai config strips glm-5.2[1m]", async () => {
-    const req = createOpenAIChatAdapter(routedZaiProvider()).buildRequest(parsed("glm-5.2[1m]"));
+  test("a routed zai config opted back into Chat strips glm-5.2[1m]", async () => {
+    // zai defaults to Responses now, so this is the modelAdapters opt-in path: the override
+    // swaps the adapter and the row's chatCompletionsPath carries the request to the Chat
+    // prefix. The bracket strip has to survive that swap.
+    const req = createOpenAIChatAdapter({ ...routedZaiProvider(), adapter: "openai-chat" })
+      .buildRequest(parsed("glm-5.2[1m]"));
     expect(wireModel(req)).toBe("glm-5.2");
   });
+
+  test("the Responses wire strips the alias too, on the passthrough body", async () => {
+    // The Responses adapter forwards the raw body instead of rebuilding it from the parsed
+    // selector, and the router writes the routed id into that raw body. Stripping only the
+    // parsed selector would send `glm-5.2[1m]` upstream, which Z.AI answers with a 400.
+    const provider = routedZaiProvider();
+    expect(provider.adapter).toBe("openai-responses");
+    const adapter = withTestTranslatorBudget(createResponsesPassthroughAdapter(provider));
+    const req = await adapter.buildRequest(parseRequest({ model: "glm-5.2[1m]", input: "hi" }));
+    expect((JSON.parse(req.body as string) as { model?: unknown }).model).toBe("glm-5.2");
+    expect(req.url).toBe("https://api.z.ai/api/v1/responses");
+  });
 });
 
 describe("anthropic adapter leaves the bracketed suffix intact", () => {
diff --git a/tests/adapters/openai/openai-chat-path-override.test.ts b/tests/adapters/openai/openai-chat-path-override.test.ts
new file mode 100644
index 0000000000..f7857dd3f9
--- /dev/null
+++ b/tests/adapters/openai/openai-chat-path-override.test.ts
@@ -0,0 +1,58 @@
+/**
+ * `chatCompletionsPath` is the mirror of `responsesPath`: a relative send path for the
+ * openai-chat wire.
+ *
+ * It exists because a per-model wire override swaps `provider.adapter` and leaves
+ * `provider.baseUrl` alone (src/server/adapter-resolve.ts). An upstream that serves Chat
+ * Completions and Responses under different prefixes therefore cannot be reached by the
+ * adapter swap by itself. Z.AI is exactly that shape: `/api/v1/responses` and
+ * `/api/coding/paas/v4/chat/completions` on one host and one key, with
+ * `/api/v1/chat/completions` answering 403.
+ */
+import { describe, expect, test } from "bun:test";
+import { createOpenAIChatAdapter } from "../../../src/adapters/openai-chat";
+import { routeModel } from "../../../src/router";
+import type { OcxConfig, OcxParsedRequest, OcxProviderConfig } from "../../../src/types";
+
+function parsed(modelId: string): OcxParsedRequest {
+  return {
+    modelId,
+    context: { messages: [{ role: "user", content: "hello", timestamp: 0 }] },
+    stream: false,
+    options: {},
+  };
+}
+
+describe("openai-chat send path override", () => {
+  test("without the field the adapter keeps appending /chat/completions to baseUrl", () => {
+    const provider: OcxProviderConfig = { adapter: "openai-chat", baseUrl: "https://example.test/v1" };
+    const req = createOpenAIChatAdapter(provider).buildRequest(parsed("some-model"));
+    expect(req.url).toBe("https://example.test/v1/chat/completions");
+  });
+
+  test("a configured path replaces the whole suffix, trailing slash and all", () => {
+    const provider: OcxProviderConfig = {
+      adapter: "openai-chat",
+      baseUrl: "https://example.test/",
+      chatCompletionsPath: "/api/other/v4/chat/completions",
+    };
+    const req = createOpenAIChatAdapter(provider).buildRequest(parsed("some-model"));
+    expect(req.url).toBe("https://example.test/api/other/v4/chat/completions");
+  });
+
+  test("the zai row carries both wires, so a Chat opt-in reaches the Chat prefix", () => {
+    const config: OcxConfig = {
+      port: 10100,
+      defaultProvider: "zai",
+      providers: { zai: { adapter: "openai-responses", baseUrl: "https://api.z.ai" } },
+    };
+    const routed = routeModel(config, "zai/glm-5.3").provider;
+    // Both paths are seeded from the registry onto the resolved provider.
+    expect(routed.responsesPath).toBe("/api/v1/responses");
+    expect(routed.chatCompletionsPath).toBe("/api/coding/paas/v4/chat/completions");
+    // Opting a model back into Chat only swaps the adapter; the path field is what keeps
+    // the request off `https://api.z.ai/chat/completions`, which is not an endpoint.
+    const req = createOpenAIChatAdapter({ ...routed, adapter: "openai-chat" }).buildRequest(parsed("glm-5.3"));
+    expect(req.url).toBe("https://api.z.ai/api/coding/paas/v4/chat/completions");
+  });
+});
diff --git a/tests/adapters/openai/openai-provider-option.test.ts b/tests/adapters/openai/openai-provider-option.test.ts
index 5e1943ceb0..d40ef2a6b3 100644
--- a/tests/adapters/openai/openai-provider-option.test.ts
+++ b/tests/adapters/openai/openai-provider-option.test.ts
@@ -1,3 +1,4 @@
+// Holds INV-OPENAI-01 from structure/overview.md; keep the id here if this file is split or renamed.
 import { describe, expect, test } from "bun:test";
 import { readFileSync } from "node:fs";
 import { repoPath } from "../../helpers/repo-root";
diff --git a/tests/ci-workflows/structure-ssot.test.ts b/tests/ci-workflows/structure-ssot.test.ts
new file mode 100644
index 0000000000..4783842bca
--- /dev/null
+++ b/tests/ci-workflows/structure-ssot.test.ts
@@ -0,0 +1,404 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { loadManifest, renderIndex, runStructureChecks, type Manifest } from "../../scripts/structure-ssot";
+import { repoRoot } from "../helpers/repo-root";
+
+/**
+ * structure/ is a second description of this tree, and a second description drifts. Before this gate
+ * existed nothing read the folder: four paths it named had already been moved or deleted, two docs
+ * shared the number 09, and one file had grown to 1,860 lines.
+ *
+ * The negative cases below exist because a guard nobody has driven red is a guard nobody has tested.
+ * The first revision of this file proved exactly one rule and shipped ten unproven ones; a review
+ * pass found several of those could not fail at all.
+ */
+
+const BT = "\u0060";
+const scratch: string[] = [];
+
+afterEach(() => {
+  while (scratch.length) rmSync(scratch.pop()!, { recursive: true, force: true });
+});
+
+function write(root: string, rel: string, body: string): void {
+  const p = join(root, rel);
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, body, "utf8");
+}
+
+function manifestOf(root: string): Manifest {
+  return JSON.parse(readFileSync(join(root, "structure/manifest.json"), "utf8")) as Manifest;
+}
+
+function saveManifest(root: string, manifest: Manifest): void {
+  write(root, "structure/manifest.json", JSON.stringify(manifest, null, 2) + "\n");
+  write(root, "structure/INDEX.md", renderIndex(manifest));
+}
+
+/** A synthetic tree that passes every check, so each negative case isolates one rule. */
+function scaffold(): string {
+  const root = mkdtempSync(join(tmpdir(), "ocx-structure-ssot-"));
+  scratch.push(root);
+  write(root, "src/alpha/keep.ts", "export const keep = 1;\n");
+  write(root, "tests/alpha/alpha.test.ts", "// Holds INV-A-01\nexport {};\n");
+  // The generated index names the sibling documentation roots and links the rules file, so a
+  // scaffold without them fails on the index rather than on the rule under test.
+  for (const root_dir of ["docs", "docs-site", "devlog"]) write(root, root_dir + "/.gitkeep", "");
+  write(root, "structure/AGENTS.md", "# Rules\n");
+  const manifest: Manifest = {
+    version: 2,
+    sizeBudgetLines: 600,
+    generatedPaths: [],
+    absentPaths: [],
+    tiers: [{ id: 1, name: "Foundation", purpose: "only tier" }],
+    docs: [{ path: "overview.md", tier: 1, title: "Overview", scope: "scope", documents: ["src/alpha/"] }],
+    grace: { undocumentedSourceAreas: [], unboundInvariants: [], oversizeDocs: [], staleRefs: [] },
+  };
+  write(
+    root,
+    "structure/overview.md",
+    [
+      "# Overview",
+      "",
+      "## Non-negotiable invariants",
+      "",
+      "- **INV-A-01** — alpha keeps working.",
+      "  Enforced by " + BT + "tests/alpha/alpha.test.ts" + BT + ".",
+      "",
+      "Alpha lives in " + BT + "src/alpha/keep.ts" + BT + ".",
+      "",
+      "> Decision record: [ADR-0001](decisions/ADR-0001-alpha.md)",
+      "",
+    ].join("\n"),
+  );
+  write(
+    root,
+    "structure/decisions/ADR-0001-alpha.md",
+    "# ADR-0001 — alpha\n\n- Contract owner: [overview.md](../overview.md#non-negotiable-invariants)\n",
+  );
+  saveManifest(root, manifest);
+  return root;
+}
+
+const fires = (root: string, needle: string): void => {
+  expect(runStructureChecks(root).join("\n")).toContain(needle);
+};
+
+/**
+ * The negative cases above run in a plain temp directory, where git has no index and the gate falls
+ * back to the filesystem. That leaves the index branch — the one the module argues hardest for —
+ * untested, so these cases build a real repository and drive it.
+ */
+function gitScaffold(): string {
+  const root = scaffold();
+  expect(Bun.spawnSync(["git", "init", "-q"], { cwd: root }).exitCode).toBe(0);
+  stage(root);
+  return root;
+}
+
+function stage(root: string): void {
+  expect(Bun.spawnSync(["git", "add", "-A"], { cwd: root }).exitCode).toBe(0);
+}
+
+describe("structure/ SSOT", () => {
+  test("the maintainer docs still describe this tree", () => {
+    expect(runStructureChecks(repoRoot())).toEqual([]);
+  });
+
+  test("the scaffold used by the negative cases is itself clean", () => {
+    expect(runStructureChecks(scaffold())).toEqual([]);
+  });
+
+  test("a doc on disk that the manifest does not list", () => {
+    const root = scaffold();
+    write(root, "structure/orphan.md", "# Orphan\n");
+    fires(root, "structure/orphan.md is not listed in manifest.json");
+  });
+
+  test("a manifest doc that is not on disk", () => {
+    const root = scaffold();
+    const manifest = manifestOf(root);
+    manifest.docs.push({ path: "ghost.md", tier: 1, title: "Ghost", scope: "s", documents: [] });
+    saveManifest(root, manifest);
+    fires(root, "manifest.json lists structure/ghost.md but the file is missing");
+  });
+
+  test("a filename that smuggles ordering back in", () => {
+    for (const name of ["01_overview.md", "01-overview.md", "deep/nested/doc.md"]) {
+      const root = scaffold();
+      const manifest = manifestOf(root);
+      manifest.docs[0]!.path = name;
+      write(root, "structure/" + name, "# Moved\n");
+      rmSync(join(root, "structure/overview.md"));
+      saveManifest(root, manifest);
+      fires(root, "must be kebab-case");
+    }
+  });
+
+  test("a doc over the line budget", () => {
+    const root = scaffold();
+    const manifest = manifestOf(root);
+    manifest.sizeBudgetLines = 5;
+    saveManifest(root, manifest);
+    write(root, "structure/overview.md", readFileSync(join(root, "structure/overview.md"), "utf8") + "filler\n".repeat(20));
+    fires(root, "over the 5-line budget");
+  });
+
+  test("a grace entry that outlived the split it promised", () => {
+    const root = scaffold();
+    const manifest = manifestOf(root);
+    manifest.grace.oversizeDocs = ["overview.md"];
+    saveManifest(root, manifest);
+    fires(root, "drop the grace entry");
+  });
+
+  test("a link that does not resolve", () => {
+    const root = scaffold();
+    write(root, "structure/overview.md", "# Overview\n\n[gone](missing.md)\n");
+    fires(root, "links missing.md, which does not exist");
+  });
+
+  test("a link whose anchor does not exist", () => {
+    const root = scaffold();
+    write(root, "structure/decisions/ADR-0001-alpha.md", "# ADR-0001\n\n- Owner: [overview.md](../overview.md#no-such-heading)\n");
+    fires(root, "that heading anchor does not exist");
+  });
+
+  test("a repository path the tree does not have", () => {
+    const root = scaffold();
+    const body = readFileSync(join(root, "structure/overview.md"), "utf8");
+    write(root, "structure/overview.md", body + "\nSee " + BT + "src/nowhere/thing.ts" + BT + ".\n");
+    fires(root, "which this tree does not have");
+  });
+
+  test("a decision record is not held against the present tree", () => {
+    const root = scaffold();
+    const adr = readFileSync(join(root, "structure/decisions/ADR-0001-alpha.md"), "utf8");
+    write(root, "structure/decisions/ADR-0001-alpha.md", adr + "\nIt named " + BT + "src/nowhere/thing.ts" + BT + " at the time.\n");
+    expect(runStructureChecks(root)).toEqual([]);
+  });
+
+  test("a path named only inside a fenced example is not held against the tree", () => {
+    const root = scaffold();
+    const body = readFileSync(join(root, "structure/overview.md"), "utf8");
+    const fence = BT.repeat(3);
+    write(root, "structure/overview.md", body + "\n" + fence + "text\n" + BT + "src/nowhere/thing.ts" + BT + "\n" + fence + "\n");
+    expect(runStructureChecks(root)).toEqual([]);
+  });
+
+  test("inline decision-log reasoning that crept back into a doc body", () => {
+    for (const line of ["[Decision Log]", "**[decision log]**", "- 목적과 의도: 무언가"]) {
+      const root = scaffold();
+      const body = readFileSync(join(root, "structure/overview.md"), "utf8");
+      write(root, "structure/overview.md", body + "\n" + line + "\n");
+      fires(root, "carries inline decision-log reasoning");
+    }
+  });
+
+  test("a decision record with no owner", () => {
+    const root = scaffold();
+    write(root, "structure/decisions/ADR-0002-lonely.md", "# ADR-0002\n");
+    fires(root, "ADR-0002-lonely.md is not linked from any doc");
+  });
+
+  test("a decision record claimed by two docs", () => {
+    const root = scaffold();
+    const manifest = manifestOf(root);
+    manifest.docs.push({ path: "second.md", tier: 1, title: "Second", scope: "s", documents: [] });
+    write(root, "structure/second.md", "# Second\n\n> Decision record: [ADR-0001](decisions/ADR-0001-alpha.md)\n");
+    saveManifest(root, manifest);
+    fires(root, "a record has one owner");
+  });
+
+  test("a reused decision-record number", () => {
+    const root = scaffold();
+    write(root, "structure/decisions/ADR-0001-twin.md", "# ADR-0001 twin\n");
+    fires(root, "decision record number 0001 is used twice");
+  });
+
+  test("a doc naming the same record twice still has one owner", () => {
+    const root = scaffold();
+    const body = readFileSync(join(root, "structure/overview.md"), "utf8");
+    write(root, "structure/overview.md", body + "\nAlso see [ADR-0001](decisions/ADR-0001-alpha.md).\n");
+    expect(runStructureChecks(root)).toEqual([]);
+  });
+
+  test("an invariant with no binding and no recorded reason", () => {
+    const root = scaffold();
+    write(
+      root,
+      "structure/overview.md",
+      "# Overview\n\n## Non-negotiable invariants\n\n- **INV-A-01** — alpha keeps working.\n\n> Decision record: [ADR-0001](decisions/ADR-0001-alpha.md)\n",
+    );
+    fires(root, "INV-A-01 has no Enforced by binding");
+  });
+
+  test("an invariant that is both bound and graced", () => {
+    const root = scaffold();
+    const manifest = manifestOf(root);
+    manifest.grace.unboundInvariants = [{ id: "INV-A-01", reason: "no test pins it yet" }];
+    saveManifest(root, manifest);
+    fires(root, "also listed in grace.unboundInvariants");
+  });
+
+  test("an invariant whose test is gone", () => {
+    const root = scaffold();
+    rmSync(join(root, "tests/alpha/alpha.test.ts"));
+    fires(root, "INV-A-01 names tests/alpha/alpha.test.ts, which this tree does not have");
+  });
+
+  test("a test that no longer names its invariant, including a longer id that merely starts the same", () => {
+    const silent = scaffold();
+    write(silent, "tests/alpha/alpha.test.ts", "export {};\n");
+    fires(silent, "does not name INV-A-01");
+
+    const prefixed = scaffold();
+    write(prefixed, "tests/alpha/alpha.test.ts", "// Holds INV-A-011\nexport {};\n");
+    fires(prefixed, "does not name INV-A-01");
+  });
+
+  test("a src area nobody describes", () => {
+    const root = scaffold();
+    write(root, "src/beta/new.ts", "export const beta = 1;\n");
+    fires(root, "src/beta/ is described by no doc");
+  });
+
+  test("a top-level src module nobody describes", () => {
+    const root = scaffold();
+    write(root, "src/orphan-module.ts", "export const x = 1;\n");
+    fires(root, "src/orphan-module.ts is described by no doc");
+  });
+
+  test("an area that is both described and graced", () => {
+    const root = scaffold();
+    const manifest = manifestOf(root);
+    manifest.grace.undocumentedSourceAreas = [{ path: "src/alpha/", reason: "conflicting" }];
+    saveManifest(root, manifest);
+    fires(root, "is both described and listed as undescribed");
+  });
+
+  test("a described area that does not exist", () => {
+    const root = scaffold();
+    const manifest = manifestOf(root);
+    manifest.docs[0]!.documents.push("src/imaginary/");
+    saveManifest(root, manifest);
+    fires(root, "claims src/imaginary/, which this tree does not have");
+  });
+
+  test("a described area the doc never names", () => {
+    const root = scaffold();
+    write(root, "src/beta/new.ts", "export const beta = 1;\n");
+    const manifest = manifestOf(root);
+    manifest.docs[0]!.documents.push("src/beta/");
+    saveManifest(root, manifest);
+    fires(root, "claims src/beta/ but never names it or a path in it");
+  });
+
+  test("a fragment-only link that names no heading in its own document", () => {
+    const root = scaffold();
+    const body = readFileSync(join(root, "structure/overview.md"), "utf8");
+    write(root, "structure/overview.md", body + "\nSee [that rule](#no-such-heading).\n");
+    fires(root, "links #no-such-heading, but that heading anchor does not exist");
+  });
+
+  test("overview.md missing fails instead of silencing every invariant check", () => {
+    const root = scaffold();
+    const manifest = manifestOf(root);
+    manifest.docs = [];
+    saveManifest(root, manifest);
+    rmSync(join(root, "structure/overview.md"));
+    fires(root, "structure/overview.md is missing");
+  });
+
+  test("a record named in prose but not linked is not owned", () => {
+    const root = scaffold();
+    const body = readFileSync(join(root, "structure/overview.md"), "utf8").replace(
+      "> Decision record: [ADR-0001](decisions/ADR-0001-alpha.md)",
+      "The reasoning sits in decisions/ADR-0001-alpha.md for anyone curious.",
+    );
+    write(root, "structure/overview.md", body);
+    fires(root, "ADR-0001-alpha.md is not linked from any doc");
+  });
+
+  test("a bare filename is not treated as a repository path", () => {
+    const root = scaffold();
+    const body = readFileSync(join(root, "structure/overview.md"), "utf8");
+    write(root, "structure/overview.md", body + "\nCodex reads " + BT + "models_cache.json" + BT + " at startup.\n");
+    expect(runStructureChecks(root)).toEqual([]);
+  });
+
+  test("a malformed manifest is an actionable failure, not a stack trace", () => {
+    expect(loadManifest("{not json")).toHaveProperty("error");
+    const shapeless = loadManifest(JSON.stringify({ sizeBudgetLines: 600 }));
+    expect(shapeless).toHaveProperty("error");
+    expect((shapeless as { error: string }).error).toContain("docs must be an array");
+
+    const root = scaffold();
+    write(root, "structure/manifest.json", "{not json");
+    fires(root, "is not valid JSON");
+  });
+
+  test("INDEX.md that drifted from the manifest", () => {
+    const root = scaffold();
+    write(root, "structure/INDEX.md", "# hand-edited\n");
+    fires(root, "drifted from manifest.json");
+  });
+
+  test("INDEX.md in this repository is the generated file", () => {
+    const root = repoRoot();
+    expect(readFileSync(join(root, "structure/INDEX.md"), "utf8").replace(/\r\n/g, "\n")).toBe(renderIndex(manifestOf(root)));
+  });
+
+  test("a tracked tree is judged by the index: a case variant is named, not silently accepted", () => {
+    const root = gitScaffold();
+    expect(runStructureChecks(root)).toEqual([]);
+    const body = readFileSync(join(root, "structure/overview.md"), "utf8").replace(
+      BT + "src/alpha/keep.ts" + BT,
+      BT + "src/Alpha/keep.ts" + BT,
+    );
+    write(root, "structure/overview.md", body);
+    stage(root);
+    fires(root, "but the tracked path is src/alpha/keep.ts");
+  });
+
+  test("a tracked tree rejects an untracked leftover that CI would never see", () => {
+    const root = gitScaffold();
+    const body = readFileSync(join(root, "structure/overview.md"), "utf8");
+    write(root, "src/alpha/scratch.ts", "export const scratch = 1;\n");
+    write(root, "structure/overview.md", body + "\nAlso " + BT + "src/alpha/scratch.ts" + BT + ".\n");
+    // overview.md is staged so the reference is read; scratch.ts deliberately is not.
+    expect(Bun.spawnSync(["git", "add", "structure/overview.md"], { cwd: root }).exitCode).toBe(0);
+    fires(root, "names src/alpha/scratch.ts, which this tree does not have");
+  });
+
+  test("a record shown inside a fenced example is not a second owner", () => {
+    const root = scaffold();
+    const manifest = manifestOf(root);
+    manifest.docs.push({ path: "second.md", tier: 1, title: "Second", scope: "s", documents: [] });
+    const fence = BT.repeat(3);
+    write(root, "structure/second.md", "# Second\n\n" + fence + "text\n> Decision record: [ADR-0001](decisions/ADR-0001-alpha.md)\n" + fence + "\n");
+    saveManifest(root, manifest);
+    expect(runStructureChecks(root)).toEqual([]);
+  });
+
+  test("a Decision record line pointing outside decisions/ is rejected", () => {
+    const root = scaffold();
+    write(root, "structure/elsewhere.md", "# Elsewhere\n");
+    const body = readFileSync(join(root, "structure/overview.md"), "utf8").replace(
+      "> Decision record: [ADR-0001](decisions/ADR-0001-alpha.md)",
+      "> Decision record: [ADR-0001](elsewhere.md)",
+    );
+    write(root, "structure/overview.md", body);
+    fires(root, "which is not in decisions/");
+  });
+
+  test("a malformed grace element is a failure line, not a thrown TypeError", () => {
+    const root = scaffold();
+    const manifest = manifestOf(root) as unknown as { absentPaths: unknown[] };
+    manifest.absentPaths = ["go/"];
+    write(root, "structure/manifest.json", JSON.stringify(manifest, null, 2) + "\n");
+    fires(root, "absentPaths[0].path must be a string");
+  });
+});
diff --git a/tests/claude-integration/claude-context-windows.test.ts b/tests/claude-integration/claude-context-windows.test.ts
index d411fce9aa..f22c418cb2 100644
--- a/tests/claude-integration/claude-context-windows.test.ts
+++ b/tests/claude-integration/claude-context-windows.test.ts
@@ -21,12 +21,15 @@ describe("claude context-window map (devlog 260712 B2)", () => {
   });
 
   test("registers native slugs (bare + desktop alias + legacy alias)", () => {
-    const map = buildClaudeContextWindows(["gpt-5.6-sol", "gpt-5.4"], []);
-    // Authoritative native overrides: gpt-5.6 natives follow Codex 272k, gpt-5.4 native 1M.
+    const map = buildClaudeContextWindows(["gpt-5.6-sol", "gpt-5.3-codex-spark", "gpt-5.4"], []);
+    // Authoritative native overrides: gpt-5.6 natives follow Codex 272k, spark 100k.
+    // gpt-5.4 was the only 1M native override; that window is gone, so a retired
+    // slug passed here does not register.
     expect(map["gpt-5.6-sol"]).toBe(272_000);
     expect(map[desktop3pAlias("native", "gpt-5.6-sol")]).toBe(272_000);
     expect(map["claude-ocx-native--gpt-5.6-sol"]).toBe(272_000);
-    expect(map["gpt-5.4"]).toBe(1_000_000);
+    expect(map["gpt-5.3-codex-spark"]).toBe(100_000);
+    expect(map["gpt-5.4"]).toBeUndefined();
   });
 
   test("first-wins on alias collisions (registry policy)", () => {
diff --git a/tests/claude-integration/claude-inbound-cache-stabilize.test.ts b/tests/claude-integration/claude-inbound-cache-stabilize.test.ts
new file mode 100644
index 0000000000..b11cbe3aaa
--- /dev/null
+++ b/tests/claude-integration/claude-inbound-cache-stabilize.test.ts
@@ -0,0 +1,493 @@
+import { createHash } from "node:crypto";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { loadConfig, saveConfig } from "../../src/config";
+import { handleClaudeMessages } from "../../src/server/claude-messages";
+import type { OcxConfig, OcxClaudeCodeConfig } from "../../src/types";
+import { installIsolatedCodexHome, type IsolatedCodexHome } from "../helpers/isolated-codex-home";
+import { removeTreeWithRetry } from "../helpers/remove-tree";
+import { beforeEach, afterEach, describe, expect, test } from "bun:test";
+import { stabilizeClaudeInstructionsForPromptCache } from "../../src/claude/inbound-cache-stabilize";
+import { anthropicToResponsesTranslation } from "../../src/claude/inbound";
+
+const TASKCREATE_NUDGE = [
+  "The task tools haven't been used recently. If you're working on tasks that would benefit from tracking, consider using TaskCreate to add them.",
+  "Only use these if relevant to the current work. This is just a gentle reminder - ignore if not applicable.",
+].join(" ");
+
+/** Claude Code 2.1.263+ wording (hitrate tip0847 / FREEZE-DIFF S/T4). */
+const TASKCREATE_NUDGE_CC_2_1_263 = [
+  "The task tools haven't been used recently. If you're working on tasks that would benefit from tracking progress, consider using TaskCreate to add new tasks and TaskUpdate to update task status (set to in_progress when starting, completed when done).",
+  "Also consider cleaning up the task list if it has become stale.",
+  "Only use these if relevant to the current work. This is just a gentle reminder - ignore if not applicable.",
+].join(" ");
+
+function footer(used: number): string {
+  return `<total_tokens>${used} tokens left</total_tokens>`;
+}
+
+function translate(
+  system: string,
+  options?: { user_id?: string; stabilizePromptCache?: boolean },
+) {
+  return anthropicToResponsesTranslation(
+    {
+      model: "m",
+      max_tokens: 1,
+      system,
+      messages: [{ role: "user", content: "hi" }],
+      ...(options?.user_id ? { metadata: { user_id: options.user_id } } : {}),
+    },
+    options?.stabilizePromptCache === undefined
+      ? undefined
+      : { stabilizePromptCache: options.stabilizePromptCache },
+  );
+}
+
+function translateHarness(system: string, metadata?: { user_id: string }) {
+  return anthropicToResponsesTranslation(
+    {
+      model: "m",
+      max_tokens: 1,
+      system,
+      messages: [{ role: "user", content: "hi" }],
+      ...(metadata ? { metadata } : {}),
+    },
+    { stabilizePromptCache: true },
+  );
+}
+
+function userTurns(body: { input: unknown }) {
+  return body.input as Array<Record<string, unknown>>;
+}
+
+describe("stabilizeClaudeInstructionsForPromptCache", () => {
+  test("empty input is a no-op", () => {
+    expect(stabilizeClaudeInstructionsForPromptCache("")).toEqual({
+      instructions: "",
+      dynamicNotice: null,
+    });
+  });
+
+  test("stable instructions without dynamics pass through", () => {
+    const instructions = "You are Claude Code.\n\nPrefer terse answers.";
+    expect(stabilizeClaudeInstructionsForPromptCache(instructions)).toEqual({
+      instructions,
+      dynamicNotice: null,
+    });
+  });
+
+  test("no-match whitespace is returned byte-for-byte", () => {
+    const instructions = "You are Claude Code.\n\n\nPrefer terse answers.\n";
+    expect(stabilizeClaudeInstructionsForPromptCache(instructions)).toEqual({
+      instructions,
+      dynamicNotice: null,
+    });
+  });
+
+  test("whitespace-only system without a footer is unchanged", () => {
+    const instructions = "  \n\n  ";
+    expect(stabilizeClaudeInstructionsForPromptCache(instructions)).toEqual({
+      instructions,
+      dynamicNotice: null,
+    });
+  });
+
+  test("three trailing total_tokens footers keep only the latest in the notice", () => {
+    const stable = "You are Claude Code.";
+    const first = footer(1000);
+    const second = footer(4000);
+    const third = footer(8000);
+    const result = stabilizeClaudeInstructionsForPromptCache(
+      [stable, first, second, third].join("\n\n"),
+    );
+    expect(result.instructions).toBe(stable);
+    expect(result.instructions).not.toContain("<total_tokens>");
+    expect(result.dynamicNotice).toBe(third);
+  });
+
+  test("real Claude Code 15000000 tokens left trailing footer peels", () => {
+    const stable = "You are Claude Code.";
+    const harness = footer(15_000_000);
+    const result = stabilizeClaudeInstructionsForPromptCache(`${stable}\n\n${harness}`);
+    expect(result.instructions).toBe(stable);
+    expect(result.dynamicNotice).toBe("<total_tokens>15000000 tokens left</total_tokens>");
+  });
+
+  test("bare numeric total_tokens without tokens left is not a harness footer", () => {
+    const docs = "You are Claude Code.\n\n<total_tokens>123</total_tokens>";
+    const result = stabilizeClaudeInstructionsForPromptCache(docs);
+    expect(result.instructions).toBe(docs);
+    expect(result.dynamicNotice).toBeNull();
+  });
+
+  test("mid-document total_tokens stays; only the trailing harness footer relocates", () => {
+    const result = stabilizeClaudeInstructionsForPromptCache(
+      `System.\n${footer(1)}\nMore system.\n${footer(3)}`,
+    );
+    expect(result.instructions).toBe(`System.\n${footer(1)}\nMore system.`);
+    expect(result.dynamicNotice).toBe(footer(3));
+  });
+
+  test("TaskCreate nudge is stripped from instructions and kept in the notice", () => {
+    const stable = "You are Claude Code.";
+    const result = stabilizeClaudeInstructionsForPromptCache(
+      `${stable}\n\n${TASKCREATE_NUDGE}`,
+    );
+    expect(result.instructions).toBe(stable);
+    expect(result.instructions).not.toContain("TaskCreate");
+    expect(result.dynamicNotice).toBe(TASKCREATE_NUDGE);
+  });
+
+  test("Claude Code 2.1.263 TaskCreate nudge peels and unpins older tokens-left footers", () => {
+    const stable = "You are Claude Code.";
+    const older = footer(15_000_000);
+    const mid = footer(14_980_071);
+    const latest = footer(14_997_176);
+    const result = stabilizeClaudeInstructionsForPromptCache(
+      [stable, older, mid, TASKCREATE_NUDGE_CC_2_1_263, latest].join("\n\n"),
+    );
+    expect(result.instructions).toBe(stable);
+    expect(result.instructions).not.toContain("<total_tokens>");
+    expect(result.instructions).not.toContain("TaskCreate");
+    expect(result.dynamicNotice).toBe(`${latest}\n\n${TASKCREATE_NUDGE_CC_2_1_263}`);
+  });
+
+  test("latest footer and latest nudge both surface in the notice", () => {
+    const stable = "Stay stable.";
+    const older = footer(10);
+    const latest = footer(50);
+    const result = stabilizeClaudeInstructionsForPromptCache(
+      [stable, older, TASKCREATE_NUDGE, latest].join("\n\n"),
+    );
+    expect(result.instructions).toBe(stable);
+    expect(result.dynamicNotice).toBe(`${latest}\n\n${TASKCREATE_NUDGE}`);
+  });
+
+  test("legacy and 2.1.263 nudges both leave the same stable instructions prefix", () => {
+    const stable = "Stay stable.";
+    const a = stabilizeClaudeInstructionsForPromptCache(
+      [stable, footer(1), TASKCREATE_NUDGE, footer(2)].join("\n\n"),
+    );
+    const b = stabilizeClaudeInstructionsForPromptCache(
+      [stable, footer(1), TASKCREATE_NUDGE_CC_2_1_263, footer(9)].join("\n\n"),
+    );
+    expect(a.instructions).toBe(stable);
+    expect(b.instructions).toBe(stable);
+  });
+
+  test("inline documentation of total_tokens tags stays in instructions", () => {
+    const docs = "The harness may emit a <total_tokens>123</total_tokens> footer; do not invent one.";
+    const result = stabilizeClaudeInstructionsForPromptCache(docs);
+    expect(result.instructions).toBe(docs);
+    expect(result.dynamicNotice).toBeNull();
+  });
+
+  test("TaskCreate mentioned in docs is not treated as the harness nudge", () => {
+    const docs = "The task tools haven't been used recently. You may mention TaskCreate in docs without the reminder.";
+    const result = stabilizeClaudeInstructionsForPromptCache(docs);
+    expect(result.instructions).toBe(docs);
+    expect(result.dynamicNotice).toBeNull();
+  });
+
+  test("fenced standalone total_tokens example stays byte-for-byte", () => {
+    const docs = ["You are a docs bot.", "```", footer(123), "```", ""].join("\n");
+    const result = stabilizeClaudeInstructionsForPromptCache(docs);
+    expect(result.instructions).toBe(docs);
+    expect(result.dynamicNotice).toBeNull();
+  });
+
+  test("docs plus a real trailing footer keep the docs and move only the latest footer", () => {
+    const docs = "Describe <total_tokens>0</total_tokens> in the protocol guide.";
+    const latest = footer(8000);
+    const result = stabilizeClaudeInstructionsForPromptCache(
+      [docs, footer(1), latest].join("\n\n"),
+    );
+    expect(result.instructions).toBe(docs);
+    expect(result.dynamicNotice).toBe(latest);
+  });
+
+  test("fenced example plus a trailing harness footer moves only the footer", () => {
+    const docs = ["Docs:", "```", footer(123), "```"].join("\n");
+    const latest = footer(8000);
+    const result = stabilizeClaudeInstructionsForPromptCache(`${docs}\n\n${latest}`);
+    expect(result.instructions).toBe(docs);
+    expect(result.dynamicNotice).toBe(latest);
+  });
+
+  test("unclosed fence through EOF is not a harness suffix", () => {
+    const docs = ["You are a docs bot.", "```", footer(123)].join("\n");
+    const result = stabilizeClaudeInstructionsForPromptCache(docs);
+    expect(result.instructions).toBe(docs);
+    expect(result.dynamicNotice).toBeNull();
+  });
+
+  test("a fence line with an info string does not close an open fence", () => {
+    const docs = ["```", footer(123), "```xml"].join("\n");
+    const result = stabilizeClaudeInstructionsForPromptCache(docs);
+    expect(result.instructions).toBe(docs);
+    expect(result.dynamicNotice).toBeNull();
+  });
+});
+
+describe("linear canonical notice extraction", () => {
+  for (const separator of ["\n", "\r\n", "\t", "\f", "  "]) {
+    test(`noncanonical inner separator ${JSON.stringify(separator)} is preserved`, () => {
+      const system = `System.\n\n<total_tokens>123${separator}tokens left</total_tokens>`;
+      expect(stabilizeClaudeInstructionsForPromptCache(system)).toEqual({ instructions: system, dynamicNotice: null });
+      const body = translateHarness(system).body;
+      expect(body.instructions).toBe(system);
+      expect(body.input).toHaveLength(1);
+    });
+  }
+
+  test("retains prefix trailing spaces after a successful peel and failed next candidate", () => {
+    expect(stabilizeClaudeInstructionsForPromptCache(`System.  \n\n${footer(1)}`)).toEqual({
+      instructions: "System.  ", dynamicNotice: footer(1),
+    });
+  });
+  test("CRLF separators and horizontal padding retain the canonical notice", () => {
+    expect(stabilizeClaudeInstructionsForPromptCache(`System.\r\n\r\n \t${footer(1)}\t \r\n`)).toEqual({
+      instructions: "System.", dynamicNotice: footer(1),
+    });
+  });
+  test("malformed notice before a valid suffix remains byte-for-byte", () => {
+    const prefix = `System.  \n<total_tokens>123\ntokens left</total_tokens>  `;
+    expect(stabilizeClaudeInstructionsForPromptCache(`${prefix}\n${footer(2)}`)).toEqual({
+      instructions: prefix, dynamicNotice: footer(2),
+    });
+  });
+  test("a whitespace-only trailing line and lone CR are not canonical separators", () => {
+    for (const system of [`System.\n${footer(1)}\n \n`, `System.\n${footer(1)}\r`]) {
+      expect(stabilizeClaudeInstructionsForPromptCache(system)).toEqual({ instructions: system, dynamicNotice: null });
+    }
+  });
+  test("twenty thousand notices after many fences keep only the latest without repeated prefix scans", () => {
+    const prefix = "System.\n" + ("```xml\nexample\n```\n").repeat(2_000) + "Stable.  ";
+    const notices = Array.from({ length: 20_000 }, (_, index) => footer(index));
+    expect(stabilizeClaudeInstructionsForPromptCache(`${prefix}\n\n${notices.join("\n")}`)).toEqual({
+      instructions: prefix, dynamicNotice: footer(19_999),
+    });
+  });
+});
+
+describe("anthropicToResponsesTranslation cache-stabilize wire-in", () => {
+  test("ordinary caller with the exact unfenced suffix keeps instructions and input unchanged", () => {
+    const latest = footer(15_000_000);
+    const system = ["You are Claude Code.", latest].join("\n\n");
+    const { body } = translate(system);
+    expect(body.instructions).toBe(system);
+    expect(userTurns(body)).toEqual([
+      { type: "message", role: "user", content: [{ type: "input_text", text: "hi" }] },
+    ]);
+  });
+
+  test("ordinary caller with the exact TaskCreate paragraph keeps instructions and input unchanged", () => {
+    const system = ["You are Claude Code.", TASKCREATE_NUDGE].join("\n\n");
+    const { body } = translate(system);
+    expect(body.instructions).toBe(system);
+    expect(userTurns(body)).toEqual([
+      { type: "message", role: "user", content: [{ type: "input_text", text: "hi" }] },
+    ]);
+  });
+
+  test("opted-in harness relocates the latest total_tokens footer onto a trailing input user message", () => {
+    const first = footer(1000);
+    const latest = footer(8000);
+    const { body } = translateHarness(["You are Claude Code.", first, latest].join("\n\n"));
+    expect(body.instructions).toBe("You are Claude Code.");
+    expect(String(body.instructions)).not.toContain("<total_tokens>");
+    const input = userTurns(body);
+    const last = input[input.length - 1]!;
+    expect(last).toEqual({
+      type: "message",
+      role: "user",
+      content: [{ type: "input_text", text: latest }],
+    });
+    expect(input.some(item => item.role === "user" && item !== last)).toBe(true);
+  });
+
+  test("opted-in peel does not require metadata.user_id", () => {
+    const latest = footer(14_980_071);
+    const { body } = translateHarness(["You are Claude Code.", latest].join("\n\n"));
+    expect(body.instructions).toBe("You are Claude Code.");
+    const input = userTurns(body);
+    expect(input[input.length - 1]).toEqual({
+      type: "message",
+      role: "user",
+      content: [{ type: "input_text", text: latest }],
+    });
+  });
+
+  test("fenced standalone total_tokens example is a translator no-op when opted in", () => {
+    const system = ["You are a docs bot.", "```", footer(123), "```", ""].join("\n");
+    const { body } = translateHarness(system);
+    expect(body.instructions).toBe(system);
+    expect(userTurns(body)).toEqual([
+      { type: "message", role: "user", content: [{ type: "input_text", text: "hi" }] },
+    ]);
+  });
+
+  test("open fence to EOF with a trailing total_tokens tag is not relocated", () => {
+    const system = ["You are a docs bot.", "```", footer(123)].join("\n");
+    const { body } = translateHarness(system);
+    expect(body.instructions).toBe(system);
+    expect(userTurns(body)).toEqual([
+      { type: "message", role: "user", content: [{ type: "input_text", text: "hi" }] },
+    ]);
+  });
+
+  test("real footer after a closed fence still relocates when opted in", () => {
+    const docs = ["Docs:", "```", footer(123), "```"].join("\n");
+    const latest = footer(8000);
+    const { body } = translateHarness(`${docs}\n\n${latest}`);
+    expect(body.instructions).toBe(docs);
+    const input = userTurns(body);
+    expect(input[input.length - 1]).toEqual({
+      type: "message",
+      role: "user",
+      content: [{ type: "input_text", text: latest }],
+    });
+  });
+
+  test("whitespace-only system without a footer is preserved byte-for-byte", () => {
+    const system = "  \n\n  ";
+    const { body } = translate(system);
+    expect(body.instructions).toBe(system);
+    expect(userTurns(body)).toEqual([
+      { type: "message", role: "user", content: [{ type: "input_text", text: "hi" }] },
+    ]);
+  });
+
+  test("Claude Code session prompt_cache_key is unchanged across trailing footers", () => {
+    const stable = "You are Claude Code.";
+    const keyOf = (system: string) =>
+      translateHarness(system, { user_id: "user-abc" }).body.prompt_cache_key as string;
+    const stableKey = keyOf(stable);
+    expect(stableKey).toMatch(/^[0-9a-f]{32}$/);
+    expect(keyOf([stable, footer(1000), footer(8000)].join("\n\n"))).toBe(stableKey);
+    expect(keyOf([stable, footer(99999)].join("\n\n"))).toBe(stableKey);
+  });
+
+  test("outside opt-in, Desktop prompt_cache_key hashes raw systemParts including footers", () => {
+    const stable = "You are Claude Code.";
+    const keyOf = (system: string) => translate(system).body.prompt_cache_key as string;
+    const stableKey = keyOf(stable);
+    expect(stableKey).toMatch(/^[0-9a-f]{32}$/);
+    expect(keyOf(stable)).toBe(stableKey);
+    expect(keyOf([stable, footer(8000)].join("\n\n"))).not.toBe(stableKey);
+  });
+
+  test("opted-in Desktop prompt_cache_key hashes stabilized instructions, not total_tokens footers", () => {
+    const stable = "You are Claude Code.";
+    const keyOf = (system: string) => translateHarness(system).body.prompt_cache_key as string;
+    const stableKey = keyOf(stable);
+    expect(stableKey).toMatch(/^[0-9a-f]{32}$/);
+    expect(keyOf([stable, footer(1000), footer(8000)].join("\n\n"))).toBe(stableKey);
+    expect(keyOf([stable, footer(99999)].join("\n\n"))).toBe(stableKey);
+  });
+
+  test("outside opt-in, a no-match Desktop key differs from the opted-in instructions-string key", () => {
+    const system = "You are Claude Code.\n\nPrefer terse answers.";
+    const rawKey = translate(system).body.prompt_cache_key as string;
+    const optedInKey = translateHarness(system).body.prompt_cache_key as string;
+    expect(rawKey).toMatch(/^[0-9a-f]{32}$/);
+    expect(optedInKey).toMatch(/^[0-9a-f]{32}$/);
+    expect(rawKey).not.toBe(optedInKey);
+  });
+
+});
+
+describe("Messages operator opt-in at the outbound boundary", () => {
+  const originalFetch = globalThis.fetch;
+  let isolatedHome: IsolatedCodexHome | undefined;
+  let previousHome: string | undefined;
+  let configHome: string | undefined;
+
+  beforeEach(() => {
+    previousHome = process.env.OPENCODEX_HOME;
+    isolatedHome = installIsolatedCodexHome("ocx-prefix-contract-");
+    configHome = mkdtempSync(join(tmpdir(), "ocx-prefix-config-"));
+    process.env.OPENCODEX_HOME = configHome;
+  });
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    isolatedHome?.restore();
+    if (previousHome === undefined) delete process.env.OPENCODEX_HOME;
+    else process.env.OPENCODEX_HOME = previousHome;
+    if (configHome) removeTreeWithRetry(configHome);
+  });
+
+  async function outbound(system: string, enabled?: boolean) {
+    const captured: Array<Record<string, unknown>> = [];
+    globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+      expect(String(input)).toBe("https://prefix.example/v1/responses");
+      captured.push(JSON.parse(String(init?.body)) as Record<string, unknown>);
+      return Response.json({ id: "resp_prefix", object: "response", status: "completed",
+        output: [{ type: "message", role: "assistant", content: [{ type: "output_text", text: "ok" }] }],
+        usage: { input_tokens: 2, output_tokens: 1, total_tokens: 3 } });
+    }) as typeof fetch;
+    const config = {
+      providers: { prefix: { adapter: "openai-responses", authMode: "key", baseUrl: "https://prefix.example/v1", apiKey: "test-key", models: ["m"] } },
+      ...(enabled === undefined ? {} : { claudeCode: { stabilizePromptCache: enabled } }),
+    } as OcxConfig;
+    const response = await handleClaudeMessages(new Request("http://localhost/v1/messages", {
+      method: "POST", headers: { "content-type": "application/json" },
+      body: JSON.stringify({ model: "prefix/m", max_tokens: 32, system,
+        messages: [{ role: "user", content: "hi" }], stream: false }),
+    }), config, { model: "", provider: "" });
+    await response.text();
+    expect(response.status).toBe(200);
+    expect(captured).toHaveLength(1);
+    return captured[0]!;
+  }
+
+  for (const enabled of [undefined, false]) {
+    test(`ordinary HTTP caller preserves exact footer with setting ${enabled}`, async () => {
+      const system = `System.\n\n${footer(15_000_000)}`;
+      const wire = await outbound(system, enabled);
+      expect(wire.instructions).toBe(system);
+      expect(wire.input).toEqual([{ type: "message", role: "user", content: [{ type: "input_text", text: "hi" }] }]);
+      // Independent historical key vector: canonical JSON keys in sorted order, raw system array.
+      const expectedKey = createHash("sha256").update(JSON.stringify({ model: "prefix/m", system: [system], tools: [], version: 2 })).digest("hex").slice(0, 32);
+      expect(wire.prompt_cache_key).toBe(expectedKey);
+    });
+  }
+
+  for (const notice of [footer(15_000_000), TASKCREATE_NUDGE, TASKCREATE_NUDGE_CC_2_1_263]) {
+    test(`explicit HTTP opt-in relocates supported notice ${notice.slice(0, 35)}`, async () => {
+      const wire = await outbound(`System.\n\n${notice}`, true);
+      expect(wire.instructions).toBe("System.");
+      expect(wire.input).toEqual([
+        { type: "message", role: "user", content: [{ type: "input_text", text: "hi" }] },
+        { type: "message", role: "user", content: [{ type: "input_text", text: notice }] },
+      ]);
+    });
+  }
+
+  test("opted-in HTTP caller preserves an open fenced example", async () => {
+    const system = `Docs:\n\x60\x60\x60xml\n${footer(1)}`;
+    const wire = await outbound(system, true);
+    expect(wire.instructions).toBe(system);
+    expect(wire.input).toHaveLength(1);
+  });
+
+  test("explicit setting survives actual config save/load without enabling other configs", () => {
+    const config = loadConfig();
+    config.claudeCode = { ...config.claudeCode, stabilizePromptCache: true };
+    saveConfig(config);
+    expect(loadConfig().claudeCode?.stabilizePromptCache).toBe(true);
+    config.claudeCode.stabilizePromptCache = false;
+    saveConfig(config);
+    expect(loadConfig().claudeCode?.stabilizePromptCache).toBe(false);
+  });
+
+  test("malformed truthy configuration never activates relocation", () => {
+    const system = `System.\n\n${footer(1)}`;
+    const config = JSON.parse('{"stabilizePromptCache":"true"}') as OcxClaudeCodeConfig;
+    const { body } = anthropicToResponsesTranslation({ model: "m", system, messages: [{ role: "user", content: "hi" }] }, config);
+    expect(body.instructions).toBe(system);
+    expect(body.input).toHaveLength(1);
+  });
+});
diff --git a/tests/claude-integration/claude-inbound.test.ts b/tests/claude-integration/claude-inbound.test.ts
index a89f9c928b..3db1a4a627 100644
--- a/tests/claude-integration/claude-inbound.test.ts
+++ b/tests/claude-integration/claude-inbound.test.ts
@@ -739,7 +739,7 @@ describe("#3922 translated tools carry the source strict intent", () => {
     additionalProperties: false,
   };
   const request = (tool: Record<string, unknown>) => ({
-    model: "openai/gpt-5.4",
+    model: "openai/gpt-5.6-luna",
     max_tokens: 32,
     messages: [{ role: "user", content: "Run a local agent." }],
     tools: [tool],
@@ -795,7 +795,7 @@ describe("#3922 translated tools carry the source strict intent", () => {
       [agent({ strict: false }), false],
     ] as const) {
       const expectedSchema = structuredClone(tool.input_schema);
-      const parsed = parseRequest({ ...anthropicToResponsesBody(request(tool)), model: "gpt-5.4" });
+      const parsed = parseRequest({ ...anthropicToResponsesBody(request(tool)), model: "gpt-5.6-luna" });
       expect(parsed.context.tools?.[0]?.strict).toBe(expected);
 
       const outbound = await adapter.buildRequest(parsed);
diff --git a/tests/claude-integration/claude-management-api.test.ts b/tests/claude-integration/claude-management-api.test.ts
index fa99f3c14f..60bc012fa2 100644
--- a/tests/claude-integration/claude-management-api.test.ts
+++ b/tests/claude-integration/claude-management-api.test.ts
@@ -895,3 +895,64 @@ test("Claude Desktop PUT retains but cannot move an unavailable route", async ()
     await server.stop(true);
   }
 });
+
+test("Claude Desktop PUT allows deleting an unavailable route, but rejects modifying or adding one", async () => {
+  const seeded = loadConfig();
+  seeded.claudeCode = {
+    desktopProfile: {
+      version: 1,
+      assignments: {
+        "missing/old-model": { family: "opus", alias: "claude-opus-4-8-20260101" },
+      },
+      defaults: { opus: "missing/old-model", fable: null, sonnet: null, haiku: null },
+    },
+  };
+  saveConfig(seeded);
+  const server = startServer(0);
+  try {
+    const state = await fetch(new URL("/api/claude-desktop", server.url)).then(r => r.json()) as Record<string, any>;
+    expect(state.models.find((model: { route: string }) => model.route === "missing/old-model")?.available).toBe(false);
+
+    // Modifying an existing unavailable assignment (e.g. changing alias) is rejected with 400.
+    const modifyEdit = structuredClone(state.profile);
+    modifyEdit.assignments["missing/old-model"].alias = "claude-opus-4-8-20260202";
+    const putModify = await fetch(new URL("/api/claude-desktop", server.url), {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ profile: modifyEdit }),
+    });
+    expect(putModify.status).toBe(400);
+    expect((await putModify.json() as { error: string }).error).toContain("현재 사용할 수 없는 모델은 옮길 수 없습니다: missing/old-model");
+    expect(loadConfig().claudeCode?.desktopProfile?.assignments["missing/old-model"]?.alias).toBe("claude-opus-4-8-20260101");
+
+    // Deleting an existing unavailable assignment succeeds with 200.
+    const deleteEdit = structuredClone(state.profile);
+    delete deleteEdit.assignments["missing/old-model"];
+    deleteEdit.defaults.opus = Object.keys(deleteEdit.assignments).filter(route => deleteEdit.assignments[route].family === "opus").sort()[0] ?? null;
+
+    const putDelete = await fetch(new URL("/api/claude-desktop", server.url), {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ profile: deleteEdit }),
+    });
+    expect(putDelete.status).toBe(200);
+    const deleteResult = await putDelete.json() as Record<string, any>;
+    expect(deleteResult.models.some((model: { route: string }) => model.route === "missing/old-model")).toBe(false);
+    expect(deleteResult.profile.assignments["missing/old-model"]).toBeUndefined();
+    expect(loadConfig().claudeCode?.desktopProfile?.assignments["missing/old-model"]).toBeUndefined();
+
+    // Adding a newly unavailable assignment is rejected with 400.
+    const addEdit = structuredClone(deleteResult.profile);
+    addEdit.assignments["missing/new-model"] = { family: "fable", alias: "claude-opus-4-8-20260102" };
+    addEdit.defaults.fable = "missing/new-model";
+    const putAdd = await fetch(new URL("/api/claude-desktop", server.url), {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ profile: addEdit }),
+    });
+    expect(putAdd.status).toBe(400);
+    expect((await putAdd.json() as { error: string }).error).toContain("현재 사용할 수 없는 모델은 추가할 수 없습니다: missing/new-model");
+  } finally {
+    await server.stop(true);
+  }
+});
diff --git a/tests/claude-integration/claude-model-info.test.ts b/tests/claude-integration/claude-model-info.test.ts
index 34a49be617..b8648a0a68 100644
--- a/tests/claude-integration/claude-model-info.test.ts
+++ b/tests/claude-integration/claude-model-info.test.ts
@@ -61,7 +61,7 @@ describe("anthropic-flavor ModelInfo discovery entries (devlog 130 B4b)", () =>
   });
 
   test("native effective ladder only advertises clamp-identity rungs (audit R4#1)", () => {
-    for (const slug of ["gpt-5.5", "gpt-5.4", "gpt-5.6-sol"]) {
+    for (const slug of ["gpt-5.5", "gpt-5.3-codex-spark", "gpt-5.6-sol"]) {
       for (const rung of nativeEffectiveLadder(slug)) {
         expect(rung).not.toBe("ultra");
         const clamped = nativeEffortClamp(slug, rung);
@@ -96,13 +96,11 @@ describe("anthropic-flavor ModelInfo discovery entries (devlog 130 B4b)", () =>
     expect(String(lunaBase)).toBeDefined();
   });
 
-  test("[1m] variants cover 1M NATIVES too (audit R1#1) — and skip sub-1M natives", () => {
-    // gpt-5.4 is the only authoritative 1M native. gpt-5.6-sol advertises 922k — a cap held
-    // under its measured ceiling — so it stays out, and so does gpt-5.5 at 272k.
-    const infos = buildAnthropicModelInfos(["gpt-5.4", "gpt-5.6-sol", "gpt-5.5"], []);
-    const variants = infos.filter(i => i.id.endsWith("[1m]"));
-    expect(variants).toHaveLength(1);
-    expect(variants[0]!.display_name.includes("gpt-5.4")).toBe(true);
+  test("[1m] variants skip natives — none have a >=1M window after gpt-5.4 retirement", () => {
+    // gpt-5.4 was the only authoritative 1M native; that override is gone. gpt-5.6-sol
+    // advertises 922k under its measured ceiling, gpt-5.5 is 272k, spark is 100k.
+    const infos = buildAnthropicModelInfos(["gpt-5.6-sol", "gpt-5.5", "gpt-5.3-codex-spark"], []);
+    expect(infos.filter(i => i.id.endsWith("[1m]"))).toHaveLength(0);
   });
 
   test("native OpenAI rows carry max_input_tokens so Claude Code skips the 200k fallback (#1218)", () => {
@@ -146,17 +144,15 @@ describe("anthropic-flavor ModelInfo discovery entries (devlog 130 B4b)", () =>
 
   test("no [1m] rows for sub-1M models, even with auto-context enabled (#854 contract)", () => {
     const auto = { enabled: true, compactWindow: 350_000 };
-    const infos = buildAnthropicModelInfos(["gpt-5.4", "gpt-5.5"], [
+    const infos = buildAnthropicModelInfos(["gpt-5.5", "gpt-5.6-sol"], [
       { provider: "mock", id: "small-model", contextWindow: 128_000 },
       { provider: "mock", id: "mid-model", contextWindow: 300_000 }, // < compact window: unsafe, no row
     ], auto);
     const variants = infos.filter(i => i.id.endsWith("[1m]"));
-    // The [1m] marker makes Claude Code account 1e6 tokens: only the
-    // authoritative 1M model may carry it — never the 272K gpt-5.5 route.
-    expect(variants).toHaveLength(1);
-    expect(variants[0]!.display_name.includes("gpt-5.4")).toBe(true);
-    expect(variants[0]!.display_name.endsWith("· 1M")).toBe(true);
-    expect(variants[0]!.max_input_tokens).toBe(1_000_000);
+    // The [1m] marker makes Claude Code account 1e6 tokens. No surviving native
+    // is >=1M, and auto-context must not mint the marker for 272k natives or
+    // sub-compact-window mocks (#854).
+    expect(variants).toHaveLength(0);
   });
 
   test("auto-context never widens anthropic passthrough rows (audit 021 #3)", () => {
diff --git a/tests/claude-integration/claude-models-discovery.test.ts b/tests/claude-integration/claude-models-discovery.test.ts
index 608a1ffa80..5c29fd7ef0 100644
--- a/tests/claude-integration/claude-models-discovery.test.ts
+++ b/tests/claude-integration/claude-models-discovery.test.ts
@@ -325,6 +325,10 @@ test("Codex discovery restores account rows for supported natives hidden on disk
   expect(listCatalogNativeSlugs()).toContain("gpt-5.5");
   expect(listCatalogNativeSlugs()).not.toContain("gpt-99-internal");
   expect(listCatalogNativeSlugs()).not.toContain("provider/gpt-5.5");
+  // Retired slugs may still sit in a custom catalog or the upstream pin; membership
+  // does not follow either of those.
+  expect(listCatalogNativeSlugs()).not.toContain("gpt-5.4");
+  expect(listCatalogNativeSlugs()).not.toContain("gpt-5.4-mini");
   expect(visibleNativeSlugs(config)).toContain("gpt-5.5");
   expect(visibleNativeSlugs({ ...config, disabledModels: ["gpt-5.5"] })).not.toContain("gpt-5.5");
 
@@ -332,6 +336,7 @@ test("Codex discovery restores account rows for supported natives hidden on disk
   try {
     const plain = await fetch(new URL("/v1/models", server.url))
       .then(response => response.json()) as { data: Array<{ id: string }> };
+    expect(plain.data.some(model => model.id === "gpt-5.4")).toBe(false);
     expect(plain.data.some(model => model.id === "gpt-5.4-mini")).toBe(false);
 
     const catalog = await fetch(new URL("/v1/models?client_version=1.0.0", server.url))
@@ -344,10 +349,11 @@ test("Codex discovery restores account rows for supported natives hidden on disk
   }
 
   config.codexAccountNamespaces = { team: "@main" };
-  config.disabledModels = ["gpt-5.4"];
+  config.disabledModels = ["gpt-5.6-sol"];
   saveConfig(config);
   resetCatalogRuntimeStateForTests();
   expect(visibleNativeSlugs(config)).toContain("gpt-5.5");
+  expect(visibleNativeSlugs(config)).not.toContain("gpt-5.6-sol");
   expect(visibleNativeSlugs(config)).not.toContain("gpt-5.4");
   server = startServer(0);
   try {
@@ -362,10 +368,10 @@ test("Codex discovery restores account rows for supported natives hidden on disk
     expect(plain.data.some(model => model.id === "team/gpt-5.4")).toBe(false);
     // Activating account selectors makes both bare and qualified discovery mirror the complete
     // enabled supported set, even when a partial custom catalog omitted this native.
-    expect(plain.data.find(model => model.id === "gpt-5.4-mini")?.reasoning_efforts)
+    expect(plain.data.find(model => model.id === "gpt-5.6-luna")?.reasoning_efforts)
       .toBeArray();
-    expect(plain.data.find(model => model.id === "team/gpt-5.4-mini")?.reasoning_efforts)
-      .toEqual(plain.data.find(model => model.id === "gpt-5.4-mini")?.reasoning_efforts);
+    expect(plain.data.find(model => model.id === "team/gpt-5.6-luna")?.reasoning_efforts)
+      .toEqual(plain.data.find(model => model.id === "gpt-5.6-luna")?.reasoning_efforts);
 
     const catalog = await fetch(new URL("/v1/models?client_version=1.0.0", server.url))
       .then(response => response.json()) as {
@@ -380,9 +386,11 @@ test("Codex discovery restores account rows for supported natives hidden on disk
       visibility: "list",
       opencodex_catalog_kind: "account-selector-v1",
     });
-    expect(catalog.models.find(model => model.slug === "team/gpt-5.4")?.visibility)
+    expect(catalog.models.find(model => model.slug === "team/gpt-5.6-sol")?.visibility)
       .toBe("hide");
-    expect(catalog.models.find(model => model.slug === "team/gpt-5.4-mini")?.visibility)
+    expect(catalog.models.find(model => model.slug === "team/gpt-5.4")?.visibility)
+      .toBeUndefined();
+    expect(catalog.models.find(model => model.slug === "team/gpt-5.6-luna")?.visibility)
       .toBe("list");
   } finally {
     await server.stop(true);
diff --git a/tests/claude-integration/claude-native-affinity.test.ts b/tests/claude-integration/claude-native-affinity.test.ts
new file mode 100644
index 0000000000..d3cb071e5b
--- /dev/null
+++ b/tests/claude-integration/claude-native-affinity.test.ts
@@ -0,0 +1,150 @@
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { clearComboSelectionState, clearComboTargetCooldowns } from "../../src/combos";
+import { handleClaudeMessages } from "../../src/server/claude-messages";
+import { handleResponses } from "../../src/server/responses/core";
+import { handleResponsesWithPolicyFallback, rankPolicyFallbackCandidates } from "../../src/server/responses/policy-fallback";
+import { tryAdmitTurn } from "../../src/server/lifecycle";
+import { providerConfigSeed } from "../../src/providers/derive";
+import { getProviderRegistryEntry } from "../../src/providers/registry";
+import type { OcxConfig } from "../../src/types";
+import { fakeChatGptJwt } from "../helpers/fake-chatgpt-jwt";
+import { installIsolatedCodexHome, type IsolatedCodexHome } from "../helpers/isolated-codex-home";
+import { removeTreeWithRetry } from "../helpers/remove-tree";
+
+const originalFetch = globalThis.fetch;
+const metadata = "user_test_account__session_conversation-native";
+// Independent SHA-256/UUID fixture vectors; no production helper builds the oracle.
+const key = "9745d86cd579894abd0ef69a5214cf96";
+const expectedSession = "9745d86c-d579-494a-8d0e-f69a5214cf96";
+let isolated: IsolatedCodexHome;
+let home: string;
+let previousHome: string | undefined;
+let token: string;
+
+beforeEach(() => {
+  previousHome = process.env.OPENCODEX_HOME;
+  home = mkdtempSync(join(tmpdir(), "ocx-native-affinity-"));
+  process.env.OPENCODEX_HOME = home;
+  isolated = installIsolatedCodexHome("ocx-native-affinity-codex-");
+  token = fakeChatGptJwt({ exp: Math.floor(Date.now() / 1000) + 86400, chatgpt_account_id: "fixture-native-main" });
+  writeFileSync(join(isolated.path, "auth.json"), JSON.stringify({ tokens: { access_token: token, account_id: "fixture-native-main" } }));
+  clearComboSelectionState();
+  clearComboTargetCooldowns();
+});
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+  clearComboSelectionState();
+  clearComboTargetCooldowns();
+  isolated.restore();
+  if (previousHome === undefined) delete process.env.OPENCODEX_HOME;
+  else process.env.OPENCODEX_HOME = previousHome;
+  removeTreeWithRetry(home);
+});
+
+function config(): OcxConfig {
+  return { openaiProviderTierVersion: 2, providers: {
+    openai: { adapter: "openai-responses", authMode: "forward", codexAccountMode: "direct", baseUrl: "https://chatgpt.com/backend-api/codex", models: ["gpt-5.6-luna"] },
+    go: { ...providerConfigSeed(getProviderRegistryEntry("opencode-go")!), apiKey: "test-go-key" },
+    other: { adapter: "openai-responses", authMode: "key", baseUrl: "https://affinity.example/v1", apiKey: "test-other-key", models: ["m"] },
+  } } as OcxConfig;
+}
+function completed(): Response {
+  return Response.json({ id: "resp_affinity", object: "response", status: "completed", output: [],
+    usage: { input_tokens: 1, output_tokens: 0, total_tokens: 1 } });
+}
+
+describe("Claude final canonical native affinity after a Go preliminary pick", () => {
+  for (const strategy of ["random", "failover"] as const) {
+    for (const explicit of [undefined, "session_id", "session-id", "thread-id"] as const) {
+      test(`${strategy} preserves ${explicit ?? "metadata native identity"}`, async () => {
+        const cfg = config();
+        cfg.combos = { reverse: { strategy, targets: [
+          { provider: "go", model: "glm-5.2" }, { provider: "openai", model: "gpt-5.6-luna" },
+        ] } };
+        const seen: Array<{ url: string; headers: Headers; body: Record<string, unknown> }> = [];
+        globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+          const url = String(input);
+          seen.push({ url, headers: new Headers(init?.headers), body: JSON.parse(String(init?.body)) });
+          return url.startsWith("https://opencode.ai/")
+            ? Response.json({ error: { message: "model retired", code: "model_not_found" } }, { status: 404 }) : completed();
+        }) as typeof fetch;
+        const entropy = spyOn(Math, "random").mockReturnValue(0.9).mockReturnValueOnce(0);
+        const lease = tryAdmitTurn();
+        expect(lease).not.toBeNull();
+        try {
+          const req = new Request("http://localhost/v1/messages", { method: "POST",
+            headers: { "content-type": "application/json", ...(explicit ? { [explicit]: "caller-conversation" } : {}) },
+            body: JSON.stringify({ model: "combo/reverse", max_tokens: 32, stream: false,
+              metadata: { user_id: metadata }, messages: [{ role: "user", content: "ping" }] }) });
+          const response = await handleClaudeMessages(req, cfg, { model: "", provider: "" },
+            { requestId: `affinity-${strategy}-${explicit ?? "metadata"}`, start: Date.now(), turnAdmissionLease: lease! });
+          await response.text();
+          expect(response.status).toBe(200);
+          const wire = seen.at(-1)!;
+          expect(wire.url).toBe("https://chatgpt.com/backend-api/codex/responses");
+          expect(wire.headers.get("session_id")).toBe(explicit ? explicit === "session_id" ? "caller-conversation" : null : expectedSession);
+          if (explicit) expect(wire.headers.get(explicit)).toBe("caller-conversation");
+          expect(wire.headers.has("x-opencode-session")).toBe(false);
+          expect(wire.body.prompt_cache_key).toBe(key);
+          expect(req.headers.get("session_id")).toBe(explicit === "session_id" ? "caller-conversation" : null);
+        } finally { entropy.mockRestore(); lease?.release(); }
+      });
+    }
+  }
+
+  test("shared-system cache key never becomes native session identity", async () => {
+    let captured: Headers | undefined;
+    globalThis.fetch = (async (_input: RequestInfo | URL, init?: RequestInit) => {
+      captured = new Headers(init?.headers); return completed();
+    }) as typeof fetch;
+    const lease = tryAdmitTurn();
+    try {
+      const response = await handleClaudeMessages(new Request("http://localhost/v1/messages", {
+        method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({
+          model: "openai/gpt-5.6-luna", system: "Shared prefix", messages: [{ role: "user", content: "ping" }], max_tokens: 32,
+        }),
+      }), config(), { model: "", provider: "" }, { requestId: "shared-prefix", start: Date.now(), turnAdmissionLease: lease! });
+      await response.text();
+      expect(response.status).toBe(200);
+      expect(captured?.has("session_id")).toBe(false);
+    } finally { lease?.release(); }
+  });
+
+  test("native failure leaves policy-hop request headers free of synthesized identity", async () => {
+    const cfg = config();
+    const trace = { version: 1, decisionId: "native-hop", createdAt: Date.now(), requestedModel: "openai/gpt-5.6-luna",
+      routeKind: "policy", profile: { id: "native-hop", revision: "1" }, requirements: [],
+      candidates: [
+        { provider: "openai", model: "gpt-5.6-luna", eligible: true, exclusions: [], score: { total: 2 } },
+        { provider: "other", model: "m", eligible: true, exclusions: [], score: { total: 1 } },
+      ], selected: { candidateIndex: 0, provider: "openai", model: "gpt-5.6-luna", reason: "fixture" },
+    } as unknown as Parameters<typeof rankPolicyFallbackCandidates>[0];
+    const requests: Request[] = [];
+    const wires: Headers[] = [];
+    globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+      wires.push(new Headers(init?.headers));
+      return String(input).startsWith("https://chatgpt.com/")
+        ? Response.json({ error: { message: "model retired", code: "model_not_found" } }, { status: 404 }) : completed();
+    }) as typeof fetch;
+    const req = new Request("http://localhost/v1/responses", { method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${token}`, "chatgpt-account-id": "fixture-native-main" },
+      body: JSON.stringify({ model: "openai/gpt-5.6-luna", input: "ping", stream: false }) });
+    const runCore: NonNullable<Parameters<typeof handleResponsesWithPolicyFallback>[4]>["runCore"] = async (request, current, log, options) => {
+      requests.push(request);
+      const response = await handleResponses(request, current, log, options);
+      if (requests.length === 1) log.routeDecision = trace;
+      return response;
+    };
+    const response = await handleResponsesWithPolicyFallback(req, cfg, { model: "", provider: "" },
+      { claudeNativeSessionId: expectedSession }, { runCore });
+    await response.text();
+    expect(response.status).toBe(200);
+    expect(requests).toHaveLength(2);
+    expect(wires[0]?.get("session_id")).toBe(expectedSession);
+    expect(wires.at(-1)?.has("session_id")).toBe(false);
+    expect(requests.every(request => !request.headers.has("session_id"))).toBe(true);
+  });
+});
diff --git a/tests/cli/cli-account-pool-verbs.test.ts b/tests/cli/cli-account-pool-verbs.test.ts
index 04be2e4fa6..afab5fea2f 100644
--- a/tests/cli/cli-account-pool-verbs.test.ts
+++ b/tests/cli/cli-account-pool-verbs.test.ts
@@ -168,7 +168,7 @@ describe("ocx account strategy / sticky", () => {
     const out = capture();
     try {
       await cmdStrategy(["openai"], deps(() => ({
-        json: { accountPoolStrategy: "round-robin", accountPoolStickyLimit: 4 },
+        json: { strategy: "round-robin", stickyLimit: 4 },
       }), calls));
     } finally { out.restore(); }
     expect(calls.every(call => call.method === "GET")).toBe(true);
@@ -180,14 +180,16 @@ describe("ocx account strategy / sticky", () => {
     const stickyCalls: Captured[] = [];
     const out = capture();
     try {
-      await cmdStrategy(["openai", "fill-first"], deps(() => ({ json: { accountPoolStrategy: "fill-first", accountPoolStickyLimit: 1 } }), strategyCalls));
-      await cmdSticky(["openai", "7"], deps(() => ({ json: { accountPoolStrategy: "fill-first", accountPoolStickyLimit: 7 } }), stickyCalls));
+      await cmdStrategy(["openai", "fill-first"], deps(() => ({ json: { strategy: "fill-first", stickyLimit: 1 } }), strategyCalls));
+      await cmdSticky(["openai", "7"], deps(() => ({ json: { strategy: "fill-first", stickyLimit: 7 } }), stickyCalls));
     } finally { out.restore(); }
-    expect(strategyCalls[0]?.path).toBe("/api/codex-auth/pool-strategy");
-    expect(stickyCalls[0]?.path).toBe("/api/codex-auth/pool-strategy");
-    expect(strategyCalls[0]?.body).toEqual({ strategy: "fill-first" });
+    expect(strategyCalls[0]?.path).toBe("/api/pool/settings");
+    expect(stickyCalls[0]?.path).toBe("/api/pool/settings");
+    // Every kind now carries `provider`, including Codex. The bare-field body was the other
+    // half of the asymmetry the unified route removes.
+    expect(strategyCalls[0]?.body).toEqual({ provider: "openai", strategy: "fill-first" });
     // Sent as a number so the server sees the type it validates.
-    expect(stickyCalls[0]?.body).toEqual({ stickyLimit: 7 });
+    expect(stickyCalls[0]?.body).toEqual({ provider: "openai", stickyLimit: 7 });
   });
 
   test("the APPLIED value is echoed, not the requested one", async () => {
@@ -195,7 +197,7 @@ describe("ocx account strategy / sticky", () => {
     // should see.
     const out = capture();
     try {
-      await cmdSticky(["openai", "9"], deps(() => ({ json: { accountPoolStrategy: "quota", accountPoolStickyLimit: 3 } }), []));
+      await cmdSticky(["openai", "9"], deps(() => ({ json: { strategy: "quota", stickyLimit: 3 } }), []));
     } finally { out.restore(); }
     expect(out.lines.join("\n")).toContain("3");
     expect(out.lines.join("\n")).not.toContain("9");
@@ -257,7 +259,7 @@ describe("ocx account strategy / sticky on the anthropic pool", () => {
       await cmdStrategy(["anthropic"], anthropicDeps(() => ({ json: { strategy: "round-robin", stickyLimit: 5 } }), calls));
     } finally { out.restore(); }
     expect(calls[0]?.method).toBe("GET");
-    expect(calls[0]?.path).toBe("/api/oauth/accounts/pool?provider=anthropic");
+    expect(calls[0]?.path).toBe("/api/pool/settings?provider=anthropic");
     // Unprefixed keys: this route spells the same settings without `accountPool`.
     expect(out.lines.join("\n")).toContain("round-robin");
   });
@@ -269,7 +271,7 @@ describe("ocx account strategy / sticky on the anthropic pool", () => {
       await cmdSticky(["anthropic", "6"], anthropicDeps(() => ({ json: { ok: true, strategy: "quota", stickyLimit: 6 } }), calls));
     } finally { out.restore(); }
     expect(calls[0]?.method).toBe("PUT");
-    expect(calls[0]?.path).toBe("/api/oauth/accounts/pool");
+    expect(calls[0]?.path).toBe("/api/pool/settings");
     // Omitting `provider` here earns a 400 from the real route, so it is asserted exactly.
     expect(calls[0]?.body).toEqual({ provider: "anthropic", stickyLimit: 6 });
     expect(out.lines.join("\n")).toContain("6");
@@ -286,7 +288,7 @@ describe("ocx account strategy / sticky on the anthropic pool", () => {
   test("the codex pool keeps its own prefixed keys mapped onto the same neutral output", async () => {
     const out = capture();
     try {
-      await cmdStrategy(["openai", "--json"], deps(() => ({ json: { accountPoolStrategy: "quota", accountPoolStickyLimit: 1 } }), []));
+      await cmdStrategy(["openai", "--json"], deps(() => ({ json: { strategy: "quota", stickyLimit: 1 } }), []));
     } finally { out.restore(); }
     expect(JSON.parse(out.lines.join("\n"))).toMatchObject({ provider: "openai", strategy: "quota", stickyLimit: 1 });
   });
@@ -342,7 +344,7 @@ describe("generic OAuth pool-settings contract (#695)", () => {
     try {
       await cmdStrategy(["google-antigravity", "round-robin"], genericDeps(() => ({ json: { ok: true, strategy: "round-robin", stickyLimit: null } }), calls));
     } finally { out.restore(); }
-    expect(calls[0]).toMatchObject({ method: "PUT", path: "/api/oauth/accounts/pool", body: { provider: "google-antigravity", strategy: "round-robin" } });
+    expect(calls[0]).toMatchObject({ method: "PUT", path: "/api/pool/settings", body: { provider: "google-antigravity", strategy: "round-robin" } });
   });
 
   test("auto-switch on a generic provider writes autoSwitchThreshold through the pool route", async () => {
@@ -391,8 +393,7 @@ describe("generic OAuth pool-settings contract (#695)", () => {
 
   test("generic missing or malformed capability stays unknown rather than enabled", async () => {
     for (const json of [null, [], {}, { enabled: "true", autoSwitchThreshold: "90", inert: "false" },
-      { enabled: true, autoSwitchThreshold: 90 }, { enabled: true, autoSwitchThreshold: 101, inert: false },
-      { enabled: true, autoSwitchThreshold: 90, inert: false }]) {
+      { enabled: true, autoSwitchThreshold: 90 }, { enabled: true, autoSwitchThreshold: 101, inert: false }]) {
       const out = capture();
       try {
         expect(await cmdAutoSwitch(["google-antigravity", "status", "--json"], genericDeps(() => ({ json }), []))).toBe(0);
@@ -403,6 +404,39 @@ describe("generic OAuth pool-settings contract (#695)", () => {
     }
   });
 
+  test("a generic pool that reports inert false is live, not unknown", async () => {
+    // `inert: false` used to be lumped in with the malformed bodies above, which made the CLI
+    // render a threshold the kernel is actually applying as "threshold support is unknown" --
+    // the opposite of the truth. The three states are distinct: true is stored-but-not-applied,
+    // false is applied, absent is a server that does not speak the field at all.
+    const out = capture();
+    try {
+      expect(await cmdAutoSwitch(
+        ["google-antigravity", "status", "--json"],
+        genericDeps(() => ({ json: { enabled: true, autoSwitchThreshold: 90, inert: false } }), []),
+      )).toBe(0);
+    } finally { out.restore(); }
+    expect(JSON.parse(out.lines.join("\n"))).toEqual({
+      provider: "google-antigravity", autoSwitchThreshold: 90, enabled: true, poolEnabled: true, inert: false,
+    });
+  });
+
+  test("a live generic pool with no stored threshold reports off, not on", async () => {
+    // `inert: false` alone is not enablement: the kernel is consuming settings, but there is
+    // no threshold to consume. Reporting "on" here would invent a value nobody set.
+    const out = capture();
+    try {
+      expect(await cmdAutoSwitch(
+        ["google-antigravity", "status", "--json"],
+        genericDeps(() => ({ json: { enabled: true, inert: false } }), []),
+      )).toBe(0);
+    } finally { out.restore(); }
+    const result = JSON.parse(out.lines.join("\n"));
+    expect(result.enabled).toBe(false);
+    expect(result.inert).toBe(false);
+    expect(result.autoSwitchThreshold).toBeNull();
+  });
+
   test("a successful generic write with a null body reports unknown settings", async () => {
     const calls: Captured[] = [];
     const out = capture();
diff --git a/tests/cli/cli-capabilities.test.ts b/tests/cli/cli-capabilities.test.ts
index 9a3191804a..4210a0d595 100644
--- a/tests/cli/cli-capabilities.test.ts
+++ b/tests/cli/cli-capabilities.test.ts
@@ -310,7 +310,6 @@ const UNDECLARED_ROUTES_2026_08_28: readonly string[] = [
   "PUT /api/codex-auth/accounts/alias",
   "PUT /api/codex-auth/accounts/priority",
   "PUT /api/codex-auth/active",
-  "PUT /api/codex-auth/auto-switch",
   "PUT /api/codex-auth/failover",
   "PUT /api/combos",
   "PUT /api/custom-models/{id}",
diff --git a/tests/cli/cli-dispatch.test.ts b/tests/cli/cli-dispatch.test.ts
index ef940dcf83..970f8f5bd6 100644
--- a/tests/cli/cli-dispatch.test.ts
+++ b/tests/cli/cli-dispatch.test.ts
@@ -4,6 +4,10 @@ import { DISPATCH_ALIASES, DISPATCH_COMMANDS, dispatchCommand, resolveDispatchCo
 import type { CliDispatchDeps } from "../../src/cli/dispatch";
 import type { OcxConfig } from "../../src/types";
 import { runGuiCommand } from "../../src/cli/gui";
+import { isCodexAccountLoginName } from "../../src/cli/account-auth";
+import { listOAuthProviders } from "../../src/oauth";
+import { isKeyLoginProvider } from "../../src/oauth/key-providers";
+import { loginUsageMessage } from "../../src/oauth/login-cli";
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -721,3 +725,136 @@ describe("GUI command delegation", () => {
     }
   });
 });
+
+describe("login routes the Codex account names instead of printing the provider wall", () => {
+  /**
+   * `ocx login codex` used to fall through to handleLogin, which knows only the public
+   * OAuth and API-key providers, and answered with a ~90-name usage list that never
+   * contains the word the user typed. The Codex pool is reachable (`ocx account login
+   * codex`), so the dead end was vocabulary, not capability.
+   *
+   * The observable proof that the routing happened is the account path's own precondition:
+   * that flow runs inside the proxy, so with no live proxy it reports "Proxy is not
+   * running" and exits 1. handleLogin would have printed "Usage: ocx login <provider>"
+   * and killed the process with process.exit(1) instead, which is also why these cases
+   * cannot simply assert on a non-Codex name here.
+   */
+  const runLogin = async (args: string[]): Promise<{ code: number; err: string }> => {
+    const err: string[] = [];
+    const errorSpy = spyOn(console, "error").mockImplementation((...v: unknown[]) => { err.push(v.join(" ")); });
+    try {
+      const argv = ["login", ...args];
+      const code = await dispatchCommand(
+        { kind: "command", command: "login", args: argv },
+        { ...fakeDeps, args: argv, findLiveProxy: async () => null } as unknown as CliDispatchDeps,
+      );
+      return { code, err: err.join("\n") };
+    } finally {
+      errorSpy.mockRestore();
+    }
+  };
+
+  test("every Codex spelling reaches the account-pool login", async () => {
+    for (const name of ["codex", "chatgpt", "openai", "CODEX", " codex "]) {
+      const result = await runLogin([name]);
+      expect(result.code, `${name} must route to the account login`).toBe(1);
+      expect(result.err).toContain("Proxy is not running");
+      expect(result.err).not.toContain("Usage: ocx login <provider>");
+    }
+  });
+
+  test("account-login flags ride into the request body, not just past the parser", async () => {
+    // An earlier version of this case asserted the 503 path with --reauth/--id attached and
+    // called that "flags survive". It could not fail: dropping the flags at the dispatch seam
+    // leaves an empty leftover list, so rejectArgs stays quiet and the liveness probe prints
+    // the same message. The only falsifiable proof is the request the flags are supposed to
+    // reach, so this one answers the probe with a live proxy and reads the POST body.
+    const calls: { url: string; method?: string; body?: string }[] = [];
+    const fetchSpy = spyOn(globalThis, "fetch").mockImplementation((async (input: RequestInfo | URL, init?: RequestInit) => {
+      calls.push({ url: String(input), method: init?.method, body: typeof init?.body === "string" ? init.body : undefined });
+      return new Response(JSON.stringify({ flowId: "flow-1", url: "https://example.invalid/auth" }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      });
+    }) as unknown as typeof fetch);
+    const logSpy = spyOn(console, "log").mockImplementation(() => {});
+    try {
+      const argv = ["login", "codex", "--reauth", "--id", "acct-1", "--no-wait", "--json"];
+      const code = await dispatchCommand(
+        { kind: "command", command: "login", args: argv },
+        {
+          ...fakeDeps,
+          args: argv,
+          findLiveProxy: async () => ({ hostname: "127.0.0.1", port: 65500 }),
+        } as unknown as CliDispatchDeps,
+      );
+      expect(code).toBe(0);
+      expect(calls).toHaveLength(1);
+      expect(calls[0]?.url).toContain("/api/codex-auth/login");
+      expect(calls[0]?.method).toBe("POST");
+      expect(JSON.parse(calls[0]?.body ?? "{}")).toEqual({ id: "acct-1", reauth: true });
+    } finally {
+      logSpy.mockRestore();
+      fetchSpy.mockRestore();
+    }
+  });
+
+  test("an unsupported flag is still rejected as a usage error", async () => {
+    const result = await runLogin(["codex", "--nope"]);
+    expect(result.code).toBe(2);
+    expect(result.err).toContain("Unexpected argument(s): --nope");
+  });
+
+  test("a name that is not a Codex spelling still gets the provider wall, not the account path", async () => {
+    // Closes the other half of the routing claim: the predicate is the gate, so a regression
+    // that sent every 'ocx login' through the account command would print "Proxy is not
+    // running" here instead of the wall. handleLogin ends in process.exit, which a test
+    // cannot survive, so the exit is spied and turned into a throw.
+    const err: string[] = [];
+    const errorSpy = spyOn(console, "error").mockImplementation((...v: unknown[]) => { err.push(v.join(" ")); });
+    const exitSpy = spyOn(process, "exit").mockImplementation(((exitCode?: number) => {
+      throw new Error(`process.exit:${exitCode}`);
+    }) as never);
+    try {
+      const argv = ["login", "definitely-not-a-provider"];
+      await expect(dispatchCommand(
+        { kind: "command", command: "login", args: argv },
+        { ...fakeDeps, args: argv, findLiveProxy: async () => null } as unknown as CliDispatchDeps,
+      )).rejects.toThrow("process.exit:1");
+      const printed = err.join("\n");
+      expect(printed).toContain("Usage: ocx login <provider>");
+      expect(printed).toContain("ocx login codex");
+      expect(printed).toContain("openai-apikey");
+      expect(printed).not.toContain("Proxy is not running");
+    } finally {
+      exitSpy.mockRestore();
+      errorSpy.mockRestore();
+    }
+  });
+
+  test("the provider wall names the Codex route without joining the public OAuth surface", () => {
+    const usage = loginUsageMessage();
+    expect(usage).toContain("ocx login codex");
+    // The wall is what the production path prints (asserted above through console.error);
+    // this reads the same source so a wording regression names the field that changed.
+    expect(usage).toContain("openai-apikey");
+    // Routing must not re-open the generic OAuth path for the pool credential:
+    // tests/oauth/oauth-public-surface.test.ts owns that exclusion.
+    expect(listOAuthProviders()).not.toContain("chatgpt");
+    expect(listOAuthProviders()).not.toContain("codex");
+    // The other table the routing silently shadows: if a key-login provider ever took one of
+    // these ids, 'ocx login <that id>' would become unreachable with no other failing test.
+    for (const name of ["openai", "codex", "chatgpt"]) expect(isKeyLoginProvider(name)).toBe(false);
+    expect(isKeyLoginProvider("openai-apikey")).toBe(true);
+    expect(isCodexAccountLoginName("codex")).toBe(true);
+    expect(isCodexAccountLoginName("xai")).toBe(false);
+  });
+
+  test("the registry entry keeps documenting the Codex route", () => {
+    // help.ts and registry.ts carry the only discoverability text a user sees before typing;
+    // the existing help/registry suites only require that an 'ocx login' line exists at all.
+    const details = (CLI_COMMANDS.find(entry => entry.name === "login")?.details ?? []).join(" ");
+    expect(details).toContain("ocx login codex");
+    expect(details).toContain("openai-apikey");
+  });
+});
diff --git a/tests/cli/cli-headless-parity.test.ts b/tests/cli/cli-headless-parity.test.ts
index 5594d44a59..0206c8e54a 100644
--- a/tests/cli/cli-headless-parity.test.ts
+++ b/tests/cli/cli-headless-parity.test.ts
@@ -250,6 +250,11 @@ describe("headless GUI parity CLI", () => {
       // skipping the endpoint.
       ["/api/github/star", "(none — GUI-only)"],
       ["/api/oauth", "ocx account"],
+      // The unified pool-settings route (#695 wp5c). One path answers for every pool
+      // kind, and `ocx account strategy` / `ocx account sticky` / `ocx account auto-switch`
+      // are what drive it headlessly — they declare it in src/cli/capabilities.ts rather
+      // than the retired per-namespace paths.
+      ["/api/pool/settings", "ocx account strategy/sticky/auto-switch"],
       ["/api/accounts/events", "(none — dashboard invalidation; ocx account reads current selection)"],
       ["/api/providers/keys", "ocx account"],
       ["/api/providers", "ocx provider"],
diff --git a/tests/cli/cli-status-json.test.ts b/tests/cli/cli-status-json.test.ts
index aeef546421..1c613ed376 100644
--- a/tests/cli/cli-status-json.test.ts
+++ b/tests/cli/cli-status-json.test.ts
@@ -2,7 +2,7 @@ import { beforeEach, describe, expect, spyOn, test } from "bun:test";
 import { createHash } from "node:crypto";
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdtempSync, readdirSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from "node:fs";
-import { createServer } from "node:net";
+import { createConnection, createServer } from "node:net";
 import type { AddressInfo } from "node:net";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
@@ -879,6 +879,24 @@ describe("status reports stale process records end to end", () => {
     await new Promise<void>(resolve => { probe.close(() => resolve()); });
     return port;
   }
+
+  /**
+   * Prove the endpoint refuses right now.
+   *
+   * `allocateFreePort` releases the port it reports, and on a sharded runner every other
+   * test binding an ephemeral port is a candidate to take it. A fixture that assumes a
+   * released port is still refusing asserts against whatever happened to bind it.
+   */
+  async function refusesConnection(port: number): Promise<boolean> {
+    return await new Promise<boolean>(resolve => {
+      const socket = createConnection({ port, host: "127.0.0.1" });
+      const settle = (refused: boolean): void => { socket.destroy(); resolve(refused); };
+      socket.setTimeout(1_000);
+      socket.once("connect", () => settle(false));
+      socket.once("timeout", () => settle(false));
+      socket.once("error", () => settle(true));
+    });
+  }
   let freePort: number;
   beforeEach(async () => { freePort = await allocateFreePort(); });
 
@@ -950,17 +968,27 @@ describe("status reports stale process records end to end", () => {
     await new Promise<void>(resolve => { occupied.listen(0, "127.0.0.1", () => resolve()); });
     const occupiedPort = (occupied.address() as AddressInfo).port;
     try {
-      // Allocate after the listener is bound: it can reuse the port released by
-      // beforeEach, so that earlier number no longer proves a refused endpoint.
-      const recordedPort = await allocateFreePort();
-      expect(recordedPort).not.toBe(occupiedPort);
       const pid = findDeadPid();
       writeFileSync(join(home, "config.json"), JSON.stringify({ port: occupiedPort, codexAutoStart: false }), "utf8");
       writeFileSync(join(home, "ocx.pid"), String(pid), "utf8");
-      writeFileSync(join(home, "runtime-port.json"), JSON.stringify({ pid, port: recordedPort, hostname: "127.0.0.1" }), "utf8");
 
-      const parsed = JSON.parse(runStatusJson(home).stdout) as { proxy?: { staleProcessState?: unknown } };
-      expect(parsed.proxy?.staleProcessState).toBe(true);
+      // The recorded port has to refuse for this to discriminate, and `allocateFreePort`
+      // hands back a port it has already released. Confirm refusal immediately before and
+      // immediately after the probe, and re-allocate when something took it in between, so
+      // a stolen port retries instead of failing an assertion it never exercised.
+      let parsed: { proxy?: { staleProcessState?: unknown } } | undefined;
+      for (let attempt = 0; attempt < 5 && parsed === undefined; attempt++) {
+        const recordedPort = await allocateFreePort();
+        if (recordedPort === occupiedPort) continue;
+        if (!await refusesConnection(recordedPort)) continue;
+        writeFileSync(join(home, "runtime-port.json"), JSON.stringify({ pid, port: recordedPort, hostname: "127.0.0.1" }), "utf8");
+        const observed = JSON.parse(runStatusJson(home).stdout) as { proxy?: { staleProcessState?: unknown } };
+        if (!await refusesConnection(recordedPort)) continue;
+        parsed = observed;
+      }
+
+      expect(parsed, "no allocated port stayed refused across the status probe").toBeDefined();
+      expect(parsed?.proxy?.staleProcessState).toBe(true);
     } finally {
       await new Promise<void>(resolve => { occupied.close(() => resolve()); });
       removeTreeWithRetry(home);
diff --git a/tests/clients/client-export-modality-enum.test.ts b/tests/clients/client-export-modality-enum.test.ts
index 36473391c6..849b1e6518 100644
--- a/tests/clients/client-export-modality-enum.test.ts
+++ b/tests/clients/client-export-modality-enum.test.ts
@@ -6,6 +6,7 @@ import {
   type ExportModel,
   type GajaeGeneratedConfig,
   type HermesGeneratedConfig,
+  type OpencodeGeneratedConfig,
   type PiGeneratedConfig,
 } from "../../src/clients/config-export";
 import type { OcxConfig } from "../../src/types";
@@ -52,6 +53,11 @@ function hermesModels(models: ExportModel[]) {
     .providers[OPENCODE_PROVIDER_ID].models;
 }
 
+function opencodeModels(models: ExportModel[]) {
+  return (buildClientConfig("opencode", ctx(models)) as OpencodeGeneratedConfig)
+    .providers[OPENCODE_PROVIDER_ID].models;
+}
+
 /** The live failure, by its real id and real modality list. */
 const MIXED: ExportModel = {
   namespaced: "zenmux/meta-muse-spark-1.1",
@@ -147,3 +153,94 @@ describe("exported modalities stay inside the enum each client accepts", () => {
     }
   });
 });
+
+/**
+ * opencode is the third shape of this problem, and the only one where the fix is a
+ * capability field rather than a filter.
+ *
+ * Its model schema accepts a WIDER enum than our internal vocabulary
+ * (`text | audio | image | video | pdf`, opencode.ai/config.json), and its client gates
+ * pasting on `attachment` / `modalities.input` INSTEAD of rejecting the file we hand it. So
+ * an out-of-enum value is dropped, but a row left with nothing acceptable keeps its entry
+ * and carries no capability keys — never a fabricated `text`, which would advertise input
+ * the model cannot read.
+ */
+describe("opencode receives the capability fields its client gates attachments on", () => {
+  test("a declared model advertises attachment plus every modality opencode accepts", () => {
+    // The live catalog shape: meta-muse-spark-1.1 declares text|image|audio, and audio is
+    // INSIDE opencode's enum, so unlike Pi and Gajae nothing is dropped here.
+    expect(opencodeModels([MIXED])["zenmux/meta-muse-spark-1.1"]).toEqual({
+      name: "meta-muse-spark-1.1 (zenmux)",
+      limit: { context: 1_048_576, output: 32_000 },
+      attachment: true,
+      modalities: { input: ["text", "image", "audio"], output: ["text"] },
+    });
+  });
+
+  test("an audio-only row stays audio-only instead of being retyped as text", () => {
+    // opencode accepts audio, so the Pi/Gajae answer — omit the row — would lose a model for
+    // no reason. Faithfulness costs nothing here.
+    expect(opencodeModels([AUDIO_ONLY])["p/audio-only"]).toEqual({
+      name: "audio-only (p)",
+      attachment: true,
+      modalities: { input: ["audio"], output: ["text"] },
+    });
+  });
+
+  test("a text-only declaration is advertised as text-only rather than omitted", () => {
+    const textOnly: ExportModel = { namespaced: "p/text", provider: "p", id: "text", inputModalities: ["text"] };
+    expect(opencodeModels([textOnly])["p/text"]).toEqual({
+      name: "text (p)",
+      attachment: false,
+      modalities: { input: ["text"], output: ["text"] },
+    });
+  });
+
+  test("a row that declares nothing carries no capability keys at all", () => {
+    // Not the same as `{ input: ["text"] }`: opencode already falls back to text-only for an
+    // entry without capabilities, and the omission keeps the pre-#4286 bytes for every model
+    // whose row says nothing.
+    const bare: ExportModel = { namespaced: "p/bare", provider: "p", id: "bare" };
+    const empty: ExportModel = { ...bare, namespaced: "p/empty", id: "empty", inputModalities: [] };
+    const models = opencodeModels([bare, empty]);
+    expect(models["p/bare"]).toEqual({ name: "bare (p)" });
+    expect(models["p/empty"]).toEqual({ name: "empty (p)" });
+  });
+
+  test("an out-of-enum value is dropped and duplicates collapse", () => {
+    const odd: ExportModel = {
+      namespaced: "p/odd", provider: "p", id: "odd", inputModalities: ["file", "image", "image"],
+    };
+    expect(opencodeModels([odd])["p/odd"]).toEqual({
+      name: "odd (p)",
+      attachment: true,
+      modalities: { input: ["image"], output: ["text"] },
+    });
+  });
+
+  test("a model whose only declaration is out of enum keeps its entry, without capabilities", () => {
+    const foreign: ExportModel = { namespaced: "p/foreign", provider: "p", id: "foreign", inputModalities: ["file"] };
+    expect(opencodeModels([foreign])["p/foreign"]).toEqual({ name: "foreign (p)" });
+  });
+
+  test("no emitted entry in a whole catalog carries a value opencode rejects", () => {
+    const catalog: ExportModel[] = [
+      MIXED,
+      AUDIO_ONLY,
+      { namespaced: "p/bare", provider: "p", id: "bare" },
+      { namespaced: "p/foreign", provider: "p", id: "foreign", inputModalities: ["file"] },
+      { namespaced: "p/vision", provider: "p", id: "vision", inputModalities: ["text", "image"] },
+    ];
+    const models = opencodeModels(catalog);
+    // The entry survives where Pi and Gajae would have dropped it; only its bad value goes.
+    expect(Object.keys(models)).toContain("p/foreign");
+    for (const entry of Object.values(models)) {
+      for (const value of entry.modalities?.input ?? []) {
+        expect(["text", "audio", "image", "video", "pdf"]).toContain(value);
+      }
+      for (const value of entry.modalities?.output ?? []) {
+        expect(["text", "audio", "image", "video", "pdf"]).toContain(value);
+      }
+    }
+  });
+});
diff --git a/tests/clients/cline-client.test.ts b/tests/clients/cline-client.test.ts
new file mode 100644
index 0000000000..cb3fc64e4a
--- /dev/null
+++ b/tests/clients/cline-client.test.ts
@@ -0,0 +1,58 @@
+import { describe, expect, test } from "bun:test";
+import { join } from "node:path";
+import { buildClientConfig, buildClientConfigText, buildClientContribution, clineConfigPath, EXPORT_CLIENTS, type ExportContext } from "../../src/clients/config-export";
+import type { ClineGeneratedConfig } from "../../src/clients/config-export/cline";
+import { INTEGRATION_CLIENTS } from "../../src/integrations/registry";
+import { decodeClinePair, encodeClinePair, parseClineDocument, serializeClineDocument } from "../../src/integrations/cline-document";
+import { PARSE_FAILED } from "../../src/integrations/config-io";
+
+const context: ExportContext = {
+  baseUrl: "http://127.0.0.1:10100/v1",
+  models: [
+    { namespaced: "mock/vision", provider: "mock", id: "vision", contextWindow: 200000, inputModalities: ["text", "image"] },
+    { namespaced: "mock/unknown", provider: "mock", id: "unknown" },
+    { namespaced: "mock/audio", provider: "mock", id: "audio", inputModalities: ["audio"] },
+  ],
+};
+
+describe("Cline shared SDK store contract", () => {
+  test("emits separate native documents with canonical selectors and no invented limits", () => {
+    // Oracle: cline/cline cfe9cadab996, core/types/provider-settings.ts and local-provider-registry.ts.
+    const doc = buildClientConfig("cline", context) as ClineGeneratedConfig;
+    expect(doc.settings.version).toBe(1);
+    expect(doc.settings.providers.opencodex!.settings).toEqual({ provider: "opencodex", protocol: "openai-responses", client: "openai", apiKey: "opencodex-loopback", baseUrl: context.baseUrl });
+    expect(doc.settings).not.toHaveProperty("lastUsedProvider");
+    expect(doc.catalog.providers.opencodex!.models).toEqual({
+      "mock/vision": { name: "vision (mock)", contextWindow: 200000, modalities: { input: ["text", "image"], output: ["text"] }, supportsVision: true },
+      "mock/unknown": { name: "unknown (mock)" },
+    });
+    expect(buildClientContribution("cline", context).fragments.map(f => f.path)).toEqual([
+      ["settings", "providers", "opencodex"], ["catalog", "providers", "opencodex"],
+    ]);
+    expect(EXPORT_CLIENTS.cline.summarize(doc)).toEqual({ modelCount: 2, modelsWithoutLimits: 1 });
+    expect(JSON.parse(buildClientConfigText("cline", context).text)).toEqual(doc);
+  });
+
+  test("honors the upstream path override order and refuses colliding/relative targets", () => {
+    const home = join(process.cwd(), "synthetic-home");
+    expect(clineConfigPath({}, home)).toBe(join(home, ".cline", "data", "settings", "providers.json"));
+    expect(clineConfigPath({ CLINE_DIR: "~/root" }, home)).toBe(join(home, "root", "data", "settings", "providers.json"));
+    expect(clineConfigPath({ CLINE_DIR: "~/root", CLINE_DATA_DIR: "~/data" }, home)).toBe(join(home, "data", "settings", "providers.json"));
+    const env = { CLINE_PROVIDER_SETTINGS_PATH: "~/custom/provider.json", CLINE_DATA_DIR: "~/data", CLINE_DIR: "~/root" };
+    expect(clineConfigPath(env, home)).toBe(join(home, "custom", "provider.json"));
+    expect(INTEGRATION_CLIENTS.cline.detectDir(env, home)).toBe(join(home, "custom"));
+    expect(() => clineConfigPath({ CLINE_DIR: "relative" }, home)).toThrow("CLINE_DIR");
+    expect(() => clineConfigPath({ CLINE_PROVIDER_SETTINGS_PATH: "~/MODELS.JSON" }, home)).toThrow("must differ");
+  });
+
+  test("raw snapshots preserve whitespace and absence, while unsafe native data refuses", () => {
+    const pair = { settings: '{ "version": 1, "providers": {} }\n', catalog: null };
+    expect(decodeClinePair(encodeClinePair(pair))).toEqual(pair);
+    expect(decodeClinePair(null)).toEqual({ settings: null, catalog: null });
+    for (const settings of ['{"version":2}', '{"providers":[]}', '{"x":1,"x":2}', 'null', '{"x":1e999}']) {
+      expect(parseClineDocument(encodeClinePair({ settings, catalog: null }))).toBe(PARSE_FAILED);
+    }
+    const doc = buildClientConfig("cline", context);
+    expect(parseClineDocument(serializeClineDocument(doc))).toEqual(doc);
+  });
+});
diff --git a/tests/clients/cline-writer.test.ts b/tests/clients/cline-writer.test.ts
new file mode 100644
index 0000000000..4247f0abde
--- /dev/null
+++ b/tests/clients/cline-writer.test.ts
@@ -0,0 +1,330 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { clineConfigPath } from "../../src/clients/config-export";
+import { createClineIO, clinePendingPath } from "../../src/integrations/cline-io";
+import { decodeClinePair } from "../../src/integrations/cline-document";
+import { applyIntegration, disableIntegration, overwriteIntegration, refreshIntegration, restoreIntegration, type IntegrationWriteInput } from "../../src/integrations/writer";
+import { createIntegrationStateStore } from "../../src/integrations/store";
+import { readIntegrationState } from "../../src/integrations/state";
+import { removeTreeWithRetry } from "../helpers/remove-tree";
+import type { IntegrationTransaction } from "../../src/integrations/config-io";
+import type { OcxConfig } from "../../src/types";
+import { refreshOwnedCatalogIntegrations } from "../../src/integrations/catalog-refresh";
+
+let root: string;
+let input: IntegrationWriteInput;
+let settings: string;
+let catalog: string;
+const originalSettings = '{ "version": 1, "lastUsedProvider": "mine", "modes": {}, "providers": {"mine":{"settings":{"provider":"mine"},"updatedAt":"2026-01-01T00:00:00.000Z","tokenSource":"manual"}} }\n';
+const originalCatalog = '{\n "version":1, "providers":{"mine":{"models":{"keep":{"name":"Keep"}}}}\n}\n';
+const models = [{ namespaced: "mock/a", provider: "mock", id: "a", contextWindow: 120000 }, { namespaced: "mock/b", provider: "mock", id: "b" }];
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), "ocx-cline-"));
+  const home = join(root, "home");
+  settings = clineConfigPath({}, home);
+  catalog = join(dirname(settings), "models.json");
+  mkdirSync(dirname(settings), { recursive: true });
+  input = {
+    clientId: "cline", home, env: {}, models, port: 10100,
+    config: { hostname: "127.0.0.1", port: 10100, defaultProvider: "mock", providers: { mock: { adapter: "openai-chat", baseUrl: "http://127.0.0.1/v1" } } } as OcxConfig,
+    store: createIntegrationStateStore(join(root, "store")),
+  };
+});
+afterEach(() => removeTreeWithRetry(root));
+
+function seed() { writeFileSync(settings, originalSettings); writeFileSync(catalog, originalCatalog); }
+function settingsDoc() { return JSON.parse(readFileSync(settings, "utf8")); }
+function catalogDoc() { return JSON.parse(readFileSync(catalog, "utf8")); }
+
+describe("Cline journaled pair", () => {
+  test("explicit catalog sync leaves unowned clients alone and refreshes owned pairs", async () => {
+    let loads = 0;
+    const request = { ...input, models: async () => { loads += 1; return [models[0]!]; } };
+    expect(await refreshOwnedCatalogIntegrations(request, ["cline"])).toEqual([]);
+    expect(loads).toBe(0);
+    expect(existsSync(settings)).toBe(false);
+    expect(applyIntegration(input).ok).toBe(true);
+    expect(await refreshOwnedCatalogIntegrations(request, ["cline"])).toEqual([{ client: "cline", ok: true, changed: true }]);
+    expect(loads).toBe(1);
+    expect(Object.keys(catalogDoc().providers.opencodex.models)).toEqual(["mock/a"]);
+  });
+  test("preserves foreign providers/default, journals both originals, and restores exact bytes", () => {
+    seed();
+    const applied = applyIntegration(input);
+    expect(applied.ok).toBe(true);
+    expect(settingsDoc().lastUsedProvider).toBe("mine");
+    expect(catalogDoc().providers.mine.models.keep.name).toBe("Keep");
+    expect(Object.keys(catalogDoc().providers.opencodex.models)).toEqual(["mock/a", "mock/b"]);
+    expect(readIntegrationState(input).state).toBe("current");
+    const op = input.store!.listOperations("cline")[0]!;
+    const snapshot = input.store!.readSnapshot(op);
+    expect(snapshot.kind).toBe("stored");
+    if (snapshot.kind === "stored") expect(decodeClinePair(snapshot.text)).toEqual({ settings: originalSettings, catalog: originalCatalog });
+    expect(restoreIntegration({ ...input, opId: op.opId }).ok).toBe(true);
+    expect(readFileSync(settings, "utf8")).toBe(originalSettings);
+    expect(readFileSync(catalog, "utf8")).toBe(originalCatalog);
+  });
+
+  test("restore preserves initially absent members, including both absent", () => {
+    for (const partial of [false, true]) {
+      if (partial) writeFileSync(settings, originalSettings);
+      const applied = applyIntegration(input);
+      expect(applied.ok).toBe(true);
+      if (!applied.ok || !applied.opId) throw new Error("missing operation");
+      expect(restoreIntegration({ ...input, opId: applied.opId }).ok).toBe(true);
+      expect(existsSync(settings)).toBe(partial);
+      expect(existsSync(catalog)).toBe(false);
+    }
+  });
+
+  test("refresh removes retired models and preserves only still-routed user selection", () => {
+    seed();
+    expect(applyIntegration(input).ok).toBe(true);
+    const edited = settingsDoc();
+    edited.providers.opencodex.settings.model = "mock/b";
+    edited.providers.opencodex.updatedAt = "2026-09-12T00:00:00.000Z";
+    writeFileSync(settings, JSON.stringify(edited));
+    expect(refreshIntegration({ ...input, port: 12100 }).ok).toBe(true);
+    expect(settingsDoc().providers.opencodex.settings.model).toBe("mock/b");
+    expect(settingsDoc().providers.opencodex.settings.baseUrl).toContain(":12100/");
+    expect(refreshIntegration({ ...input, models: [models[0]!] }).ok).toBe(true);
+    expect(Object.keys(catalogDoc().providers.opencodex.models)).toEqual(["mock/a"]);
+    expect(settingsDoc().providers.opencodex.settings.model).toBeUndefined();
+    expect(disableIntegration(input).ok).toBe(true);
+    expect(settingsDoc().providers.opencodex).toBeUndefined();
+    expect(catalogDoc().providers.opencodex).toBeUndefined();
+    expect(settingsDoc().version).toBe(1);
+    expect(settingsDoc().lastUsedProvider).toBe("mine");
+  });
+
+  test("protected edits refuse refresh and drifted pair requires explicit restore confirmation", () => {
+    seed();
+    const applied = applyIntegration(input);
+    if (!applied.ok || !applied.opId) throw new Error("apply failed");
+    const edited = settingsDoc();
+    edited.providers.opencodex.settings.baseUrl = "http://127.0.0.1:9999/v1";
+    writeFileSync(settings, JSON.stringify(edited));
+    expect(readIntegrationState(input).state).toBe("conflict");
+    expect(refreshIntegration(input).ok).toBe(false);
+    const refused = restoreIntegration({ ...input, opId: applied.opId });
+    expect(refused.ok).toBe(false);
+    if (!refused.ok) expect(refused.reason).toBe("drift_requires_confirm");
+    expect(restoreIntegration({ ...input, opId: applied.opId, confirmDrift: true }).ok).toBe(true);
+    expect(readFileSync(catalog, "utf8")).toBe(originalCatalog);
+  });
+
+  test("unsafe second file and remote admission refuse without replacing the first file", () => {
+    seed();
+    writeFileSync(catalog, '{"version":2}');
+    expect(applyIntegration(input).ok).toBe(false);
+    expect(readFileSync(settings, "utf8")).toBe(originalSettings);
+    seed();
+    expect(applyIntegration({ ...input, config: { ...input.config, hostname: "0.0.0.0" } }).ok).toBe(false);
+    expect(readFileSync(settings, "utf8")).toBe(originalSettings);
+    expect(input.store!.listOperations()).toHaveLength(0);
+  });
+
+  test("missing install and no-follow member refusals leave both files alone", () => {
+    const absentHome = join(root, "never-installed");
+    const absent = applyIntegration({ ...input, home: absentHome });
+    expect(absent.ok).toBe(false);
+    if (!absent.ok) expect(absent.reason).toBe("not_installed");
+    seed();
+    const io = input.store!.io();
+    const refused = applyIntegration({ ...input, io: { ...io, lstatKind: path => path === catalog ? "other" : io.statKind(path) } });
+    expect(refused.ok).toBe(false);
+    expect(readFileSync(settings, "utf8")).toBe(originalSettings);
+    expect(readFileSync(catalog, "utf8")).toBe(originalCatalog);
+  });
+
+  test("occupied custom provider requires explicit overwrite and remains reversible", () => {
+    seed();
+    const doc = settingsDoc();
+    doc.providers.opencodex = { settings: { provider: "opencodex", baseUrl: "http://127.0.0.1:9999/v1" }, updatedAt: "2026-01-01T00:00:00.000Z", tokenSource: "manual" };
+    const before = JSON.stringify(doc);
+    writeFileSync(settings, before);
+    expect(applyIntegration(input).ok).toBe(false);
+    const applied = overwriteIntegration(input);
+    expect(applied.ok).toBe(true);
+    if (!applied.ok || !applied.opId) throw new Error("overwrite failed");
+    expect(restoreIntegration({ ...input, opId: applied.opId }).ok).toBe(true);
+    expect(readFileSync(settings, "utf8")).toBe(before);
+  });
+
+  test("second-file and journal failures compensate both files and ownership", () => {
+    for (const point of ["catalog", "journal"] as const) {
+      seed();
+      const io = input.store!.io();
+      let failed = false;
+      const result = applyIntegration({ ...input, io: {
+        ...io,
+        writeText: (path, text) => {
+          if (point === "catalog" && path === catalog && !failed) { failed = true; throw new Error("injected"); }
+          io.writeText(path, text);
+        },
+        appendJournal: entry => {
+          if (point === "journal") throw new Error("injected");
+          io.appendJournal(entry);
+        },
+      } });
+      expect(result.ok).toBe(false);
+      expect(readFileSync(settings, "utf8")).toBe(originalSettings);
+      expect(readFileSync(catalog, "utf8")).toBe(originalCatalog);
+      expect(input.store!.readRecords().cline).toBeUndefined();
+      expect(existsSync(clinePendingPath(input.store!, settings))).toBe(false);
+    }
+  });
+
+  test("pending pair is read-only unsafe; an explicit mutation recovers interrupted files", () => {
+    seed();
+    const io = input.store!.io();
+    let failWrites = false;
+    const result = applyIntegration({ ...input, io: { ...io, writeText: (path, text) => {
+      if (path === catalog) failWrites = true;
+      if (failWrites && (path === settings || path === catalog)) throw new Error("disk offline");
+      io.writeText(path, text);
+    } } });
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.residual).toBe(true);
+    const intermediate = readFileSync(settings, "utf8");
+    expect(readIntegrationState(input).state).toBe("unsafe");
+    expect(readFileSync(settings, "utf8")).toBe(intermediate);
+    expect(applyIntegration(input).ok).toBe(true);
+    expect(readIntegrationState(input).state).toBe("current");
+  });
+
+  test("journaled mixed pair cannot be blessed by marker cleanup", () => {
+    seed();
+    const io = input.store!.io();
+    const marker = clinePendingPath(input.store!, settings);
+    expect(applyIntegration({ ...input, io: { ...io, removeFile: path => {
+      if (path === marker) throw new Error("cleanup unavailable");
+      io.removeFile(path);
+    } } }).ok).toBe(true);
+    const pending = JSON.parse(readFileSync(marker, "utf8")) as IntegrationTransaction;
+    writeFileSync(settings, decodeClinePair(pending.before).settings!);
+    expect(readIntegrationState(input).state).toBe("unsafe");
+    expect(applyIntegration(input).ok).toBe(false);
+    expect(existsSync(marker)).toBe(true);
+  });
+
+  test("an uncommitted marker never authorizes overwriting a foreign edit", () => {
+    seed();
+    const io = input.store!.io();
+    let offline = false;
+    expect(applyIntegration({ ...input, io: { ...io, writeText: (path, text) => {
+      if (path === catalog) offline = true;
+      if (offline && (path === settings || path === catalog)) throw new Error("offline");
+      io.writeText(path, text);
+    } } }).ok).toBe(false);
+    const foreign = '{"version":1,"providers":{"mine":{"changed":true}}}';
+    writeFileSync(catalog, foreign);
+    expect(applyIntegration(input).ok).toBe(false);
+    expect(readFileSync(catalog, "utf8")).toBe(foreign);
+    expect(existsSync(clinePendingPath(input.store!, settings))).toBe(true);
+  });
+
+  test("cleanup failure after append keeps success and permits safe later cleanup", () => {
+    seed();
+    const io = input.store!.io();
+    const marker = clinePendingPath(input.store!, settings);
+    expect(applyIntegration({ ...input, io: { ...io, removeFile: path => {
+      if (path === marker) throw new Error("cleanup unavailable");
+      io.removeFile(path);
+    } } }).ok).toBe(true);
+    expect(input.store!.listOperations("cline")).toHaveLength(1);
+    expect(readIntegrationState(input).state).toBe("current");
+    expect(applyIntegration(input).ok).toBe(true);
+    expect(existsSync(marker)).toBe(false);
+    expect(input.store!.listOperations("cline")).toHaveLength(1);
+  });
+
+  test("uncertain history or ownership never authorizes recovery writes", () => {
+    seed();
+    const store = input.store!;
+    const io = store.io();
+    const marker = clinePendingPath(store, settings);
+    expect(applyIntegration({ ...input, io: { ...io, removeFile: path => {
+      if (path === marker) throw new Error("retain marker");
+      io.removeFile(path);
+    } } }).ok).toBe(true);
+    const before = [readFileSync(settings, "utf8"), readFileSync(catalog, "utf8"), readFileSync(marker, "utf8"), readFileSync(join(store.root, "records.json"), "utf8")];
+    for (const method of ["findCommittedOperation", "readRecordsStrict"] as const) {
+      const uncertain = { ...store, [method]: () => { throw new Error("unreadable"); } };
+      expect(applyIntegration({ ...input, store: uncertain }).ok).toBe(false);
+      expect([readFileSync(settings, "utf8"), readFileSync(catalog, "utf8"), readFileSync(marker, "utf8"), readFileSync(join(store.root, "records.json"), "utf8")]).toEqual(before);
+    }
+    // Valid JSON with invalid schema is also uncertainty, not a missing commit.
+    const journal = join(store.root, "journal.jsonl");
+    const journalBefore = readFileSync(journal, "utf8");
+    writeFileSync(journal, '{}\n');
+    expect(applyIntegration(input).ok).toBe(false);
+    writeFileSync(journal, journalBefore);
+    expect([readFileSync(settings, "utf8"), readFileSync(catalog, "utf8"), readFileSync(marker, "utf8"), readFileSync(join(store.root, "records.json"), "utf8")]).toEqual(before);
+  });
+
+  test("malformed pending authority is rejected before any recovery side effect", () => {
+    seed();
+    const store = input.store!;
+    const io = store.io();
+    const marker = clinePendingPath(store, settings);
+    expect(applyIntegration({ ...input, io: { ...io, removeFile: path => {
+      if (path === marker) throw new Error("retain marker");
+      io.removeFile(path);
+    } } }).ok).toBe(true);
+    const valid = JSON.parse(readFileSync(marker, "utf8")) as IntegrationTransaction;
+    const files = [readFileSync(settings, "utf8"), readFileSync(catalog, "utf8"), readFileSync(join(store.root, "records.json"), "utf8")];
+    const variants: unknown[] = [
+      { ...valid, priorRecord: { clientId: "cline", configPath: settings } },
+      { ...valid, entry: { ...valid.entry, priorRecord: valid.record } },
+      { ...valid, entry: { ...valid.entry, resultFingerprint: "0000000000000000" } },
+      { ...valid, entry: { ...valid.entry, resultAbsent: true, resultFingerprint: "" } },
+      { ...valid, entry: { ...valid.entry, kind: ["apply"] } },
+      { ...valid, record: { ...valid.record, fragmentPaths: [["settings", "providers", "mine"]] } },
+    ];
+    for (const variant of variants) {
+      const text = JSON.stringify(variant);
+      writeFileSync(marker, text);
+      expect(applyIntegration(input).ok).toBe(false);
+      expect([readFileSync(settings, "utf8"), readFileSync(catalog, "utf8"), readFileSync(join(store.root, "records.json"), "utf8")]).toEqual(files);
+      expect(readFileSync(marker, "utf8")).toBe(text);
+    }
+  });
+
+  test("embedded NUL cannot turn malformed prior ownership into a valid recovery path", () => {
+    seed();
+    const store = input.store!;
+    const io = store.io();
+    let failedAppend = false;
+    const result = applyIntegration({ ...input, io: { ...io,
+      appendJournal: () => { failedAppend = true; throw new Error("append unavailable"); },
+      writeText: (path, text) => {
+        if (failedAppend && (path === settings || path === catalog)) throw new Error("rollback unavailable");
+        io.writeText(path, text);
+      },
+    } });
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.residual).toBe(true);
+    const marker = clinePendingPath(store, settings);
+    const pending = JSON.parse(readFileSync(marker, "utf8")) as IntegrationTransaction;
+    const priorRecord = { ...pending.record!, fragmentPaths: [["settings\0providers", "opencodex"], ["catalog", "providers", "opencodex"]] };
+    const malformed = JSON.stringify({ ...pending, priorRecord, entry: { ...pending.entry, priorRecord } });
+    writeFileSync(marker, malformed);
+    const before = [readFileSync(settings, "utf8"), readFileSync(catalog, "utf8"), readFileSync(join(store.root, "records.json"), "utf8")];
+    expect(applyIntegration(input).ok).toBe(false);
+    expect([readFileSync(settings, "utf8"), readFileSync(catalog, "utf8"), readFileSync(join(store.root, "records.json"), "utf8")]).toEqual(before);
+    expect(readFileSync(marker, "utf8")).toBe(malformed);
+  });
+
+  test("adapter keeps non-target IO unchanged and reads a pair as one snapshot", () => {
+    seed();
+    const adapter = createClineIO(input.store!.io(), settings, input.store!);
+    const result = adapter.readText(settings);
+    if (result.kind !== "text") throw new Error("pair missing");
+    expect(decodeClinePair(result.text)).toEqual({ settings: originalSettings, catalog: originalCatalog });
+    expect(adapter.statKind(dirname(settings))).toBe("dir");
+  });
+});
diff --git a/tests/clients/desktop-3p.test.ts b/tests/clients/desktop-3p.test.ts
index 912c2c18af..cc116cb837 100644
--- a/tests/clients/desktop-3p.test.ts
+++ b/tests/clients/desktop-3p.test.ts
@@ -212,13 +212,21 @@ describe("Claude Desktop 3P models", () => {
   });
 
   test("an openai context cap reaches the Desktop writer, not just the dashboard", () => {
-    // gpt-5.4 is the authoritative 1M native, so it earns supports1m. Capping the provider
-    // at 272k has to take that away here too, or the written Desktop config promises a
-    // window the proxy will not serve (#854's effective-window contract).
-    const uncapped = generateDesktop3pModels(["gpt-5.4"], []);
-    expect(uncapped[0]).toMatchObject({ supports1m: true, prefer1m: true });
+    // No surviving native advertises a 1M window (gpt-5.4 was the last). Sol's
+    // opt-in ceiling is 922k, so even a 1M provider cap must not invent
+    // supports1m — nativeOpenAiContextWindow clamps it under the threshold.
+    // A 272k cap has to take the same path, or the written Desktop config
+    // would promise a window the proxy will not serve (#854's effective-window
+    // contract).
+    const uncapped = generateDesktop3pModels(["gpt-5.6-sol"], []);
+    expect(uncapped[0]!.supports1m).toBeUndefined();
+    expect(uncapped[0]!.prefer1m).toBeUndefined();
 
-    const capped = generateDesktop3pModels(["gpt-5.4"], [], undefined, 272_000);
+    const optedIn = generateDesktop3pModels(["gpt-5.6-sol"], [], undefined, 1_000_000);
+    expect(optedIn[0]!.supports1m).toBeUndefined();
+    expect(optedIn[0]!.prefer1m).toBeUndefined();
+
+    const capped = generateDesktop3pModels(["gpt-5.6-sol"], [], undefined, 272_000);
     expect(capped[0]!.supports1m).toBeUndefined();
     expect(capped[0]!.prefer1m).toBeUndefined();
   });
diff --git a/tests/clients/integrations-state.test.ts b/tests/clients/integrations-state.test.ts
index b2d4f530cc..f96cf134c5 100644
--- a/tests/clients/integrations-state.test.ts
+++ b/tests/clients/integrations-state.test.ts
@@ -794,9 +794,9 @@ describe("installation detection is independent of config state", () => {
  * from. Rationale and the per-client table: 020 §1 amendment.
  */
 describe("the loopback-only set is one fact, read through one seam", () => {
-  test("omp, pi, kimi, gajae, dsh, mcode, zcode, prime, aside and raycast are loopback-only and nobody else is", () => {
+  test("omp, pi, kimi, gajae, dsh, mcode, zcode, prime, aside, raycast and omo are loopback-only and nobody else is", () => {
     const loopbackOnly = INTEGRATION_CLIENT_IDS.filter(id => isLoopbackOnly(id));
-    expect(loopbackOnly).toEqual(["pi", "omp", "kimi", "gajae", "dsh", "mcode", "zcode", "prime", "aside", "raycast"]);
+    expect(loopbackOnly).toEqual(["pi", "omp", "kimi", "gajae", "dsh", "mcode", "zcode", "prime", "aside", "raycast", "omo", "cline"]);
   });
 
   test("the registry restates nothing — it reads the export spec", () => {
diff --git a/tests/clients/integrations-writer.test.ts b/tests/clients/integrations-writer.test.ts
index c80c28481d..38c2498c32 100644
--- a/tests/clients/integrations-writer.test.ts
+++ b/tests/clients/integrations-writer.test.ts
@@ -549,6 +549,29 @@ describe("apply", () => {
     if (!result.ok) expect(result.reason).toBe("conflict");
   });
 
+  test("a hand-edited ZCode provider kind stays a hard conflict (#4295)", () => {
+    // The export moved from `openai-compatible` to `openai` so ZCode dials the proxy's
+    // native Responses route. `kind` is not a refreshable path, so a user who sets it
+    // back by hand must keep owning that decision instead of having it silently
+    // rewritten — the same protection `options` already has above.
+    const configPath = installZcode();
+    const request = input({ clientId: "zcode" });
+    expect(applyIntegration(request).ok).toBe(true);
+
+    const document = JSON.parse(readFileSync(configPath, "utf8")) as {
+      provider: Record<string, { kind: string }>;
+    };
+    expect(document.provider.opencodex!.kind).toBe("openai");
+    document.provider.opencodex!.kind = "openai-compatible";
+    writeFileSync(configPath, `${JSON.stringify(document, null, 2)}\n`);
+
+    const status = readIntegrationState(request);
+    expect(status).toMatchObject({ state: "conflict", reason: "foreign-edit" });
+    const result = applyIntegration(request);
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toBe("conflict");
+  });
+
   test("a malformed recorded ZCode policy cannot widen refreshable drift (#2389)", () => {
     const configPath = installZcode();
     const request = input({ clientId: "zcode" });
diff --git a/tests/clients/omo-client.test.ts b/tests/clients/omo-client.test.ts
new file mode 100644
index 0000000000..aac1cffbcb
--- /dev/null
+++ b/tests/clients/omo-client.test.ts
@@ -0,0 +1,161 @@
+import { describe, expect, test } from "bun:test";
+import { join } from "node:path";
+import {
+  ClientPathError,
+  EXPORT_CLIENTS,
+  LOOPBACK_API_KEY_PLACEHOLDER,
+  OPENCODE_PROVIDER_ID,
+  buildClientConfig,
+  buildClientConfigText,
+  buildClientContribution,
+  omoAgentDir,
+  omoConfigPath,
+  type ExportContext,
+  type PiGeneratedConfig,
+} from "../../src/clients/config-export";
+import { INTEGRATION_CLIENTS } from "../../src/integrations/registry";
+import type { OcxConfig } from "../../src/types";
+
+const CONFIG = {
+  port: 10100,
+  hostname: "127.0.0.1",
+  defaultProvider: "mock",
+  providers: { mock: { adapter: "openai-chat", baseUrl: "http://127.0.0.1/v1" } },
+} as OcxConfig;
+
+function context(): ExportContext {
+  return {
+    baseUrl: "http://127.0.0.1:10100/v1",
+    config: CONFIG,
+    models: [
+      { namespaced: "anthropic/claude-opus-5", provider: "anthropic", id: "claude-opus-5", contextWindow: 200_000, inputModalities: ["text", "image"] },
+      { namespaced: "openai/gpt-5.6-sol", provider: "openai", id: "gpt-5.6-sol", contextWindow: 922_000, reasoningEfforts: ["low", "medium", "high"] },
+      // No authoritative context window: ships without limits rather than guessing.
+      { namespaced: "mystery/model", provider: "mystery", id: "model" },
+    ],
+  };
+}
+
+describe("omo client config", () => {
+  /**
+   * The opposite of Prime's assertion, deliberately.
+   *
+   * Prime and Aside reuse Pi's builder with the session-affinity flag left at
+   * its default, because nobody has verified that their engines read it. omo's
+   * engine WAS verified: senpi's compiled validator accepts `compat` with
+   * `sendSessionAffinityHeaders`, so omo opts in and the generated provider is
+   * byte-identical to Pi's.
+   */
+  test("is Pi's document including the session-affinity opt-in", () => {
+    const omo = buildClientConfig("omo", context()) as PiGeneratedConfig;
+    const pi = buildClientConfig("pi", context()) as PiGeneratedConfig;
+    expect(omo).toEqual(pi);
+    expect(omo.providers[OPENCODE_PROVIDER_ID]!.compat).toEqual({ sendSessionAffinityHeaders: true });
+  });
+
+  /**
+   * The flag has to be on BOTH paths or they drift: `build` feeds `ocx export`
+   * and `/api/client-config`, while `buildContribution` is what the writer
+   * actually puts on disk when the integration is enabled or refreshed. One
+   * carrying `compat` and the other not would look correct in every unit test
+   * that only reads one of them.
+   */
+  test("the exported document and the written fragment are the same bytes", () => {
+    const document = buildClientConfig("omo", context()) as PiGeneratedConfig;
+    expect(buildClientContribution("omo", context()).fragments[0]!.value)
+      .toEqual(document.providers[OPENCODE_PROVIDER_ID]);
+  });
+
+  test("adds only providers.opencodex, wired to the loopback proxy", () => {
+    const document = buildClientConfig("omo", context()) as PiGeneratedConfig;
+    expect(Object.keys(document)).toEqual(["providers"]);
+    expect(Object.keys(document.providers)).toEqual([OPENCODE_PROVIDER_ID]);
+    const provider = document.providers[OPENCODE_PROVIDER_ID]!;
+    expect(provider.baseUrl).toBe("http://127.0.0.1:10100/v1");
+    expect(provider.api).toBe("openai-completions");
+    expect(provider.apiKey).toBe(LOOPBACK_API_KEY_PLACEHOLDER);
+  });
+
+  test("native JSON round-trips and never carries a credential", () => {
+    const sentinel = ["sk", "live", "omo", "sentinel"].join("-");
+    const withKey = { ...CONFIG, apiKeys: [{ key: sentinel }] } as OcxConfig;
+    const built = buildClientConfigText("omo", { ...context(), config: withKey });
+    expect(JSON.parse(built.text)).toEqual(built.document as never);
+    expect(built.text).not.toContain(sentinel);
+    expect(built.text).toContain(LOOPBACK_API_KEY_PLACEHOLDER);
+  });
+
+  test("the contribution owns exactly the providers.opencodex path under its own id", () => {
+    const contribution = buildClientContribution("omo", context());
+    // Reusing Pi's builder must not leak Pi's id into the ownership record, or
+    // the writer would stamp one client's block with the other's name.
+    expect(contribution.clientId).toBe("omo");
+    expect(contribution.fragments.map(f => f.path)).toEqual([["providers", OPENCODE_PROVIDER_ID]]);
+  });
+
+  /**
+   * omo publishes three variables and reads them in this order, then pins the
+   * first two for the senpi process it spawns. Checking them in any other order
+   * would write a catalog omo never opens.
+   */
+  test("resolves omo's own three-variable precedence", () => {
+    expect(omoAgentDir({}, "/home/u")).toBe(join("/home/u", ".omo", "agent"));
+    expect(omoConfigPath({}, "/home/u")).toBe(join("/home/u", ".omo", "agent", "models.json"));
+
+    expect(omoConfigPath({ OMO_CODING_AGENT_DIR: "/from-omo" }, "/home/u")).toBe(join("/from-omo", "models.json"));
+    expect(omoConfigPath({ SENPI_CODING_AGENT_DIR: "/from-senpi" }, "/home/u")).toBe(join("/from-senpi", "models.json"));
+    expect(omoConfigPath({ PI_CODING_AGENT_DIR: "/from-pi" }, "/home/u")).toBe(join("/from-pi", "models.json"));
+
+    // Precedence, not merely recognition.
+    expect(omoConfigPath({
+      OMO_CODING_AGENT_DIR: "/from-omo",
+      SENPI_CODING_AGENT_DIR: "/from-senpi",
+      PI_CODING_AGENT_DIR: "/from-pi",
+    }, "/home/u")).toBe(join("/from-omo", "models.json"));
+    expect(omoConfigPath({
+      SENPI_CODING_AGENT_DIR: "/from-senpi",
+      PI_CODING_AGENT_DIR: "/from-pi",
+    }, "/home/u")).toBe(join("/from-senpi", "models.json"));
+
+    // omo trims and then tests truthiness, so a blank value is not a path.
+    expect(omoConfigPath({ OMO_CODING_AGENT_DIR: "   ", PI_CODING_AGENT_DIR: "/from-pi" }, "/home/u"))
+      .toBe(join("/from-pi", "models.json"));
+    expect(omoConfigPath({ OMO_CODING_AGENT_DIR: "" }, "/home/u"))
+      .toBe(join("/home/u", ".omo", "agent", "models.json"));
+
+    expect(omoConfigPath({ OMO_CODING_AGENT_DIR: "~/alt" }, "/home/u")).toBe(join("/home/u", "alt", "models.json"));
+  });
+
+  /**
+   * Each variable reports under its own name. Telling someone their
+   * `PI_CODING_AGENT_DIR` is relative when they set `OMO_CODING_AGENT_DIR`
+   * sends them to the wrong line of their shell profile.
+   */
+  test("refuses a relative override and names the variable that carried it", () => {
+    expect(() => omoConfigPath({ OMO_CODING_AGENT_DIR: "relative" }, "/home/u")).toThrow(ClientPathError);
+    expect(() => omoConfigPath({ OMO_CODING_AGENT_DIR: "relative" }, "/home/u")).toThrow(/OMO_CODING_AGENT_DIR/);
+    expect(() => omoConfigPath({ SENPI_CODING_AGENT_DIR: "relative" }, "/home/u")).toThrow(/SENPI_CODING_AGENT_DIR/);
+    expect(() => omoConfigPath({ PI_CODING_AGENT_DIR: "relative" }, "/home/u")).toThrow(/PI_CODING_AGENT_DIR/);
+  });
+
+  /**
+   * The AGENT directory, not `~/.omo`. The v4 launcher wrapper creates
+   * `~/.omo` for its `binary-runtime` without ever creating `agent/`, so
+   * detecting on the parent reports a v5 install that is not there.
+   */
+  test("detects installation by the agent directory, not the brand directory", () => {
+    const spec = INTEGRATION_CLIENTS.omo;
+    expect(spec.detectDir({}, "/home/u")).toBe(join("/home/u", ".omo", "agent"));
+    expect(spec.detectDir({}, "/home/u")).not.toBe(join("/home/u", ".omo"));
+    expect(spec.detectDir({ OMO_CODING_AGENT_DIR: "/elsewhere" } as NodeJS.ProcessEnv, "/home/u")).toBe("/elsewhere");
+  });
+
+  test("ships as a loopback-only integration with no env var to export", () => {
+    const spec = EXPORT_CLIENTS.omo;
+    expect(spec.loopbackOnly).toBe(true);
+    expect(spec.apiKeyEnv).toBe("");
+    // Not a bare models.json: a download would collide with pi's, prime's and
+    // aside's in the user's Downloads folder.
+    expect(spec.filename).toBe("omo-models.json");
+  });
+});
diff --git a/tests/clients/remote-control-prototype.test.ts b/tests/clients/remote-control-prototype.test.ts
new file mode 100644
index 0000000000..dea420eaf3
--- /dev/null
+++ b/tests/clients/remote-control-prototype.test.ts
@@ -0,0 +1,270 @@
+import { describe, expect, test } from "bun:test";
+import { randomUUID } from "node:crypto";
+import {
+  OpaqueRemoteControlRelay,
+  RemoteControlClientHandshake,
+  RemoteControlHost,
+  acceptRemoteControlClientHello,
+  decodeRemoteControlApplicationFrame,
+  decodeRemoteControlRelayFrame,
+  encodeRemoteControlApplicationFrame,
+  encodeRemoteControlRelayFrame,
+  generateRemoteControlIdentityKeyPair,
+  serializeRemoteControlHello,
+  type RemoteControlRelayPeer,
+  type RemoteControlTerminal,
+} from "../../src/remote-control";
+
+class Peer implements RemoteControlRelayPeer {
+  buffered = 0;
+  sent: Uint8Array[] = [];
+  closed: Array<{ code: number; reason: string }> = [];
+
+  bufferedAmount(): number { return this.buffered; }
+  send(value: Uint8Array): void { this.sent.push(value.slice()); }
+  close(code: number, reason: string): void { this.closed.push({ code, reason }); }
+}
+
+function handshakeFixture() {
+  const account = generateRemoteControlIdentityKeyPair();
+  const device = generateRemoteControlIdentityKeyPair();
+  const sessionId = randomUUID();
+  const deviceId = randomUUID();
+  const client = RemoteControlClientHandshake.create({
+    sessionId,
+    deviceId,
+    commandProfile: "codex",
+    capabilities: ["terminal.input", "terminal.output", "terminal.resize"],
+    accountPrivateKey: account.privateKey,
+  });
+  return { account, device, sessionId, deviceId, client };
+}
+
+describe("Paseo-style remote control prototype", () => {
+  test("rejects a host authenticated with a different pinned device key", () => {
+    const fixture = handshakeFixture();
+    const accepted = acceptRemoteControlClientHello(fixture.client.hello, {
+      expectedSessionId: fixture.sessionId,
+      expectedDeviceId: fixture.deviceId,
+      devicePrivateKey: fixture.device.privateKey,
+      accountPublicKey: fixture.account.publicKey,
+      allowedCapabilities: ["terminal.input"],
+    });
+    const otherDevice = generateRemoteControlIdentityKeyPair();
+    expect(() => fixture.client.complete(accepted.hello, otherDevice.publicKey))
+      .toThrow("host identity verification failed");
+    accepted.cipher.destroy();
+  });
+
+  test("rejects a valid-length corrupted host signature", () => {
+    const fixture = handshakeFixture();
+    const accepted = acceptRemoteControlClientHello(fixture.client.hello, {
+      expectedSessionId: fixture.sessionId,
+      expectedDeviceId: fixture.deviceId,
+      devicePrivateKey: fixture.device.privateKey,
+      accountPublicKey: fixture.account.publicKey,
+      allowedCapabilities: ["terminal.input"],
+    });
+    const signature = Buffer.from(accepted.hello.signature, "base64url");
+    signature[0]! ^= 1;
+    expect(() => fixture.client.complete({
+      ...accepted.hello, signature: signature.toString("base64url"),
+    }, fixture.device.publicKey)).toThrow("host identity verification failed");
+    accepted.cipher.destroy();
+  });
+
+  test("authenticates both endpoints, encrypts both directions, and rejects replay", () => {
+    const fixture = handshakeFixture();
+    const accepted = acceptRemoteControlClientHello(fixture.client.hello, {
+      expectedSessionId: fixture.sessionId,
+      expectedDeviceId: fixture.deviceId,
+      devicePrivateKey: fixture.device.privateKey,
+      accountPublicKey: fixture.account.publicKey,
+      allowedCapabilities: ["terminal.input", "terminal.output", "terminal.resize"],
+    });
+    const clientCipher = fixture.client.complete(accepted.hello, fixture.device.publicKey);
+
+    const first = clientCipher.encrypt(new TextEncoder().encode("private terminal input"));
+    expect(new TextDecoder().decode(accepted.cipher.decrypt(first))).toBe("private terminal input");
+    expect(() => accepted.cipher.decrypt(first)).toThrow("replayed or out-of-order");
+
+    const authenticated = clientCipher.encrypt(new TextEncoder().encode("authenticated frame"));
+    const tamperedCiphertext = Uint8Array.from(authenticated);
+    tamperedCiphertext[tamperedCiphertext.length - 1]! ^= 1;
+    expect(() => accepted.cipher.decrypt(tamperedCiphertext)).toThrow();
+    expect(new TextDecoder().decode(accepted.cipher.decrypt(authenticated))).toBe("authenticated frame");
+
+    const reply = accepted.cipher.encrypt(new TextEncoder().encode("private terminal output"));
+    expect(new TextDecoder().decode(clientCipher.decrypt(reply))).toBe("private terminal output");
+
+    const tampered = { ...fixture.client.hello, commandProfile: "claude" as const };
+    expect(() => acceptRemoteControlClientHello(tampered, {
+      expectedSessionId: fixture.sessionId,
+      expectedDeviceId: fixture.deviceId,
+      devicePrivateKey: fixture.device.privateKey,
+      accountPublicKey: fixture.account.publicKey,
+      allowedCapabilities: ["terminal.input"],
+    })).toThrow("account identity verification failed");
+  });
+
+  test("does not start the local terminal until the first authenticated application frame", async () => {
+    const fixture = handshakeFixture();
+    const events: string[] = [];
+    let output: ((value: Uint8Array) => void) | undefined;
+    const terminal: RemoteControlTerminal = {
+      write(value) { events.push(`input:${new TextDecoder().decode(value)}`); },
+      resize(columns, rows) { events.push(`resize:${columns}x${rows}`); },
+      close() { events.push("close"); },
+    };
+    const encryptedOutput: Uint8Array[] = [];
+    const host = new RemoteControlHost({
+      deviceId: fixture.deviceId,
+      devicePrivateKey: fixture.device.privateKey,
+      accountPublicKey: fixture.account.publicKey,
+      terminalFactory: {
+        create(options) {
+          events.push(`start:${options.commandProfile}`);
+          output = options.onOutput;
+          return terminal;
+        },
+      },
+    });
+    const hostHelloPayload = host.open(
+      fixture.sessionId,
+      serializeRemoteControlHello(fixture.client.hello),
+      value => encryptedOutput.push(value),
+    );
+    expect(events).toEqual([]);
+    const clientCipher = fixture.client.complete(
+      JSON.parse(new TextDecoder().decode(hostHelloPayload)),
+      fixture.device.publicKey,
+    );
+    await host.receive(fixture.sessionId, clientCipher.encrypt(encodeRemoteControlApplicationFrame({
+      kind: "resize",
+      columns: 120,
+      rows: 40,
+    })));
+    expect(events).toEqual(["start:codex", "resize:120x40"]);
+
+    output!(new TextEncoder().encode("hello from local PTY"));
+    expect(encryptedOutput).toHaveLength(1);
+    const decoded = decodeRemoteControlApplicationFrame(clientCipher.decrypt(encryptedOutput[0]!));
+    expect(decoded.kind).toBe("output");
+    if (decoded.kind === "output") expect(new TextDecoder().decode(decoded.data)).toBe("hello from local PTY");
+  });
+
+  test("relay routes opaque bytes without parsing terminal plaintext", () => {
+    const relay = new OpaqueRemoteControlRelay();
+    const host = new Peer();
+    const client = new Peer();
+    const deviceId = randomUUID();
+    const sessionId = randomUUID();
+    relay.registerHost(deviceId, host);
+
+    const opaqueHello = Uint8Array.from([0, 255, 17, 33, 128]);
+    relay.attachClient({ sessionId, deviceId, client, openPayload: opaqueHello });
+    const open = decodeRemoteControlRelayFrame(host.sent.shift()!);
+    expect(open.kind).toBe("open");
+    expect(open.payload).toEqual(opaqueHello);
+
+    const ciphertext = Uint8Array.from([222, 173, 190, 239, 0, 255]);
+    relay.receiveFromHost(deviceId, host, encodeRemoteControlRelayFrame({
+      kind: "data",
+      sessionId,
+      payload: ciphertext,
+    }));
+    expect(client.sent).toEqual([ciphertext]);
+  });
+
+  test("carries an encrypted terminal round trip through the opaque relay", async () => {
+    const fixture = handshakeFixture();
+    const relay = new OpaqueRemoteControlRelay();
+    const hostSocket = new Peer();
+    const browserSocket = new Peer();
+    let terminalOutput: ((value: Uint8Array) => void) | undefined;
+    const terminalInput: string[] = [];
+    const localHost = new RemoteControlHost({
+      deviceId: fixture.deviceId,
+      devicePrivateKey: fixture.device.privateKey,
+      accountPublicKey: fixture.account.publicKey,
+      terminalFactory: {
+        create(options) {
+          terminalOutput = options.onOutput;
+          return {
+            write(value) { terminalInput.push(new TextDecoder().decode(value)); },
+            resize() {},
+            close() {},
+          };
+        },
+      },
+    });
+    relay.registerHost(fixture.deviceId, hostSocket);
+    relay.attachClient({
+      sessionId: fixture.sessionId,
+      deviceId: fixture.deviceId,
+      client: browserSocket,
+      openPayload: serializeRemoteControlHello(fixture.client.hello),
+    });
+
+    const open = decodeRemoteControlRelayFrame(hostSocket.sent.shift()!);
+    const hostHello = localHost.open(open.sessionId, open.payload, ciphertext => {
+      relay.receiveFromHost(fixture.deviceId, hostSocket, encodeRemoteControlRelayFrame({
+        kind: "data",
+        sessionId: fixture.sessionId,
+        payload: ciphertext,
+      }));
+    });
+    relay.receiveFromHost(fixture.deviceId, hostSocket, encodeRemoteControlRelayFrame({
+      kind: "data",
+      sessionId: fixture.sessionId,
+      payload: hostHello,
+    }));
+    const clientCipher = fixture.client.complete(
+      JSON.parse(new TextDecoder().decode(browserSocket.sent.shift()!)),
+      fixture.device.publicKey,
+    );
+
+    relay.receiveFromClient(
+      fixture.sessionId,
+      browserSocket,
+      clientCipher.encrypt(encodeRemoteControlApplicationFrame({
+        kind: "input",
+        data: new TextEncoder().encode("codex --help\n"),
+      })),
+    );
+    const input = decodeRemoteControlRelayFrame(hostSocket.sent.shift()!);
+    await localHost.receive(input.sessionId, input.payload);
+    expect(terminalInput).toEqual(["codex --help\n"]);
+
+    terminalOutput!(new TextEncoder().encode("local-only output"));
+    const output = decodeRemoteControlApplicationFrame(clientCipher.decrypt(browserSocket.sent.shift()!));
+    expect(output.kind).toBe("output");
+    if (output.kind === "output") expect(new TextDecoder().decode(output.data)).toBe("local-only output");
+  });
+
+  test("enforces device session and backpressure bounds", () => {
+    const relay = new OpaqueRemoteControlRelay({ maxSessionsPerDevice: 1, maxBufferedBytes: 8 });
+    const host = new Peer();
+    const deviceId = randomUUID();
+    relay.registerHost(deviceId, host);
+    relay.attachClient({ sessionId: randomUUID(), deviceId, client: new Peer(), openPayload: Uint8Array.of(1) });
+    expect(() => relay.attachClient({
+      sessionId: randomUUID(),
+      deviceId,
+      client: new Peer(),
+      openPayload: Uint8Array.of(2),
+    })).toThrow("session limit");
+
+    const backpressured = new Peer();
+    backpressured.buffered = 9;
+    const secondDevice = randomUUID();
+    relay.registerHost(secondDevice, backpressured);
+    expect(() => relay.attachClient({
+      sessionId: randomUUID(),
+      deviceId: secondDevice,
+      client: new Peer(),
+      openPayload: Uint8Array.of(3),
+    })).toThrow("backpressured");
+    expect(backpressured.closed[0]?.code).toBe(1013);
+  });
+});
diff --git a/tests/clients/remote-workspace-protocol.test.ts b/tests/clients/remote-workspace-protocol.test.ts
new file mode 100644
index 0000000000..87a2eacc71
--- /dev/null
+++ b/tests/clients/remote-workspace-protocol.test.ts
@@ -0,0 +1,45 @@
+import { describe, expect, test } from "bun:test";
+import {
+  parseRemoteWorkspaceAgentMessage,
+  parseRemoteWorkspaceHubMessage,
+  remoteWorkspaceToolsForCapabilities,
+  serializeRemoteWorkspaceAgentMessage,
+  truncateRemoteWorkspaceUtf8,
+} from "../../src/remote-control";
+
+describe("Remote Workspace protocol contracts", () => {
+  test("presence carries the explicit read-only capability set", () => {
+    const encoded = serializeRemoteWorkspaceAgentMessage({
+      version: 1, type: "presence", capabilities: ["workspace.read"],
+    });
+    expect(parseRemoteWorkspaceAgentMessage(encoded)).toEqual({
+      version: 1, type: "presence", capabilities: ["workspace.read"],
+    });
+    expect(remoteWorkspaceToolsForCapabilities(["workspace.read"])).toEqual([
+      "list_directory", "read_file",
+    ]);
+  });
+
+  test("rejects unknown fields, versions and capabilities at the wire boundary", () => {
+    for (const value of [
+      { version: 2, type: "presence", capabilities: ["workspace.read"] },
+      { version: 1, type: "presence", capabilities: ["workspace.admin"] },
+      { version: 1, type: "presence", capabilities: ["workspace.read"], root: "/" },
+    ]) expect(() => parseRemoteWorkspaceAgentMessage(JSON.stringify(value))).toThrow();
+    expect(() => parseRemoteWorkspaceHubMessage(JSON.stringify({
+      version: 1, type: "ciphertext", sessionId: "not-a-session", payload: "A".repeat(32),
+    }))).toThrow("session ID");
+  });
+
+  test("refuses oversized control messages before interpreting their fields", () => {
+    expect(() => parseRemoteWorkspaceAgentMessage(" ".repeat(96 * 1024 + 1))).toThrow("length");
+  });
+
+  test("UTF-8 limits preserve complete scalar values at byte boundaries", () => {
+    expect(truncateRemoteWorkspaceUtf8("A😀한", 4)).toBe("A");
+    expect(truncateRemoteWorkspaceUtf8("A😀한", 5)).toBe("A😀");
+    expect(truncateRemoteWorkspaceUtf8("A😀한", 8)).toBe("A😀한");
+    expect(truncateRemoteWorkspaceUtf8("한", 0)).toBe("");
+    expect(() => truncateRemoteWorkspaceUtf8("x", -1)).toThrow("limit");
+  });
+});
diff --git a/tests/clients/remote-workspace-rpc-framing.test.ts b/tests/clients/remote-workspace-rpc-framing.test.ts
new file mode 100644
index 0000000000..f13f043c90
--- /dev/null
+++ b/tests/clients/remote-workspace-rpc-framing.test.ts
@@ -0,0 +1,33 @@
+import { describe, expect, test } from "bun:test";
+import {
+  RemoteWorkspaceRpcReassembler,
+  frameRemoteWorkspaceRpcMessage,
+} from "../../src/remote-control/workspace-rpc-framing";
+
+describe("Remote Workspace RPC framing", () => {
+  test("round-trips a logical message across bounded relay frames", () => {
+    const message = new TextEncoder().encode("large-rpc\n".repeat(30_000));
+    const frames = [...frameRemoteWorkspaceRpcMessage(message)];
+    expect(frames.length).toBeGreaterThan(1);
+    expect(Math.max(...frames.map(frame => frame.byteLength))).toBeLessThanOrEqual(64 * 1024 - 24);
+    const reassembler = new RemoteWorkspaceRpcReassembler();
+    let complete: Uint8Array | null = null;
+    for (const frame of frames) complete = reassembler.accept(frame);
+    expect(complete).toEqual(message);
+  });
+
+  test("rejects out-of-order fragments and forgets cleared partial messages", () => {
+    const frames = [...frameRemoteWorkspaceRpcMessage(new Uint8Array(200_000))];
+    const reassembler = new RemoteWorkspaceRpcReassembler();
+    expect(() => reassembler.accept(frames[1]!)).toThrow("out of order");
+    expect(reassembler.accept(frames[0]!)).toBeNull();
+    reassembler.clear();
+    expect(() => reassembler.accept(frames[1]!)).toThrow("out of order");
+  });
+
+  test("rejects a declared allocation above the logical message limit", () => {
+    const frame = [...frameRemoteWorkspaceRpcMessage(new Uint8Array(100_000))][0]!.slice();
+    new DataView(frame.buffer, frame.byteOffset, frame.byteLength).setUint32(22, 0xffff_ffff);
+    expect(() => new RemoteWorkspaceRpcReassembler().accept(frame)).toThrow("fragment bounds");
+  });
+});
diff --git a/tests/clients/sync-client-integrations.test.ts b/tests/clients/sync-client-integrations.test.ts
index e051afb2f4..219a148082 100644
--- a/tests/clients/sync-client-integrations.test.ts
+++ b/tests/clients/sync-client-integrations.test.ts
@@ -65,7 +65,7 @@ describe("ocx sync fans out to enabled native clients and owned file integration
 
     expect(fn).toContain("grokIntegrationEnabled(config)");
     expect(fn).toContain("claudeDesktopIntegrationEnabled(config)");
-    expect(fn).toContain('["mcode", "pi", "aside", "raycast"]');
+    expect(fn).toContain('["mcode", "pi", "aside", "raycast", "omo", "cline"]');
     expect(fn).toContain("refreshOwnedCatalogIntegrations");
     // Native clients keep their catches; the owned catalog helper isolates file clients.
     expect(fn.match(/catch \(error\)/g)?.length).toBe(2);
@@ -651,12 +651,12 @@ describe("owned Pi/Aside catalogs follow filtered model selections", () => {
   });
 });
 
-test("the direct ocx sync command refreshes MCode, Pi, Raycast and server-owned Aside", async () => {
+test("the direct ocx sync command refreshes MCode, Pi, Raycast, omo and server-owned Aside", async () => {
   const src = await Bun.file(new URL("../../src/cli/dispatch.ts", import.meta.url)).text();
   const start = src.indexOf("sync: async deps =>");
   const command = src.slice(start, src.indexOf("v2: async deps =>", start));
   expect(command).toContain("refreshOwnedCatalogIntegrations");
-  expect(command).toContain('["mcode", "pi", "raycast"]');
+  expect(command).toContain('["mcode", "pi", "raycast", "omo", "cline"]');
   expect(command).toContain("refreshAsideProfilesThroughServer");
   expect(command.indexOf("syncModelsToCodex")).toBeLessThan(command.indexOf("refreshOwnedCatalogIntegrations"));
   expect(command).toContain('synced.status !== "refused"');
diff --git a/tests/codex-integration/bearer-admission-routed-provider.test.ts b/tests/codex-integration/bearer-admission-routed-provider.test.ts
index 5b87318626..277f790bd5 100644
--- a/tests/codex-integration/bearer-admission-routed-provider.test.ts
+++ b/tests/codex-integration/bearer-admission-routed-provider.test.ts
@@ -20,6 +20,8 @@ import { ownedServiceHomeInspection } from "../helpers/owned-service-home-inspec
 import { removeTreeWithRetry } from "../helpers/remove-tree";
 import { fakeChatGptJwt } from "../helpers/fake-chatgpt-jwt";
 import { resetVisionDescriptionCache } from "../../src/vision";
+import { SERVER_BUDGET_MS } from "../helpers/test-budget";
+import { saveCodexAccountCredential } from "../../src/codex/account-store";
 
 /**
  * Issue #2132: bearer admission must not require a stored ChatGPT credential.
@@ -116,6 +118,7 @@ function cursorForwardConfig(baseUrl: string, apiKey?: string): OcxConfig {
 
 async function withCursorCaptureServer<T>(
   run: (baseUrl: string, capturedAuth: Array<string | null>) => Promise<T>,
+  beforeResponse?: () => Promise<void>,
 ): Promise<T> {
   const capturedAuth: Array<string | null> = [];
   const sessions = new Set<http2.ServerHttp2Session>();
@@ -127,11 +130,16 @@ async function withCursorCaptureServer<T>(
   server.on("stream", (stream, headers) => {
     const auth = headers.authorization;
     capturedAuth.push(typeof auth === "string" ? auth : null);
-    stream.respond({
-      ":status": typeof auth === "string" ? 200 : 401,
-      "content-type": "application/connect+proto",
-    });
-    stream.end();
+    const respond = () => {
+      if (stream.destroyed || stream.closed) return;
+      stream.respond({
+        ":status": typeof auth === "string" ? 200 : 401,
+        "content-type": "application/connect+proto",
+      });
+      stream.end();
+    };
+    if (beforeResponse) void beforeResponse().then(respond).catch(error => stream.destroy(error));
+    else respond();
   });
   await new Promise<void>((resolve, reject) => {
     const onError = (error: Error) => reject(error);
@@ -432,16 +440,107 @@ describe("bearer admission is not reused as a Cursor upstream credential", () =>
     });
   });
 
-  test.each(["owned", "fenced"])("Chat Cursor keeps stored vision auth off its primary wire (%s)", async ownership => {
+  test.each([
+    "configured-vision-text", "default-sidecars", "no-stored-main", "disabled-vision",
+    "terminal-vision", "routed-vision", "anthropic-vision", "missing-openai",
+    "noncanonical-openai", "search-runTurn", "search-tool-choice-none",
+  ])("Chat Cursor leaves native main switchable without a planned OpenAI helper (%s)", async scenario => {
+    let signalStarted!: () => void;
+    const started = new Promise<void>(resolve => { signalStarted = resolve; });
+    let releaseUpstream!: () => void;
+    const upstreamGate = new Promise<void>(resolve => { releaseUpstream = resolve; });
     await withCursorCaptureServer(async (baseUrl, capturedAuth) => {
       const config = cursorForwardConfig(baseUrl);
+      config.openaiProviderTierVersion = 2;
       config.providers.cursorcustom!.noVisionModels = ["auto"];
       config.providers.openai = {
         adapter: "openai-responses", baseUrl: "https://chatgpt.com/backend-api/codex",
         authMode: "forward", codexAccountMode: "direct",
       };
+      config.visionSidecar = { enabled: true, backend: "openai", model: "gpt-5.6-luna" };
+      if (scenario === "default-sidecars") delete config.visionSidecar;
+      if (scenario === "disabled-vision") config.visionSidecar.enabled = false;
+      if (scenario === "routed-vision") {
+        config.providers.gateway = { ...mixedConfig().providers.gateway!, models: ["vision-model"] };
+        config.visionSidecar = { enabled: true, backend: "routed", model: "gateway/vision-model" };
+      }
+      if (scenario === "anthropic-vision") config.visionSidecar.backend = "anthropic";
+      if (scenario === "missing-openai") delete config.providers.openai;
+      if (scenario === "noncanonical-openai") {
+        // Keep the reserved OpenAI row absent; a custom forward provider is valid config
+        // but is not authority to inject stored ChatGPT credentials into a sidecar.
+        config.providers.mirror = { adapter: "openai-responses", authMode: "forward", baseUrl: "https://mirror.example.com/v1" };
+        delete config.providers.openai;
+      }
+      const search = scenario.startsWith("search-");
+      if (search) config.webSearchSidecar = { enabled: true, backend: "openai", model: "gpt-5.6-luna" };
+      const withImage = ["disabled-vision", "terminal-vision", "routed-vision", "anthropic-vision", "missing-openai", "noncanonical-openai"].includes(scenario);
+      saveConfig(config);
+      const stored = fakeChatGptJwt({ chatgpt_account_id: "stored_main_acc", exp: Math.floor(Date.now() / 1000) + 3600 });
+      writeFileSync(join(codexHome, "auth.json"), JSON.stringify({
+        tokens: scenario === "no-stored-main" ? {} : { access_token: stored, account_id: "stored_main_acc" },
+      }));
+      const server = await startOwnedServer();
+      let settled = false;
+      const pending = originalFetch(new URL("/v1/chat/completions", server.url), {
+        method: "POST",
+        headers: { "content-type": "application/json", "x-opencodex-api-key": ADMISSION_SECRET,
+          authorization: "Bearer cursor-upstream-token",
+          ...(scenario === "terminal-vision" ? { "x-opencodex-vision-describe": "1" } : {}),
+        },
+        body: JSON.stringify({ model: "cursorcustom/auto", stream: false, messages: [{ role: "user",
+          content: withImage ? [{ type: "text", text: "Describe this image" },
+            { type: "image_url", image_url: { url: "data:image/png;base64,aGVsbG8taW1hZ2UtYnl0ZXM=" } }] : "hi",
+        }], ...(search ? { tools: [{ type: "web_search" }] } : {}),
+        ...(scenario === "search-tool-choice-none" ? { tool_choice: "none" } : {}),
+        }),
+      }).then(response => { settled = true; return response; });
+      try {
+        await Promise.race([started, pending.then(async response => {
+          const result = await response.clone().json().catch(() => ({})) as { error?: { code?: string; message?: string } };
+          throw new Error(`Cursor response settled before its held upstream: HTTP ${response.status}, ${result.error?.code ?? ""}: ${result.error?.message ?? ""}`);
+        })]);
+        expect(settled).toBe(false);
+        expect(capturedAuth).toEqual(["Bearer cursor-upstream-token"]);
+        expect(getNativeMainProfileRequestCount()).toBe(0);
+        let switches = 0;
+        const manager = { switch: async () => { switches += 1; return { ok: true }; } } as unknown as NativeProfileManager;
+        const switchUrl = new URL("http://localhost/api/native-main-profiles/switch");
+        const switched = await handleNativeProfileAPI(new Request(switchUrl, {
+          method: "POST", body: JSON.stringify({ target: "target", confirmedStopped: true }),
+        }), switchUrl, config, { manager, drainTimeoutMs: 0 });
+        expect(switched?.status).toBe(200);
+        expect(switches).toBe(1);
+        expect(settled).toBe(false);
+        expect(nativeAuth).toEqual([]);
+      } finally {
+        releaseUpstream();
+        try { await (await pending).text(); } finally { await server.stop(true); }
+      }
+      expect(getNativeMainProfileRequestCount()).toBe(0);
+    }, async () => { signalStarted(); await upstreamGate; });
+  }, SERVER_BUDGET_MS);
+
+  test.each(["owned", "fenced", "pool", "pool-fenced"])("Chat Cursor keeps stored vision auth off its primary wire (%s)", async ownership => {
+    await withCursorCaptureServer(async (baseUrl, capturedAuth) => {
+      const config = cursorForwardConfig(baseUrl);
+      const pool = ownership.startsWith("pool");
+      config.providers.cursorcustom!.noVisionModels = ["auto"];
+      config.providers.openai = {
+        adapter: "openai-responses", baseUrl: "https://chatgpt.com/backend-api/codex",
+        authMode: "forward", codexAccountMode: pool ? "pool" : "direct",
+      };
       // Keep this auth fixture independent of the legacy sidecar model migration.
       config.visionSidecar = { enabled: true, backend: "openai", model: "gpt-5.6-luna" };
+      if (pool) {
+        config.codexAccounts = [{ id: "sidecar-pool", label: "sidecar pool", isMain: false, chatgptAccountId: "sidecar_pool_acc" }];
+        config.activeCodexAccountId = "sidecar-pool";
+        config.autoSwitchThreshold = 0;
+        saveCodexAccountCredential("sidecar-pool", {
+          accessToken: "sidecar-pool-token", refreshToken: "sidecar-pool-refresh",
+          expiresAt: Date.now() + 3_600_000, chatgptAccountId: "sidecar_pool_acc",
+        });
+      }
       saveConfig(config);
       const stored = fakeChatGptJwt({ chatgpt_account_id: "stored_main_acc", exp: Math.floor(Date.now() / 1000) + 3600 });
       writeFileSync(join(codexHome, "auth.json"), JSON.stringify({
@@ -451,6 +550,13 @@ describe("bearer admission is not reused as a Cursor upstream credential", () =>
       globalThis.fetch = (async (input, init) => {
         const url = new URL(input instanceof Request ? input.url : String(input));
         if (url.hostname === "chatgpt.com") {
+          // Pool admission can probe quota independently of the vision helper.
+          if (url.pathname === "/backend-api/wham/usage") return Response.json({
+            rate_limit: { allowed: true, limit_reached: false,
+              primary_window: { used_percent: 0, reset_at: Math.floor(Date.now() / 1000) + 3600, limit_window_seconds: 18000 },
+              secondary_window: { used_percent: 0, reset_at: Math.floor(Date.now() / 1000) + 86400, limit_window_seconds: 604800 },
+            },
+          });
           const headers = new Headers(input instanceof Request ? input.headers : init?.headers);
           sidecar.push({ authorization: headers.get("authorization"), account: headers.get("chatgpt-account-id"),
             claimed: getNativeMainProfileRequestCount() > 0 });
@@ -460,11 +566,12 @@ describe("bearer admission is not reused as a Cursor upstream credential", () =>
         }
         return originalFetch(input, init);
       }) as typeof fetch;
-      const server = ownership === "owned" ? await startOwnedServer() : startServer(0, {
+      const fenced = ownership.endsWith("fenced");
+      const server = !fenced ? await startOwnedServer() : startServer(0, {
         inspectNativeCodexOwnership: () => ({ ownership: "foreign", reason: "fixture owned by another service" }),
       });
       try {
-        if (ownership === "fenced") expect(await waitForNativeMainStartupGate()).toMatchObject({ status: "blocked" });
+        if (fenced) expect(await waitForNativeMainStartupGate()).toMatchObject({ status: "blocked" });
         const response = await originalFetch(new URL("/v1/chat/completions", server.url), {
           method: "POST",
           headers: { "content-type": "application/json", "x-opencodex-api-key": ADMISSION_SECRET,
@@ -477,8 +584,9 @@ describe("bearer admission is not reused as a Cursor upstream credential", () =>
         await response.text();
         // The capture-only Cursor fixture ends without a completion frame.
         expect(response.status).toBe(502);
-        expect(sidecar).toEqual(ownership === "owned"
-          ? [{ authorization: `Bearer ${stored}`, account: "stored_main_acc", claimed: true }] : []);
+        expect(sidecar).toEqual(ownership === "fenced" ? []
+          : [{ authorization: pool ? "Bearer sidecar-pool-token" : `Bearer ${stored}`,
+            account: pool ? "sidecar_pool_acc" : "stored_main_acc", claimed: !pool }]);
         expect(capturedAuth).toEqual(["Bearer cursor-upstream-token"]);
       } finally {
         await server.stop(true);
diff --git a/tests/codex-integration/catalog-full-picker-order.test.ts b/tests/codex-integration/catalog-full-picker-order.test.ts
index e0fd0e1fb6..272db59408 100644
--- a/tests/codex-integration/catalog-full-picker-order.test.ts
+++ b/tests/codex-integration/catalog-full-picker-order.test.ts
@@ -1,3 +1,4 @@
+// Holds INV-AGENT-01 from structure/overview.md; keep the id here if this file is split or renamed.
 import { routedSlug } from "../../src/providers/slug-codec";
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
diff --git a/tests/codex-integration/catalog-zero-credit-picker.test.ts b/tests/codex-integration/catalog-zero-credit-picker.test.ts
index 423ca834f6..c6a564b9eb 100644
--- a/tests/codex-integration/catalog-zero-credit-picker.test.ts
+++ b/tests/codex-integration/catalog-zero-credit-picker.test.ts
@@ -1,10 +1,10 @@
 import { afterEach, describe, expect, test } from "bun:test";
-import { clearCachedProviderQuotas, setCachedProviderQuotaForTests } from "../../src/providers/quota-routing-cache";
+import { clearCachedProviderQuotas, setCachedProviderQuotaForTests, replaceCachedProviderQuotas, providerQuotaRoutingBinding, type ProviderQuotaRoutingEvidence } from "../../src/providers/quota-routing-cache";
 import { quotaInactiveReason } from "../../src/combos/resolve";
 import { buildCatalogEntries, CATALOG_INACTIVE_REASON_FIELD, deriveEntry } from "../../src/codex/catalog/sync";
 import type { RawEntry } from "../../src/codex/catalog/parsing";
 import type { OcxConfig } from "../../src/types";
-import type { ProviderQuota } from "../../src/providers/quota";
+import type { ProviderQuotaReport, ProviderQuota } from "../../src/providers/quota";
 
 /**
  * Regression coverage for #1711 — zero-credit models and combos were still offered as ordinary
@@ -51,6 +51,32 @@ describe("quota-inactive catalog rows (#1711)", () => {
     expect(quotaInactiveReason(config(), [{ provider: "alpha" }], NOW)).toBe("no_credit");
   });
 
+  test("display-only reports cannot mark a catalog row inactive", () => {
+    replaceCachedProviderQuotas([{ provider: "alpha", label: "Alpha", source: "display", quota: exhausted(), updatedAt: NOW }]);
+    expect(quotaInactiveReason(config(), [{ provider: "alpha" }], NOW)).toBeUndefined();
+  });
+
+  test.each(["apiKey", "baseUrl", "adapter"] as const)("bound evidence stops marking inactivity after %s changes", field => {
+    const current = config();
+    const provider = current.providers.alpha!;
+    const report: ProviderQuotaReport = { provider: "alpha", label: "Alpha", source: "inference", quota: exhausted(), updatedAt: NOW };
+    const binding = providerQuotaRoutingBinding("alpha", provider);
+    expect(binding).not.toBeNull();
+    const evidence = new WeakMap<ProviderQuotaReport, ProviderQuotaRoutingEvidence>();
+    evidence.set(report, { quota: report.quota, binding: binding! });
+    replaceCachedProviderQuotas([report], evidence);
+    expect(quotaInactiveReason(current, [{ provider: "alpha" }], NOW)).toBe("no_credit");
+    if (field === "apiKey") provider.apiKey = "changed-key";
+    else if (field === "baseUrl") provider.baseUrl = "https://changed.example.test/v1";
+    else provider.adapter = "openai-responses";
+    expect(quotaInactiveReason(current, [{ provider: "alpha" }], NOW)).toBeUndefined();
+  });
+
+  test.each([NOW - 30 * 60_000, NOW + 1, -1, Number.NaN])("invalid or exactly expired evidence is unknown: %s", updatedAt => {
+    setCachedProviderQuotaForTests("alpha", exhausted(updatedAt));
+    expect(quotaInactiveReason(config(), [{ provider: "alpha" }], NOW)).toBeUndefined();
+  });
+
   test("a refill clears the field", () => {
     setCachedProviderQuotaForTests("alpha", funded());
     expect(quotaInactiveReason(config(), [{ provider: "alpha" }], NOW)).toBeUndefined();
diff --git a/tests/codex-integration/codex-auth-context.test.ts b/tests/codex-integration/codex-auth-context.test.ts
index 2956c2135e..39e3c45329 100644
--- a/tests/codex-integration/codex-auth-context.test.ts
+++ b/tests/codex-integration/codex-auth-context.test.ts
@@ -73,6 +73,9 @@ import {
   tryAdmitTurn,
 } from "../../src/server/lifecycle";
 import type { CodexModelEntitlementSnapshot } from "../../src/codex/model-entitlements";
+import { recordContextSessionOwner, clearContextSessionOwnersForTests } from "../../src/codex/context-owner";
+import { handleContextHistory } from "../../src/server/context-history";
+import { resetContextRelayActivationForTests } from "../../src/codex/context-compat";
 import { hasForwardableCodexBearer } from "../../src/server/auth-cors";
 import { removeTreeWithRetry } from "../helpers/remove-tree";
 
@@ -102,6 +105,7 @@ beforeEach(() => {
 });
 
 afterEach(() => {
+  resetContextRelayActivationForTests();
   setIcaclsRunnerForTests(null);
   removeTreeWithRetry(testDir);
   clearThreadAccountMap();
@@ -1755,7 +1759,7 @@ describe("Codex auth context", () => {
       });
 
       // Spark owns a separate quota, so Terra can use the same account.
-      await expect(resolveCodexAuthContext(headers, cfg, "pool", { modelId: "gpt-5.4" }))
+      await expect(resolveCodexAuthContext(headers, cfg, "pool", { modelId: "gpt-5.6-terra" }))
         .resolves.toMatchObject({ kind: "pool", accountId: "pool-a" });
       await expect(resolveCodexAuthContext(headers, cfg, "pool", { modelId: "gpt-5.3-codex-spark" }))
         .rejects.toBeInstanceOf(CodexAccountCooldownError);
@@ -1763,12 +1767,12 @@ describe("Codex auth context", () => {
       recordCodexUpstreamOutcome(cfg, "pool-a", 429, {
         now,
         resetAt,
-        modelId: "gpt-5.4",
+        modelId: "gpt-5.6-terra",
       });
 
       // Terra and Luna stay in the shared native quota group, while Spark keeps
       // its independent cooldown instead of being overwritten by Terra's 429.
-      await expect(resolveCodexAuthContext(headers, cfg, "pool", { modelId: "gpt-5.4-mini" }))
+      await expect(resolveCodexAuthContext(headers, cfg, "pool", { modelId: "gpt-5.6-luna" }))
         .rejects.toBeInstanceOf(CodexAccountCooldownError);
       await expect(resolveCodexAuthContext(headers, cfg, "pool", { modelId: "gpt-5.3-codex-spark" }))
         .rejects.toBeInstanceOf(CodexAccountCooldownError);
@@ -1780,7 +1784,7 @@ describe("Codex auth context", () => {
         retryAfter: "60",
         modelId: "gpt-5.3-codex-spark",
       });
-      await expect(resolveCodexAuthContext(headers, cfg, "pool", { modelId: "gpt-5.4" }))
+      await expect(resolveCodexAuthContext(headers, cfg, "pool", { modelId: "gpt-5.6-terra" }))
         .rejects.toBeInstanceOf(CodexAccountCooldownError);
     } finally {
       Date.now = originalNow;
@@ -1813,7 +1817,7 @@ describe("Codex auth context", () => {
       Date.now = () => now;
       // Establish the shared-scope binding first. The Spark fallback below must
       // create a second binding rather than replacing this one.
-      await expect(resolveCodexAuthContext(headers, cfg, "pool", { modelId: "gpt-5.4" }))
+      await expect(resolveCodexAuthContext(headers, cfg, "pool", { modelId: "gpt-5.6-terra" }))
         .resolves.toMatchObject({ kind: "pool", accountId: "pool-a" });
 
       recordCodexUpstreamOutcome(cfg, "pool-a", 429, {
@@ -1825,7 +1829,7 @@ describe("Codex auth context", () => {
       await expect(resolveCodexAuthContext(headers, cfg, "pool", { modelId: "gpt-5.3-codex-spark" }))
         .resolves.toMatchObject({ kind: "pool", accountId: "pool-b" });
       expect(cfg.activeCodexAccountId).toBe("pool-a");
-      await expect(resolveCodexAuthContext(headers, cfg, "pool", { modelId: "gpt-5.4" }))
+      await expect(resolveCodexAuthContext(headers, cfg, "pool", { modelId: "gpt-5.6-terra" }))
         .resolves.toMatchObject({ kind: "pool", accountId: "pool-a" });
       // This second Spark request proves routing retained the peer choice for
       // the Spark affinity instead of relying on an auth-layer substitution.
@@ -1858,7 +1862,7 @@ describe("Codex auth context", () => {
       recordCodexUpstreamOutcome(cfg, "pool-a", 429, {
         now,
         resetAt,
-        modelId: "gpt-5.4",
+        modelId: "gpt-5.6-terra",
       });
 
       const probeAt = now + CODEX_QUOTA_PROBE_INTERVAL_MS;
@@ -1881,7 +1885,7 @@ describe("Codex auth context", () => {
       Date.now = () => probeAt + 1;
       await expect(resolveCodexAuthContext(headers, cfg, "pool", { modelId: "gpt-5.3-codex-spark" }))
         .resolves.toMatchObject({ kind: "pool", accountId: "pool-a" });
-      await expect(resolveCodexAuthContext(headers, cfg, "pool", { modelId: "gpt-5.4-mini" }))
+      await expect(resolveCodexAuthContext(headers, cfg, "pool", { modelId: "gpt-5.6-luna" }))
         .resolves.toMatchObject({ kind: "pool", probeQuotaScope: "shared" });
     } finally {
       Date.now = originalNow;
@@ -2387,3 +2391,52 @@ describe("native-main fence names its gate reason", () => {
     }
   });
 });
+
+
+test("context Direct bearer admission uses real stored-main materialization and fails closed without it", async () => {
+  writeFileSync(join(testDir, "config.toml"), "[features]\ncontext_management.experimental_mode = true\n");
+  resetContextRelayActivationForTests();
+  const cfg = config();
+  cfg.providers.openai = {
+    adapter: "openai-responses", baseUrl: "https://chatgpt.com/backend-api/codex",
+    authMode: "forward", codexAccountMode: "direct",
+  };
+  const token = liveJwt();
+  const admission = { kind: "environment", source: "bearer", contextPrincipalId: "principal-a" } as const;
+  clearContextSessionOwnersForTests();
+  recordContextSessionOwner("principal-a", new Headers({ "session-id": "synthetic-root" }), cfg.providers.openai.baseUrl,
+    { kind: "main", accountId: null }, new Headers({ authorization: `Bearer ${token}`, "chatgpt-account-id": "stored_main_acc" }), true);
+  const request = () => new Request("http://localhost/v1/alpha/notes/v2/read_file", {
+    method: "POST", headers: { authorization: "Bearer ocx_data_test_admission", "openai-beta": "responses=experimental", cookie: "synthetic=private" },
+    body: JSON.stringify({ context: { session_id: "synthetic-root" } }),
+  });
+  const originalFetch = globalThis.fetch;
+  let calls = 0;
+  globalThis.fetch = Object.assign(async (input: string | URL | Request, init?: RequestInit) => {
+    calls++;
+    expect(String(input)).toBe("https://chatgpt.com/backend-api/codex/alpha/notes/v2/read_file");
+    const headers = new Headers(init?.headers);
+    expect(headers.get("authorization")).toBe(`Bearer ${token}`);
+    expect(headers.get("chatgpt-account-id")).toBe("stored_main_acc");
+    expect(headers.get("openai-beta")).toBe("responses=experimental");
+    expect(headers.has("cookie")).toBe(false);
+    return new Response("{}");
+  }, { preconnect: originalFetch.preconnect });
+  try {
+    for (const available of [true, false]) {
+      writeFileSync(join(testDir, "auth.json"), JSON.stringify({ tokens: available ? { access_token: token, account_id: "stored_main_acc" } : {} }));
+      const turn = tryAdmitTurn();
+      expect(turn).not.toBeNull();
+      try {
+        const response = await handleContextHistory(request(), cfg, { model: "context_history", provider: "" }, "alpha/notes/v2/read_file", turn!, admission);
+        expect(response.status).toBe(available ? 200 : 401);
+      } finally {
+        turn?.release();
+      }
+    }
+    expect(calls).toBe(1);
+  } finally {
+    clearContextSessionOwnersForTests();
+    globalThis.fetch = originalFetch;
+  }
+});
diff --git a/tests/codex-integration/codex-catalog-golden.test.ts b/tests/codex-integration/codex-catalog-golden.test.ts
index 35eeb82bbc..2219440790 100644
--- a/tests/codex-integration/codex-catalog-golden.test.ts
+++ b/tests/codex-integration/codex-catalog-golden.test.ts
@@ -38,7 +38,7 @@ describe("codex-catalog golden (pure buildCatalogEntries oracle)", () => {
 
     const entries = buildCatalogEntries(
       template() as unknown as Parameters<typeof buildCatalogEntries>[0],
-      ["gpt-5.5", "gpt-5.4"],
+      ["gpt-5.5", "gpt-5.3-codex-spark"],
       goModels,
       ["gpt-5.5", "kiro/claude-opus-4.6"],
       false,
@@ -73,7 +73,7 @@ describe("codex-catalog golden (pure buildCatalogEntries oracle)", () => {
 
     // Full structural snapshot (the oracle): exact slug set + priority + ws projection.
     expect(projection.map(p => `${p.slug}@${p.priority}`).sort()).toEqual([
-      "gpt-5.4@9",
+      "gpt-5.3-codex-spark@9",
       "gpt-5.5@0",
       "kiro/claude-opus-4.6@1",
       "opencode-go/glm-5.2@5",
diff --git a/tests/codex-integration/codex-catalog-model-picker-order.test.ts b/tests/codex-integration/codex-catalog-model-picker-order.test.ts
index 1bc57c76cc..2d1fb6cc73 100644
--- a/tests/codex-integration/codex-catalog-model-picker-order.test.ts
+++ b/tests/codex-integration/codex-catalog-model-picker-order.test.ts
@@ -150,10 +150,10 @@ describe("modelPickerOrder (#1649)", () => {
   test("the builder leaves a bare native row unchanged before the complete-order pass", () => {
     const entries = buildCatalogEntriesFromObservedState({
       template: template() as never,
-      gptSlugs: ["gpt-5.5", "gpt-5.4"],
+      gptSlugs: ["gpt-5.5", "gpt-5.3-codex-spark"],
       goModels: [{ id: "glm-5.2", provider: "jd-chat", owned_by: "jd" }] as unknown as CatalogModel[],
       featured: [],
-      modelPickerOrder: ["gpt-5.4", "jd-chat/glm-5.2"],
+      modelPickerOrder: ["gpt-5.3-codex-spark", "jd-chat/glm-5.2"],
       wsEnabled: false,
       multiAgentMode: "default",
       exactComboSlugs: new Set(),
@@ -164,7 +164,7 @@ describe("modelPickerOrder (#1649)", () => {
     });
     const p = Object.fromEntries((entries as Record<string, unknown>[]).map(e => [e.slug as string, e.priority as number]));
     // The native row keeps its native priority (9), untouched by modelPickerOrder.
-    expect(p["gpt-5.4"]).toBe(9);
+    expect(p["gpt-5.3-codex-spark"]).toBe(9);
     // The routed row IS placed in the high picker tier.
     expect(p["jd-chat/glm-5.2"]).toBeGreaterThanOrEqual(1000);
   });
diff --git a/tests/codex-integration/codex-catalog-restore.test.ts b/tests/codex-integration/codex-catalog-restore.test.ts
index 1b148daad1..ee215b823b 100644
--- a/tests/codex-integration/codex-catalog-restore.test.ts
+++ b/tests/codex-integration/codex-catalog-restore.test.ts
@@ -1,3 +1,4 @@
+// Holds INV-RESTORE-01 from structure/overview.md; keep the id here if this file is split or renamed.
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { createHash } from "node:crypto";
 import { existsSync, mkdtempSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
@@ -91,7 +92,7 @@ describe("Codex catalog restore", () => {
     writeFileSync(catalogPath, JSON.stringify({
       models: [
         { slug: "gpt-5.5" },
-        { slug: "opencode-go/deepseek-v4-pro" },
+        { slug: "opencode-go/deepseek-v4.1-flash" },
         { slug: "user-native" },
       ],
     }, null, 2) + "\n");
@@ -112,12 +113,12 @@ describe("Codex catalog restore", () => {
     const catalogPath = join(codexHome, "catalog.json");
     writeFileSync(join(codexHome, "config.toml"), 'model_catalog_json = "catalog.json"\n', "utf8");
     writeFileSync(join(opencodexHome, "config.json"), JSON.stringify({
-      disabledModels: ["gpt-5.4", "desktop/gpt-5.5"],
+      disabledModels: ["gpt-5.6-luna", "desktop/gpt-5.5"],
     }), "utf8");
     writeFileSync(catalogPath, JSON.stringify({
       models: [
         { slug: "gpt-5.5", visibility: "hide", priority: 7 },
-        { slug: "gpt-5.4", visibility: "hide" },
+        { slug: "gpt-5.6-luna", visibility: "hide" },
         { slug: "gpt-5.3-codex-spark", visibility: "hide" },
         { slug: "user-native", visibility: "hide" },
         {
@@ -131,7 +132,7 @@ describe("Codex catalog restore", () => {
           opencodex_catalog_kind: "account-selector-v1",
         },
         {
-          slug: "team/gpt-5.4",
+          slug: "team/gpt-5.6-luna",
           visibility: "list",
           opencodex_catalog_kind: "account-selector-v1",
         },
@@ -157,7 +158,7 @@ describe("Codex catalog restore", () => {
       visibility: "list",
       priority: 7,
     });
-    expect(restored.find(model => model.slug === "gpt-5.4")?.visibility).toBe("hide");
+    expect(restored.find(model => model.slug === "gpt-5.6-luna")?.visibility).toBe("hide");
     expect(restored.find(model => model.slug === "gpt-5.3-codex-spark")?.visibility).toBe("hide");
     expect(restored.find(model => model.slug === "user-native")?.visibility).toBe("hide");
     expect(restored.some(model => String(model.slug).includes("/"))).toBe(false);
@@ -197,15 +198,15 @@ describe("Codex catalog restore", () => {
     const backupPath = backupPathForTestCatalog(codexHome, opencodexHome, "catalog.json");
     writeFileSync(join(codexHome, "config.toml"), 'model_catalog_json = "catalog.json"\n', "utf8");
     writeFileSync(backupPath, JSON.stringify({
-      models: [{ slug: "gpt-5.4", visibility: "hide", priority: 50 }],
+      models: [{ slug: "gpt-5.6-luna", visibility: "hide", priority: 50 }],
     }, null, 2) + "\n");
     writeFileSync(catalogPath, JSON.stringify({
       models: [
-        { slug: "gpt-5.4", visibility: "hide", priority: 0 },
+        { slug: "gpt-5.6-luna", visibility: "hide", priority: 0 },
         { slug: "gpt-5.5", visibility: "hide", priority: 7 },
         { slug: "gpt-5.3-codex-spark", visibility: "hide" },
         {
-          slug: "team/gpt-5.4",
+          slug: "team/gpt-5.6-luna",
           visibility: "list",
           opencodex_catalog_kind: "account-selector-v1",
         },
@@ -236,7 +237,7 @@ describe("Codex catalog restore", () => {
     expect(JSON.parse(r.stdout)).toMatchObject({ removed: 4, kept: 3 });
     const restored = JSON.parse(readFileSync(catalogPath, "utf8")).models as Array<Record<string, unknown>>;
     expect(restored).toEqual([
-      { slug: "gpt-5.4", visibility: "hide", priority: 50 },
+      { slug: "gpt-5.6-luna", visibility: "hide", priority: 50 },
       { slug: "gpt-5.5", visibility: "list", priority: 7 },
       { slug: "gpt-5.3-codex-spark", visibility: "hide" },
     ]);
@@ -309,7 +310,7 @@ describe("Codex catalog restore", () => {
     writeFileSync(catalogPath, JSON.stringify({
       models: [
         { slug: "gpt-5.5", priority: 50, base_instructions: "native", visibility: "list" },
-        { slug: "gpt-5.4", priority: 0, base_instructions: "native", visibility: "list" },
+        { slug: "gpt-5.3-codex-spark", priority: 0, base_instructions: "native", visibility: "list" },
       ],
     }, null, 2) + "\n");
 
@@ -332,7 +333,7 @@ describe("Codex catalog restore", () => {
     expect(JSON.parse(r.stdout)).toMatchObject({ added: 0 });
     const synced = JSON.parse(readFileSync(catalogPath, "utf8")).models as Array<Record<string, unknown>>;
     expect(synced.find(m => m.slug === "gpt-5.5")?.priority).toBe(0);
-    expect(synced.find(m => m.slug === "gpt-5.4")?.priority).toBeGreaterThan(100);
+    expect(synced.find(m => m.slug === "gpt-5.3-codex-spark")?.priority).toBeGreaterThan(100);
   }, { timeout: 15_000 });
 
   test("sync advertises documented Codex-native additions omitted by the bundled catalog", () => {
@@ -382,7 +383,7 @@ describe("Codex catalog restore", () => {
           port: 10100,
           providers: {},
           defaultProvider: "openai",
-          subagentModels: ["gpt-5.5", "gpt-5.4", "gpt-5.3-codex-spark", "gpt-5.6-sol"],
+          subagentModels: ["gpt-5.5", "gpt-5.3-codex-spark", "gpt-5.6-sol"],
         });
         console.log(JSON.stringify(result));
       })();
@@ -394,6 +395,8 @@ describe("Codex catalog restore", () => {
     expect(synced.map(m => m.slug)).toContain("gpt-5.6-sol");
     expect(synced.map(m => m.slug)).toContain("gpt-5.6-terra");
     expect(synced.map(m => m.slug)).toContain("gpt-5.6-luna");
-    expect(synced.find(m => m.slug === "gpt-5.4")?.max_context_window).toBe(1_000_000);
+    // gpt-5.4 is no longer a native catalog member, and no surviving native has a 1M window.
+    expect(synced.map(m => m.slug)).not.toContain("gpt-5.4");
+    expect(synced.find(m => m.slug === "gpt-5.3-codex-spark")?.max_context_window).toBe(100_000);
   }, { timeout: 15_000 });
 });
diff --git a/tests/codex-integration/codex-catalog-sync-hardening.test.ts b/tests/codex-integration/codex-catalog-sync-hardening.test.ts
index 21c60d5835..2521067764 100644
--- a/tests/codex-integration/codex-catalog-sync-hardening.test.ts
+++ b/tests/codex-integration/codex-catalog-sync-hardening.test.ts
@@ -115,8 +115,8 @@ describe("Codex catalog sync hardening", () => {
     writeFileSync(catalogPath, JSON.stringify({
       models: [
         nativeEntry("gpt-5.5", 0),
-        nativeEntry("gpt-5.4", 1),
-        nativeEntry("gpt-5.4-mini", 2),
+        nativeEntry("gpt-5.4", 1),            // retired -> drop
+        nativeEntry("gpt-5.4-mini", 2),       // retired -> drop
         nativeEntry("gpt-5.3-codex-spark", 3),
         nativeEntry("gpt-5.6-sol", 4),
         nativeEntry("gpt-5.6-terra", 5),
@@ -136,8 +136,10 @@ describe("Codex catalog sync hardening", () => {
 
     const slugs = (JSON.parse(readFileSync(catalogPath, "utf8")).models as Array<{ slug: string }>).map(m => m.slug);
     expect(slugs).toContain("gpt-5.5");
-    expect(slugs).toContain("gpt-5.4");
-    expect(slugs).toContain("gpt-5.4-mini");
+    // Retired from NATIVE_OPENAI_MODELS. A pinned upstream snapshot row is not catalog
+    // membership, so these drop with the other unsupported gpt-/codex- natives.
+    expect(slugs).not.toContain("gpt-5.4");
+    expect(slugs).not.toContain("gpt-5.4-mini");
     expect(slugs).toContain("gpt-5.3-codex-spark");
     // This isolated fixture has no authenticated ChatGPT roster. The flagship natives list
     // anyway (owner decision 2026-09-04): asking upstream under an adequate client version
@@ -272,13 +274,13 @@ describe("Codex catalog sync hardening", () => {
           auto_compact_token_limit: 115_200,
         },
         {
-          ...nativeEntry("gpt-5.4", 1),
-          comp_hash: "native-5.4-hash",
-          base_instructions: "Native 5.4 instructions",
-          model_messages: { instructions_template: "Native 5.4 instructions" },
+          ...nativeEntry("gpt-5.3-codex-spark", 1),
+          comp_hash: "native-spark-hash",
+          base_instructions: "Native spark instructions",
+          model_messages: { instructions_template: "Native spark instructions" },
           tool_mode: "code_mode_only",
         },
-        nativeEntry("gpt-5.4-mini", 2),
+        nativeEntry("gpt-5.6-luna", 2),
         routedEntry("vendor/stable-model", 5),
         { ...routedEntry("foreign/gpt-5.5", 6), description: "Foreign provider description" },
         {
@@ -370,10 +372,10 @@ describe("Codex catalog sync hardening", () => {
     expect(team?.description).toBe(bare?.description);
     expect(rows.filter(row => row.slug === "team/gpt-5.5")).toHaveLength(1);
     for (const selector of ["desktop", "team"]) {
-      expect(rows.some(row => row.slug === `${selector}/gpt-5.4`)).toBe(true);
-      expect(rows.some(row => row.slug === `${selector}/gpt-5.4-mini`)).toBe(true);
+      expect(rows.some(row => row.slug === `${selector}/gpt-5.3-codex-spark`)).toBe(true);
+      expect(rows.some(row => row.slug === `${selector}/gpt-5.6-luna`)).toBe(true);
     }
-    for (const nativeSlug of ["gpt-5.5", "gpt-5.4"]) {
+    for (const nativeSlug of ["gpt-5.5", "gpt-5.3-codex-spark"]) {
       const native = rows.find(row => row.slug === nativeSlug);
       const qualified = rows.find(row => row.slug === `team/${nativeSlug}`);
       expect(qualified).toMatchObject({
@@ -726,7 +728,7 @@ describe("Codex catalog sync hardening", () => {
     writeFileSync(catalogPath, JSON.stringify({
       models: [
         { ...nativeEntry("gpt-5.5", 0), visibility: "hide" },
-        nativeEntry("gpt-5.4", 1),
+        nativeEntry("gpt-5.3-codex-spark", 1),
       ],
     }, null, 2) + "\n");
 
@@ -740,7 +742,7 @@ describe("Codex catalog sync hardening", () => {
             liveModels: false
           }
         },
-        disabledModels: ["gpt-5.4", "team/gpt-5.5"],
+        disabledModels: ["gpt-5.3-codex-spark", "team/gpt-5.5"],
         codexAccounts: [{ id: "stored-side-account", isMain: false }],
         codexAccountNamespaces: { desktop: "@main", team: "stored-side-account" }
       }).then(res => console.log(JSON.stringify(res)));
@@ -762,7 +764,7 @@ describe("Codex catalog sync hardening", () => {
       visibility: "list",
       opencodex_catalog_kind: "account-selector-v1",
     });
-    expect(rows.find(row => row.slug === "team/gpt-5.4")?.visibility).toBe("hide");
+    expect(rows.find(row => row.slug === "team/gpt-5.3-codex-spark")?.visibility).toBe("hide");
   });
 
   test("default catalog path merges from disk instead of replacing it with bundled rows", () => {
diff --git a/tests/codex-integration/codex-catalog.test.ts b/tests/codex-integration/codex-catalog.test.ts
index b3d263a488..794a92bd50 100644
--- a/tests/codex-integration/codex-catalog.test.ts
+++ b/tests/codex-integration/codex-catalog.test.ts
@@ -1,3 +1,4 @@
+// Holds INV-WS-01 from structure/overview.md; keep the id here if this file is split or renamed.
 import { afterEach, describe, expect, spyOn, test } from "bun:test";
 import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -8,6 +9,7 @@ import { isGpt56NativeSlug } from "../../src/codex/catalog/effort";
 import { nativeOpenAiContextTier, nativeOpenAiMaxInputTokens } from "../../src/codex/catalog";
 import { shouldUpgradeToUpstreamEntry } from "../../src/codex/catalog/metadata";
 import { applyNativeVisibility, augmentRoutedModelsWithMetadata, augmentRoutedModelsWithRegistryOpenAiApiRows, buildCatalogEntries, buildComboCatalogOmission, catalogModelSlug, clampCatalogModelsToCodexSupport, clampEntryToCodexSupportedEfforts, clampedDefaultEffort, CODEX_ACCOUNT_BOUND_CATALOG_KIND, CODEX_NATIVE_ALIAS_CATALOG_KIND, comboCatalogOmissionReason, deriveComboCatalogModel, exactComboCatalogSlugs, filterCatalogVisibleModels, filterSupportedNativeSlugs, gatherRoutedModels as gatherRoutedModelsDirect, isDatedVariantId, isMediaGenerationModelId, loadBundledCodexCatalog, materializeBundledCodexCatalog, mergeCatalogEntriesForSync, NATIVE_DAYBREAK_BLUE_MODEL, NATIVE_GPT6_ASTRA_MODEL, NATIVE_OPENAI_MODELS, nativeDefaultReasoningEffort, nativeInputModalities, nativeOpenAiCapabilitySourceSlug, nativeOpenAiContextWindow, nativeReasoningEfforts, normalizeRoutedCatalogEntry, resetCatalogRuntimeStateForTests, resetOpenAiApiCatalogWarningStateForTests, resolveComboCatalogMember, shouldExposeRoutedModel, upstreamNativeEntry } from "../../src/codex/catalog";
+import { accountBoundNativeOpenAiSlugsBySelector, observedAccountBoundNativeEntries } from "../../src/codex/catalog";
 import { applyProviderConfigHints, fetchProviderModels, mergeConfiguredModelsIntoLiveCatalog } from "../../src/codex/catalog/provider-fetch";
 import {
   CODEX_CUSTOM_MODEL_CATALOG_KIND,
@@ -1171,7 +1173,7 @@ describe("combo catalog capability intersection", () => {
           adapter: "openai-chat",
           baseUrl: "https://nova.example/v1",
           liveModels: false,
-          models: ["codex/gpt-5.6-sol", "codex/gpt-5.4-mini"],
+          models: ["codex/gpt-5.6-sol", "codex/gpt-5.5"],
         },
       },
       combos: {
@@ -1181,11 +1183,14 @@ describe("combo catalog capability intersection", () => {
           displayName: "Nova1 - codex-gpt-5.6-sol",
           targets: [{ provider: "Nova1", model: "codex/gpt-5.6-sol" }],
         },
-        "nova-mini": {
-          alias: "gpt-5.4-mini",
+        // gpt-5.5 stands in for the retired gpt-5.4-mini here: same pinned shape
+        // (272k window, low..xhigh, default medium), and it is still a native, so
+        // the alias has real capabilities to fall back to.
+        "nova-old-ladder": {
+          alias: "gpt-5.5",
           nativeAlias: true,
-          displayName: "Nova1 - codex-gpt-5.4-mini",
-          targets: [{ provider: "Nova1", model: "codex/gpt-5.4-mini" }],
+          displayName: "Nova1 - codex-gpt-5.5",
+          targets: [{ provider: "Nova1", model: "codex/gpt-5.5" }],
         },
       },
     };
@@ -1200,8 +1205,8 @@ describe("combo catalog capability intersection", () => {
       reasoningEfforts: ["low", "medium", "high", "xhigh", "max", "ultra"],
       defaultReasoningEffort: "low",
     });
-    expect(rows.find(row => row.provider === "combo" && row.id === "nova-mini")).toMatchObject({
-      alias: "gpt-5.4-mini",
+    expect(rows.find(row => row.provider === "combo" && row.id === "nova-old-ladder")).toMatchObject({
+      alias: "gpt-5.5",
       nativeAlias: true,
       contextWindow: 272_000,
       maxInputTokens: 272_000,
@@ -2223,16 +2228,16 @@ describe("configured CatalogModel displayName -> catalog display_name", () => {
   test("Command Code routed models relabel the picker row with distinguishable slugs", () => {
     const entries = buildCatalogEntries(nativeTemplate(), [], [
       { provider: "command-code", id: "deepseek/deepseek-v4-flash", owned_by: "command-code" },
-      { provider: "commandcode", id: "deepseek/deepseek-v4-pro", owned_by: "commandcode" },
+      { provider: "commandcode", id: "deepseek/deepseek-v4.1-flash", owned_by: "commandcode" },
     ]);
     const auth = entries.find(e => e.slug === "command-code/deepseek-deepseek-v4-flash");
-    const api = entries.find(e => e.slug === "commandcode/deepseek-deepseek-v4-pro");
+    const api = entries.find(e => e.slug === "commandcode/deepseek-deepseek-v4.1-flash");
 
     // Display-only relabel + redundant vendor-prefix drop: routing slugs stay untouched.
     expect(auth?.display_name).toBe("commandcode-auth/deepseek-v4-flash");
     expect(auth?.slug).toBe("command-code/deepseek-deepseek-v4-flash");
-    expect(api?.display_name).toBe("commandcode-api/deepseek-v4-pro");
-    expect(api?.slug).toBe("commandcode/deepseek-deepseek-v4-pro");
+    expect(api?.display_name).toBe("commandcode-api/deepseek-deepseek-v4.1-flash");
+    expect(api?.slug).toBe("commandcode/deepseek-deepseek-v4.1-flash");
   });
 
   test("Google Antigravity routed models relabel the picker row with compact agy prefix", () => {
@@ -2918,6 +2923,33 @@ describe("legacy custom-model catalog ownership", () => {
     }));
   });
 
+  test("a persisted row for a retired native is not re-observed back into the catalog", () => {
+    const retiredAccountRow = {
+      // A stale on-disk row for a retired native is the one way membership removal can be undone:
+      // an observation admits any native NOT in the supported set, which a retired slug also is not.
+      ...nativeTemplate(),
+      slug: "team/gpt-5.4",
+      display_name: "team / GPT-5.4",
+      supported_in_api: true,
+      opencodex_catalog_kind: CODEX_ACCOUNT_BOUND_CATALOG_KIND,
+    };
+    const retiredBareRow = {
+      ...nativeTemplate(),
+      slug: "gpt-5.4-mini",
+      display_name: "GPT-5.4-Mini",
+      supported_in_api: true,
+    };
+    const bySelector = accountBoundNativeOpenAiSlugsBySelector(
+      { codexAccounts: { team: { accountId: "acct_team" } } } as never,
+      [retiredAccountRow, retiredBareRow] as never,
+    );
+    for (const slugs of bySelector.values()) {
+      expect(slugs).not.toContain("gpt-5.4");
+      expect(slugs).not.toContain("gpt-5.4-mini");
+    }
+    expect(observedAccountBoundNativeEntries([retiredBareRow] as never)).toEqual([]);
+  });
+
   test("legacy evidence cannot claim account-selector or combo rows", () => {
     const account = {
       ...nativeTemplate(),
@@ -3455,18 +3487,28 @@ describe("Codex catalog routed normalization", () => {
     expect(routed?.auto_compact_token_limit).toBe(115_200);
   });
 
-  test("native gpt-5.4 uses its 1M context window override", () => {
+  test("retired gpt-5.4 no longer has a 1M native context override", () => {
+    expect(NATIVE_OPENAI_MODELS).not.toContain("gpt-5.4");
+    expect(NATIVE_OPENAI_MODELS).not.toContain("gpt-5.4-mini");
+    expect(nativeOpenAiContextWindow("gpt-5.4")).toBeUndefined();
+    expect(nativeOpenAiContextWindow("gpt-5.4-mini")).toBeUndefined();
+
+    // gpt-5.4 was the only native 1M override. Nothing replaces it: remaining
+    // natives keep their own windows even when cloned from a 1M template or
+    // given a 2M cap large enough to raise a long-window family.
     const template = {
       ...nativeTemplate(),
       context_window: 272_000,
       max_context_window: 1_000_000,
     };
-    const entries = buildCatalogEntries(template, ["gpt-5.4"], []);
-    const native = entries.find(e => e.slug === "gpt-5.4");
-
-    expect(native?.context_window).toBe(1_000_000);
-    expect(native?.max_context_window).toBe(1_000_000);
-    expect(native?.auto_compact_token_limit).toBe(900_000);
+    const entries = buildCatalogEntries(template, [...NATIVE_OPENAI_MODELS], []);
+    for (const slug of NATIVE_OPENAI_MODELS) {
+      const native = entries.find(e => e.slug === slug);
+      expect(native?.context_window).toBeDefined();
+      expect(native!.context_window as number).toBeLessThan(1_000_000);
+      expect(native!.max_context_window as number).toBeLessThan(1_000_000);
+      expect(nativeOpenAiContextWindow(slug, 2_000_000)).toBeLessThan(1_000_000);
+    }
   });
 
   test("native gpt-5.3-codex-spark uses its 100k context window instead of inherited codex max", () => {
@@ -3636,11 +3678,14 @@ describe("Codex catalog routed normalization", () => {
     expect(luna?.auto_compact_token_limit).toBe(244_800);
   });
 
-  test("preserved gpt-5.4-mini rows get the openai cap without a hardcoded override (#1430)", () => {
+  test("preserved old-ladder native rows get the openai cap; retired gpt-5.4-mini is dropped (#1430)", () => {
     const cap = 200_000;
     const template = nativeTemplate();
-    // gpt-5.4-mini has no NATIVE_OPENAI_CONTEXT_OVERRIDES entry; its windows come
-    // from the preserved disk row and must still be capped on merge.
+    // gpt-5.4-mini is no longer a supported native, so merge drops it
+    // (CANONICAL_NATIVE_CATALOG_CONTENT_POLICY.unsupportedNativeEntries = "drop").
+    // The #1430 cap still applies to a preserved old-ladder native without a
+    // long-window opt-in: gpt-5.5's hardcoded override is 272k/272k, so a 200k
+    // cap must still win.
     const genuine54Mini = {
       ...template,
       slug: "gpt-5.4-mini",
@@ -3649,8 +3694,16 @@ describe("Codex catalog routed normalization", () => {
       max_context_window: 272_000,
       auto_compact_token_limit: 244_800,
     };
+    const genuine55 = {
+      ...template,
+      slug: "gpt-5.5",
+      display_name: "GPT-5.5",
+      context_window: 272_000,
+      max_context_window: 272_000,
+      auto_compact_token_limit: 244_800,
+    };
     const merged = mergeCatalogEntriesForSync(
-      [genuine54Mini],
+      [genuine54Mini, genuine55],
       [],
       new Map(),
       [],
@@ -3668,10 +3721,11 @@ describe("Codex catalog routed normalization", () => {
       new Set(),
       cap,
     );
-    const mini = merged.find(e => e.slug === "gpt-5.4-mini");
-    expect(mini?.context_window).toBe(cap);
-    expect(mini?.max_context_window).toBe(cap);
-    expect(mini?.auto_compact_token_limit).toBe(180_000);
+    expect(merged.find(e => e.slug === "gpt-5.4-mini")).toBeUndefined();
+    const gpt55 = merged.find(e => e.slug === "gpt-5.5");
+    expect(gpt55?.context_window).toBe(cap);
+    expect(gpt55?.max_context_window).toBe(cap);
+    expect(gpt55?.auto_compact_token_limit).toBe(180_000);
   });
 
   test("nativeOpenAiContextWindow applies the openai cap as a ceiling only when provided", () => {
@@ -3681,8 +3735,11 @@ describe("Codex catalog routed normalization", () => {
     expect(nativeOpenAiContextWindow("gpt-5.6-sol", 500_000)).toBe(500_000);
     // A cap ABOVE the native value is a ceiling, not a floor.
     expect(nativeOpenAiContextWindow("gpt-5.6-sol", 2_000_000)).toBe(922_000);
-    // Non-5.6 natives are capped the same way.
-    expect(nativeOpenAiContextWindow("gpt-5.4", 272_000)).toBe(272_000);
+    // Non-5.6 natives have no long-window opt-in: a cap may only lower.
+    expect(nativeOpenAiContextWindow("gpt-5.5", 200_000)).toBe(200_000);
+    expect(nativeOpenAiContextWindow("gpt-5.5", 2_000_000)).toBe(272_000);
+    // The retired 1M native is gone; a cap cannot invent a window for it.
+    expect(nativeOpenAiContextWindow("gpt-5.4", 272_000)).toBeUndefined();
   });
 
   // Owner decision (devlog 260816_.../011 §4-bis): Daybreak Blue is now a GLOBALLY
@@ -4334,41 +4391,43 @@ describe("Codex catalog routed normalization", () => {
       base_instructions: "installed native instructions",
       genuine_marker: "installed-native",
     };
-    const nativeMini = {
+    // The second native is a surviving slug: a retired one would be dropped as an
+    // unsupported native before this test could say anything about adoption.
+    const nativeSpark = {
       ...nativeTemplate(),
-      slug: "gpt-5.4-mini",
-      display_name: "gpt-5.4-mini",
+      slug: "gpt-5.3-codex-spark",
+      display_name: "gpt-5.3-codex-spark",
       priority: 6,
     };
     const routedCursorRows = buildCatalogEntries(nativeTemplate(), [], [
       { provider: "cursor", id: "gpt-5.5", owned_by: "cursor" },
-      { provider: "cursor", id: "gpt-5.4-mini", owned_by: "cursor" },
+      { provider: "cursor", id: "gpt-5.3-codex-spark", owned_by: "cursor" },
     ]);
 
     const merged = mergeCatalogEntriesForSync(
-      [native, nativeMini, { slug: "cursor/old", visibility: "list" }],
+      [native, nativeSpark, { slug: "cursor/old", visibility: "list" }],
       routedCursorRows,
       new Map([
         ["gpt-5.5", 9],
-        ["gpt-5.4-mini", 10],
+        ["gpt-5.3-codex-spark", 10],
       ]),
       [],
       false,
-      new Set(["gpt-5.5", "gpt-5.4-mini"]),
+      new Set(["gpt-5.5", "gpt-5.3-codex-spark"]),
     );
     const slugs = merged.map(entry => entry.slug);
 
     expect(slugs).toContain("gpt-5.5");
-    expect(slugs).toContain("gpt-5.4-mini");
+    expect(slugs).toContain("gpt-5.3-codex-spark");
     expect(slugs).toContain("cursor/gpt-5.5");
-    expect(slugs).toContain("cursor/gpt-5.4-mini");
+    expect(slugs).toContain("cursor/gpt-5.3-codex-spark");
     expect(slugs).not.toContain("cursor/old");
     expect(merged.find(entry => entry.slug === "gpt-5.5")?.priority).toBe(9);
     expect(merged.find(entry => entry.slug === "gpt-5.5")?.base_instructions)
       .toBe("installed native instructions");
     expect(merged.find(entry => entry.slug === "gpt-5.5")?.genuine_marker)
       .toBe("installed-native");
-    expect(merged.find(entry => entry.slug === "gpt-5.4-mini")?.priority).toBe(10);
+    expect(merged.find(entry => entry.slug === "gpt-5.3-codex-spark")?.priority).toBe(10);
   });
 
   test("buildCatalogEntries advertises supports_websockets only on explicit opt-in", () => {
@@ -5986,9 +6045,9 @@ describe("Codex catalog routed normalization", () => {
   test("built-in DeepSeek and GLM effort models opt into Codex reasoning propagation (#1100)", async () => {
     const expected = [
       { slug: "deepseek/deepseek-v4-flash", efforts: ["low", "high", "max", "ultra"] },
-      { slug: "deepseek/deepseek-v4-pro", efforts: ["low", "high", "max", "ultra"] },
+      { slug: "deepseek/deepseek-flash", efforts: ["low", "high", "max", "ultra"] },
       { slug: "opencode-go/deepseek-v4-flash", efforts: ["low", "high", "max"] },
-      { slug: "opencode-go/deepseek-v4-pro", efforts: ["low", "high", "max"] },
+      { slug: "opencode-go/deepseek-v4.1-flash", efforts: ["low", "high", "max"] },
       { slug: "opencode-go/glm-5.2", efforts: ["low", "medium", "high", "xhigh", "max"] },
       { slug: "opencode-go/glm-5.1", efforts: ["low", "medium", "high", "xhigh", "max"] },
       { slug: "opencode-go/glm-5", efforts: ["low", "medium", "high", "xhigh", "max"] },
@@ -6007,7 +6066,7 @@ describe("Codex catalog routed normalization", () => {
           authMode: "key",
           apiKey: "sk-test",
           liveModels: false,
-          models: ["deepseek-v4-flash", "deepseek-v4-pro"],
+          models: ["deepseek-v4-flash", "deepseek-flash"],
         },
         "opencode-go": {
           adapter: "openai-chat",
@@ -6015,7 +6074,7 @@ describe("Codex catalog routed normalization", () => {
           authMode: "key",
           apiKey: "sk-test",
           liveModels: false,
-          models: ["deepseek-v4-flash", "deepseek-v4-pro", "glm-5.2", "glm-5.1", "glm-5"],
+          models: ["deepseek-v4-flash", "deepseek-v4.1-flash", "glm-5.2", "glm-5.1", "glm-5"],
         },
         zai: {
           adapter: "openai-chat",
@@ -6173,7 +6232,7 @@ describe("Codex catalog routed normalization", () => {
 
     expect(provider.modelSupportsReasoningSummaries).toEqual({
       "deepseek-v4-flash": false,
-      "deepseek-v4-pro": true,
+      "deepseek-flash": true,
     });
   });
 
@@ -6950,7 +7009,7 @@ describe("native slug allowlist", () => {
     ];
 
     expect(filterSupportedNativeSlugs(liveModels)).toEqual([
-      "gpt-5.5", "gpt-5.4", "gpt-5.4-mini", "gpt-5.3-codex-spark",
+      "gpt-5.5", "gpt-5.3-codex-spark",
     ]);
   });
 
diff --git a/tests/codex-integration/codex-context-owner.test.ts b/tests/codex-integration/codex-context-owner.test.ts
new file mode 100644
index 0000000000..6c60edbb33
--- /dev/null
+++ b/tests/codex-integration/codex-context-owner.test.ts
@@ -0,0 +1,238 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+import type { CodexAuthContext } from "../../src/codex/auth-context";
+import { clearContextSessionOwnersForTests, contextSessionOwnerMatches,
+  getContextSessionOwner, recordContextSessionOwner } from "../../src/codex/context-owner";
+
+const destination = "https://chatgpt.com/backend-api/codex";
+const principal = "principal-a";
+const start = 1_000_000;
+const root = (id = "root") => new Headers({ "session-id": id, "thread-id": id });
+const outbound = (account: string | null = "physical-a", token = "accepted-a") => new Headers({
+  authorization: `Bearer ${token}`, ...(account === null ? {} : { "chatgpt-account-id": account }),
+});
+const stored = (id = "slot-a", account = "physical-a"): CodexAuthContext => ({
+  kind: "pool", accountId: id, chatgptAccountId: account,
+  accessToken: "accepted-a", generation: 1, writerGeneration: 0, fixedAccount: true,
+});
+const caller: CodexAuthContext = { kind: "main", accountId: null };
+beforeEach(clearContextSessionOwnersForTests);
+
+let issuedTokens = 0;
+const userToken = (user: string | undefined, second?: string) => {
+  const auth: Record<string, string> = {};
+  if (user !== undefined) auth.chatgpt_user_id = user;
+  if (second !== undefined) auth.user_id = second;
+  // iat varies per call so two tokens for the same person are genuinely different credentials,
+  // which is what a refresh looks like and what the fingerprint rules are about.
+  const payload = Buffer.from(JSON.stringify({
+    iat: ++issuedTokens, "https://api.openai.com/auth": auth,
+  }), "utf8").toString("base64url");
+  return `header.${payload}.signature`;
+};
+
+describe("context session ownership", () => {
+  test("another admission principal can neither read nor poison the first principal's session", () => {
+    recordContextSessionOwner(principal, root(), destination, stored(), outbound(), false, start);
+    expect(getContextSessionOwner("principal-b", "root", destination, start)).toBeUndefined();
+    recordContextSessionOwner("principal-b", root(), destination, stored("slot-b", "physical-b"),
+      outbound("physical-b", "accepted-b"), false, start);
+    const first = getContextSessionOwner(principal, "root", destination, start)!;
+    expect(first).toMatchObject({ accountId: "slot-a", ambiguous: false });
+    expect(getContextSessionOwner("principal-b", "root", destination, start))
+      .toMatchObject({ accountId: "slot-b", ambiguous: false });
+  });
+
+  test("a second user inside the same workspace does not inherit the session", () => {
+    const first = outbound("physical-a", userToken("user-a"));
+    const second = outbound("physical-a", userToken("user-b"));
+    recordContextSessionOwner(principal, root(), destination, stored(), first, false, start);
+    const owner = getContextSessionOwner(principal, "root", destination, start)!;
+    expect(contextSessionOwnerMatches(owner, first)).toBe(true);
+    expect(contextSessionOwnerMatches(owner, second)).toBe(false);
+    recordContextSessionOwner(principal, root(), destination, stored(), second, false, start + 1);
+    expect(getContextSessionOwner(principal, "root", destination, start + 1)?.ambiguous).toBe(true);
+  });
+
+  test("a proven user survives a token refresh; without one only the exact credential continues", () => {
+    const issued = outbound("physical-a", userToken("user-a"));
+    recordContextSessionOwner(principal, root(), destination, stored(), issued, false, start);
+    const owner = getContextSessionOwner(principal, "root", destination, start)!;
+    expect(contextSessionOwnerMatches(owner, outbound("physical-a", userToken("user-a")))).toBe(true);
+
+    recordContextSessionOwner(principal, root("bare"), destination, stored(), outbound(), false, start);
+    const bare = getContextSessionOwner(principal, "bare", destination, start)!;
+    expect(contextSessionOwnerMatches(bare, outbound())).toBe(true);
+    expect(contextSessionOwnerMatches(bare, outbound("physical-a", "rotated"))).toBe(false);
+    // A credential that only now starts proving a user is a different fact, not a continuation.
+    expect(contextSessionOwnerMatches(bare, outbound("physical-a", userToken("user-a")))).toBe(false);
+  });
+
+  test("conflicting user claims are never recorded and poison an existing entry", () => {
+    recordContextSessionOwner(principal, root(), destination, stored(),
+      outbound("physical-a", userToken("user-a", "user-b")), false, start);
+    expect(getContextSessionOwner(principal, "root", destination, start)).toBeUndefined();
+
+    recordContextSessionOwner(principal, root("seeded"), destination, stored(),
+      outbound("physical-a", userToken("user-a")), false, start);
+    recordContextSessionOwner(principal, root("seeded"), destination, stored(),
+      outbound("physical-a", userToken("user-a", "user-b")), false, start + 1);
+    expect(getContextSessionOwner(principal, "seeded", destination, start + 1)?.ambiguous).toBe(true);
+  });
+
+  test("an unauthenticated admission owns nothing", () => {
+    recordContextSessionOwner(undefined, root(), destination, stored(), outbound(), false, start);
+    expect(getContextSessionOwner(undefined, "root", destination, start)).toBeUndefined();
+    expect(getContextSessionOwner(principal, "root", destination, start)).toBeUndefined();
+  });
+
+  test("an explicit stored account owns the session independently of routing state", () => {
+    recordContextSessionOwner(principal, root(), destination, stored(), outbound(), false, start);
+    const owner = getContextSessionOwner(principal, "root", destination, start)!;
+    expect(owner).toMatchObject({ kind: "stored", accountId: "slot-a", ambiguous: false });
+    expect(contextSessionOwnerMatches(owner, outbound())).toBe(true);
+    expect(contextSessionOwnerMatches(owner, outbound("physical-b"))).toBe(false);
+    expect(JSON.stringify(owner)).not.toContain("physical-a");
+    expect(JSON.stringify(owner)).not.toContain("accepted-a");
+  });
+
+  test("stored ownership survives token and generation refresh for the same proven user", () => {
+    const issued = outbound("physical-a", userToken("user-a"));
+    const renewed = outbound("physical-a", userToken("user-a"));
+    expect(renewed.get("authorization")).not.toBe(issued.get("authorization"));
+    recordContextSessionOwner(principal, root(), destination, stored(), issued, false, start);
+    const refreshed = { ...stored(), generation: 2, accessToken: "refreshed" } as CodexAuthContext;
+    recordContextSessionOwner(principal, root(), destination, refreshed, renewed, false, start + 1);
+    const owner = getContextSessionOwner(principal, "root", destination, start + 2)!;
+    expect(owner.ambiguous).toBe(false);
+    // A stored credential is minted by the proxy for the account it selected, so either token
+    // of the same proven person is accepted; a different person in that workspace is not.
+    expect(contextSessionOwnerMatches(owner, renewed)).toBe(true);
+    expect(contextSessionOwnerMatches(owner, issued)).toBe(true);
+    expect(contextSessionOwnerMatches(owner, outbound("physical-a", userToken("user-b")))).toBe(false);
+  });
+
+  test("a userless credential cannot rebind an entry by sharing its workspace", () => {
+    recordContextSessionOwner(principal, root(), destination, stored(), outbound(), false, start);
+    recordContextSessionOwner(principal, root(), destination, stored(),
+      outbound("physical-a", "another-userless-token"), false, start + 1);
+    expect(getContextSessionOwner(principal, "root", destination, start + 1)?.ambiguous).toBe(true);
+  });
+
+  test("stored identity must match the accepted outbound account", () => {
+    recordContextSessionOwner(principal, root(), destination, stored(), outbound("physical-b"), false, start);
+    expect(getContextSessionOwner(principal, "root", destination, start)).toBeUndefined();
+    recordContextSessionOwner(principal, root(), destination, stored(), outbound(null), false, start);
+    expect(getContextSessionOwner(principal, "root", destination, start)).toBeUndefined();
+  });
+
+  test("caller-owned credentials remain fenced from proxy or other bearer credentials", () => {
+    recordContextSessionOwner(principal, root(), destination, caller, outbound(), false, start);
+    const owner = getContextSessionOwner(principal, "root", destination, start)!;
+    expect(owner.kind).toBe("caller");
+    expect(contextSessionOwnerMatches(owner, outbound())).toBe(true);
+    expect(contextSessionOwnerMatches(owner, outbound("physical-a", "proxy-secret"))).toBe(false);
+    expect(contextSessionOwnerMatches(owner, outbound("physical-b"))).toBe(false);
+  });
+
+  test("only an accepted same-account model turn authorizes a rotated caller token", () => {
+    const issued = outbound("physical-a", userToken("user-a"));
+    recordContextSessionOwner(principal, root(), destination, caller, issued, false, start);
+    const refreshed = outbound("physical-a", userToken("user-a"));
+    expect(refreshed.get("authorization")).not.toBe(issued.get("authorization"));
+    // Same person, but this bearer has never been accepted upstream for this session.
+    expect(contextSessionOwnerMatches(getContextSessionOwner(principal, "root", destination, start)!, refreshed)).toBe(false);
+    recordContextSessionOwner(principal, root(), destination, caller, refreshed, false, start + 1);
+    const owner = getContextSessionOwner(principal, "root", destination, start + 1)!;
+    expect(owner.ambiguous).toBe(false);
+    expect(contextSessionOwnerMatches(owner, refreshed)).toBe(true);
+    // A caller bearer is not ours to reissue, so the superseded one stops being the credential.
+    expect(contextSessionOwnerMatches(owner, issued)).toBe(false);
+    expect(contextSessionOwnerMatches(owner, outbound())).toBe(false);
+  });
+
+  test("caller without physical identity allows only the exact credential", () => {
+    recordContextSessionOwner(principal, root(), destination, caller, outbound(null), false, start);
+    let owner = getContextSessionOwner(principal, "root", destination, start)!;
+    expect(contextSessionOwnerMatches(owner, outbound(null))).toBe(true);
+    recordContextSessionOwner(principal, root(), destination, caller, outbound(null, "rotated"), false, start + 1);
+    owner = getContextSessionOwner(principal, "root", destination, start + 1)!;
+    expect(owner.ambiguous).toBe(true);
+    expect(contextSessionOwnerMatches(owner, outbound(null, "rotated"))).toBe(false);
+  });
+
+  test("substituted Direct main is stored ownership, not caller ownership", () => {
+    recordContextSessionOwner(principal, root(), destination, caller, outbound(), true, start);
+    expect(getContextSessionOwner(principal, "root", destination, start)).toMatchObject({ kind: "stored", accountId: "__main__" });
+  });
+
+  test("root and child model turns share the root body session lookup", () => {
+    recordContextSessionOwner(principal, root(), destination, stored(), outbound(), false, start);
+    recordContextSessionOwner(principal, new Headers({ "x-codex-parent-thread-id": "root", "session-id": "child" }),
+      destination, stored(), outbound(), false, start + 1);
+    expect(getContextSessionOwner(principal, "root", destination, start + 1)?.ambiguous).toBe(false);
+    expect(getContextSessionOwner(principal, "child", destination, start + 1)).toBeUndefined();
+  });
+
+  test.each(["physical", "kind", "destination"])("conflicting %s remains ambiguous after later writes", conflict => {
+    recordContextSessionOwner(principal, root(), destination, stored(), outbound(), false, start);
+    recordContextSessionOwner(principal, root(), conflict === "destination" ? "https://other.test/codex" : destination,
+      conflict === "kind" ? caller : stored("slot-b", conflict === "physical" ? "physical-b" : "physical-a"),
+      outbound(conflict === "physical" ? "physical-b" : "physical-a"), false, start + 1);
+    recordContextSessionOwner(principal, root(), destination, stored(), outbound(), false, start + 2);
+    const owner = getContextSessionOwner(principal, "root", destination, start + 2)!;
+    expect(owner.ambiguous).toBe(true);
+    expect(contextSessionOwnerMatches(owner, outbound())).toBe(false);
+    expect(getContextSessionOwner(principal, "root", "https://other.test/codex", start + 2)).toBeUndefined();
+  });
+
+  test("destination mismatch cannot bootstrap a new owner", () => {
+    recordContextSessionOwner(principal, root(), destination, stored(), outbound(), false, start);
+    expect(getContextSessionOwner(principal, "root", "https://other.test/codex", start)).toBeUndefined();
+    expect(getContextSessionOwner(principal, "root", destination + "/", start)).toBeDefined();
+  });
+
+  test("a fresh lookup detects conflict after an earlier snapshot was read", () => {
+    recordContextSessionOwner(principal, root(), destination, stored(), outbound(), false, start);
+    const oldOwner = getContextSessionOwner(principal, "root", destination, start)!;
+    recordContextSessionOwner(principal, root(), destination, stored("slot-b", "physical-b"), outbound("physical-b"), false, start + 1);
+    const currentOwner = getContextSessionOwner(principal, "root", destination, start + 1)!;
+    expect(oldOwner.ambiguous).toBe(false);
+    expect(currentOwner.ambiguous).toBe(true);
+    expect(contextSessionOwnerMatches(currentOwner, outbound())).toBe(false);
+  });
+
+  test("expiry and restart lose ownership instead of guessing an active account", () => {
+    recordContextSessionOwner(principal, root(), destination, stored(), outbound(), false, start);
+    expect(getContextSessionOwner(principal, "root", destination, start + 24 * 60 * 60_000)).toBeUndefined();
+    recordContextSessionOwner(principal, root(), destination, stored(), outbound(), false, start);
+    clearContextSessionOwnersForTests();
+    expect(getContextSessionOwner(principal, "root", destination, start)).toBeUndefined();
+  });
+
+  test("LRU capacity evicts the untouched entry, preserving a recently looked-up owner", () => {
+    for (let i = 0; i < 2048; i++) recordContextSessionOwner(principal, root(`root-${i}`), destination, stored(), outbound(), false, start);
+    expect(getContextSessionOwner(principal, "root-0", destination, start + 1)).toBeDefined();
+    recordContextSessionOwner(principal, root("overflow"), destination, stored(), outbound(), false, start + 2);
+    expect(getContextSessionOwner(principal, "root-0", destination, start + 2)).toBeDefined();
+    expect(getContextSessionOwner(principal, "root-1", destination, start + 2)).toBeUndefined();
+  });
+
+  test("byte capacity also bounds long account slots", () => {
+    for (let i = 0; i < 1600; i++) recordContextSessionOwner(principal, root(`root-${i}`), destination,
+      stored("a".repeat(512)), outbound(), false, start);
+    expect(getContextSessionOwner(principal, "root-0", destination, start)).toBeUndefined();
+    expect(getContextSessionOwner(principal, "root-1599", destination, start)).toBeDefined();
+  });
+
+  test("invalid and oversized identifiers never create ownership", () => {
+    for (const id of ["", "bad root", "a".repeat(513)]) {
+      recordContextSessionOwner(principal, root(id), destination, stored(), outbound(), false, start);
+      expect(getContextSessionOwner(principal, id, destination, start)).toBeUndefined();
+    }
+    recordContextSessionOwner(principal, new Headers({ "x-codex-parent-thread-id": "bad root", "session-id": "root" }),
+      destination, stored(), outbound(), false, start);
+    expect(getContextSessionOwner(principal, "root", destination, start)).toBeUndefined();
+    recordContextSessionOwner(principal, root(), "https://x.test/" + "a".repeat(4096), stored(), outbound(), false, start);
+    expect(getContextSessionOwner(principal, "root", destination, start)).toBeUndefined();
+  });
+});
diff --git a/tests/codex-integration/codex-convergence-account-selectors.test.ts b/tests/codex-integration/codex-convergence-account-selectors.test.ts
index ceb34ef6a2..1586978e46 100644
--- a/tests/codex-integration/codex-convergence-account-selectors.test.ts
+++ b/tests/codex-integration/codex-convergence-account-selectors.test.ts
@@ -140,13 +140,13 @@ function generatedRoutedEntry(slug: string, marker?: string): RawEntry {
 }
 
 function nativeMetadataEntry(
-  slug: "gpt-5.5" | "gpt-5.4",
+  slug: "gpt-5.5" | "gpt-5.6-luna",
   baseInstructions: string,
   priority: number,
 ): RawEntry {
   return {
     slug,
-    display_name: slug === "gpt-5.5" ? "GPT-5.5 Live" : "GPT-5.4 Live",
+    display_name: slug === "gpt-5.5" ? "GPT-5.5 Live" : "GPT-5.6-Luna Live",
     description: `${slug} installed metadata`,
     priority,
     visibility: "list",
@@ -201,7 +201,7 @@ function writeAutoReviewModel(value?: string): void {
 
 function autoReviewSeed(routeOverride: string | null = "stale-override"): RawEntry[] {
   return [
-    { ...nativeEntry(), slug: "gpt-5.4", auto_review_model_override: "native-upstream" },
+    { ...nativeEntry(), slug: "gpt-5.5", auto_review_model_override: "native-upstream" },
     {
       ...generatedRoutedEntry("static/deepseek-v4-flash"),
       auto_review_model_override: routeOverride,
@@ -693,7 +693,7 @@ test("retained and convergence writers resolve, clear, reject, and recover auto-
     writeAutoReviewModel();
     writeCatalog(autoReviewSeed());
     catalog = await write(autoReviewConfig(["deepseek-v4-flash"]));
-    expect(catalog.models?.find(entry => entry.slug === "gpt-5.4"))
+    expect(catalog.models?.find(entry => entry.slug === "gpt-5.5"))
       .toHaveProperty("auto_review_model_override", "native-upstream");
     expect(catalog.models?.find(entry => entry.slug === "static/deepseek-v4-flash"))
       .toHaveProperty("auto_review_model_override", null);
@@ -994,19 +994,19 @@ test("generated account rows silently win freshly gathered provider collisions",
 
 test("qualified rows retain the matching installed metadata for each native model", async () => {
   const gpt55Instructions = "Installed instructions unique to GPT-5.5.";
-  const gpt54Instructions = "Installed instructions unique to GPT-5.4.";
+  const lunaInstructions = "Installed instructions unique to GPT-5.6-Luna.";
   writeCatalog([
     nativeMetadataEntry("gpt-5.5", gpt55Instructions, 3),
-    nativeMetadataEntry("gpt-5.4", gpt54Instructions, 4),
+    nativeMetadataEntry("gpt-5.6-luna", lunaInstructions, 4),
   ]);
 
   const catalog = await convergeCatalog(config(true));
   const models = catalog.models ?? [];
 
   expect(models.find(entry => entry.slug === "gpt-5.5")?.base_instructions).toBe(gpt55Instructions);
-  expect(models.find(entry => entry.slug === "gpt-5.4")?.base_instructions).toBe(gpt54Instructions);
+  expect(models.find(entry => entry.slug === "gpt-5.6-luna")?.base_instructions).toBe(lunaInstructions);
   expect(models.find(entry => entry.slug === "team/gpt-5.5")?.base_instructions).toBe(gpt55Instructions);
-  expect(models.find(entry => entry.slug === "team/gpt-5.4")?.base_instructions).toBe(gpt54Instructions);
+  expect(models.find(entry => entry.slug === "team/gpt-5.6-luna")?.base_instructions).toBe(lunaInstructions);
 });
 
 test("a missing supported native is backfilled and restored when the picker is disabled", async () => {
diff --git a/tests/codex-integration/codex-history-provider.test.ts b/tests/codex-integration/codex-history-provider.test.ts
index fbc97238de..972245846f 100644
--- a/tests/codex-integration/codex-history-provider.test.ts
+++ b/tests/codex-integration/codex-history-provider.test.ts
@@ -1,10 +1,11 @@
-import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, utimesSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, utimesSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { Database } from "bun:sqlite";
 import { afterEach, describe, expect, setDefaultTimeout, test } from "bun:test";
 import { classifyRecoverableHistoryError, countPendingOpencodexHistory, historyBackupPathFor, isRecoverableHistoryError, migrateHistoryToOpenai, restoreLegacyOpenaiHistory, restoredUserEventFor, setAfterNoopPendingCountForTests, setAfterStrictHistoryRolloutAppendForTests, setBeforeHistoryApplyTransactionForTests, setBeforeHistoryBackupConsumeForTests, setBeforeStrictHistoryRolloutAppendForTests, setHistoryDbBusyTimeoutForTests, snapshotCodexHistoryNoop, syncCodexHistoryProvider, withHistoryRetry } from "../../src/codex/history-provider";
 import { INVALID_HISTORY_BACKUP_FIXTURES, validHistoryBackupFixture } from "../helpers/codex-history-manifest-fixtures";
+import { preflightCodexHistoryInjection, setHistoryAppendHooksForTests } from "../../src/codex/history-provider";
 
 // Windows CI: a transient file lock can consume the full production 5s busy timeout, tripping
 // bun's 5s default per-test timeout by itself. Fail fast into withHistoryRetry instead.
@@ -15,6 +16,7 @@ setDefaultTimeout(30_000);
 
 const noopSnapshotArtifacts = new Set<string>();
 afterEach(() => {
+  setHistoryAppendHooksForTests(undefined);
   setBeforeHistoryBackupConsumeForTests(undefined);
   setBeforeStrictHistoryRolloutAppendForTests(undefined);
   setAfterStrictHistoryRolloutAppendForTests(undefined);
@@ -101,6 +103,135 @@ function makeFixture({ includeExec = false, includeLegacy = false } = {}) {
 }
 
 describe("Codex history provider sync", () => {
+  test.each(["{broken", "null", "[]", "42", '"text"'])("invalid first record %s is a structured integrity failure", (first) => {
+    const fixture = makeFixture();
+    noopSnapshotArtifacts.add(join(fixture.dbPath,".."));
+    writeFileSync(fixture.rollout, first + "\n");
+    expect(syncCodexHistoryProvider("opencodex",fixture.dbPath,fixture.backupPath)).toMatchObject({failed:true,rows:0,files:0,integrityCode:"history_rollout_record_invalid"});
+    const db = new Database(fixture.dbPath);
+    db.run("UPDATE threads SET model_provider='opencodex'");
+    db.close();
+    expect(restoreLegacyOpenaiHistory(fixture.dbPath)).toMatchObject({failed:true,rows:0,files:0,integrityCode:"history_rollout_record_invalid"});
+    expect(readFileSync(fixture.rollout,"utf8")).toBe(first+"\n");
+  });
+
+  test.each(["beforeWrite", "afterWrite"] as const)("descriptor-bound append refuses path replacement %s", (stage) => {
+    const fixture = makeFixture();
+    noopSnapshotArtifacts.add(join(fixture.dbPath,".."));
+    const replacement=JSON.stringify({ordinal:0,type:"session_meta",payload:{id:"thread-1",history_mode:"paginated",model_provider:"openai"}})+"\n";
+    setHistoryAppendHooksForTests({[stage]:(path:string)=>{
+      if(path!==fixture.rollout)return;
+      renameSync(path,path+".old");
+      writeFileSync(path,replacement);
+    }});
+    expect(syncCodexHistoryProvider("opencodex",fixture.dbPath,fixture.backupPath)).toMatchObject({failed:true,rows:0,integrityCode:"history_rollout_identity_changed"});
+    expect(readFileSync(fixture.rollout,"utf8")).toBe(replacement);
+    const db=new Database(fixture.dbPath,{readonly:true});
+    expect(db.query("SELECT model_provider FROM threads WHERE id='thread-1'").get()).toEqual({model_provider:"openai"});
+    db.close();
+  });
+
+  for (const stage of ["beforeFirstLineOpen", "beforeFirstLineWrite", "afterFirstLineWrite"] as const) {
+    test.each([false, true])(`first-line identity guard preserves replacement (${stage}, strict=%s)`, (strict) => {
+      const fixture = makeFixture();
+      noopSnapshotArtifacts.add(join(fixture.dbPath, ".."));
+      // Leave enough first-line padding for forward provider replacement in place.
+      const raw = readFileSync(fixture.rollout, "utf8");
+      writeFileSync(fixture.rollout, raw.replace('"model_provider":"openai"', '"model_provider":"openai"                '));
+      if (strict) expect(syncCodexHistoryProvider("opencodex", fixture.dbPath, fixture.backupPath).rows).toBe(1);
+      const provider = strict ? "opencodex" : "openai";
+      const replacement = JSON.stringify({ordinal:0,type:"session_meta",payload:{id:"thread-1",history_mode:"paginated",model_provider:provider}}) + "\n";
+      let fired = false;
+      setHistoryAppendHooksForTests({[stage]:(path:string)=>{
+        if(path!==fixture.rollout || fired)return;
+        fired=true;
+        renameSync(path,path+".old");
+        writeFileSync(path,replacement);
+      }});
+      const result=syncCodexHistoryProvider(strict?"openai":"opencodex",fixture.dbPath,fixture.backupPath);
+      expect(fired).toBe(true);
+      expect(result).toMatchObject({failed:true,rows:0,integrityCode:strict?"history_backup_partial_restore":"history_rollout_identity_changed"});
+      expect(readFileSync(fixture.rollout,"utf8")).toBe(replacement);
+      const db=new Database(fixture.dbPath,{readonly:true});
+      expect(db.query("SELECT model_provider FROM threads WHERE id='thread-1'").get()).toEqual({model_provider:provider});
+      db.close();
+      if(strict) expect(existsSync(fixture.backupPath)).toBe(true);
+    });
+  }
+
+  test("late paginated conversion rolls back routing instead of swallowing integrity failure",()=>{
+    const fixture=makeFixture();
+    noopSnapshotArtifacts.add(join(fixture.dbPath,".."));
+    const replacement=JSON.stringify({ordinal:0,type:"session_meta",payload:{id:"thread-1",history_mode:"paginated",model_provider:"openai"}})+"\n";
+    setBeforeHistoryApplyTransactionForTests(()=>writeFileSync(fixture.rollout,replacement));
+    expect(syncCodexHistoryProvider("opencodex",fixture.dbPath,fixture.backupPath)).toMatchObject({failed:true,rows:0,integrityCode:"history_paginated_requires_native_writer"});
+    expect(readFileSync(fixture.rollout,"utf8")).toBe(replacement);
+    const db=new Database(fixture.dbPath,{readonly:true});
+    expect(db.query("SELECT model_provider FROM threads WHERE id='thread-1'").get()).toEqual({model_provider:"openai"});
+    db.close();
+  });
+  test("refuses legacy rows in a migration-capable store before external writes", () => {
+    const fixture = makeFixture();
+    noopSnapshotArtifacts.add(join(fixture.dbPath, ".."));
+    const before = readFileSync(fixture.rollout, "utf8");
+    const db = new Database(fixture.dbPath);
+    db.run("ALTER TABLE threads ADD COLUMN history_mode TEXT DEFAULT 'legacy'");
+    db.close();
+    expect(syncCodexHistoryProvider("opencodex", fixture.dbPath, fixture.backupPath)).toMatchObject({failed:true,rows:0,files:0,integrityCode:"history_paginated_requires_native_writer"});
+    expect(readFileSync(fixture.rollout,"utf8")).toBe(before);
+    expect(existsSync(fixture.backupPath)).toBe(false);
+  });
+  test("injection preflight preserves provider definitions needed by paginated threads", () => {
+    const fixture = makeFixture({ includeLegacy: true });
+    noopSnapshotArtifacts.add(join(fixture.dbPath, ".."));
+    const db = new Database(fixture.dbPath);
+    db.run("ALTER TABLE threads ADD COLUMN history_mode TEXT DEFAULT 'legacy'");
+    db.run("UPDATE threads SET history_mode='paginated' WHERE id='thread-3'");
+    db.close();
+    expect(preflightCodexHistoryInjection(false, false, fixture.dbPath)).toBe("history_paginated_requires_native_writer");
+    expect(preflightCodexHistoryInjection(true, true, fixture.dbPath)).toBe("history_paginated_requires_native_writer");
+    expect(preflightCodexHistoryInjection(true, false, fixture.dbPath)).toBeNull();
+    expect(existsSync(fixture.backupPath)).toBe(false);
+  });
+
+  for (const marker of ["ordinal", "history_mode"] as const) {
+    test(`refuses paginated ${marker} before routing any row or writing a manifest`, () => {
+      const fixture = makeFixture();
+      noopSnapshotArtifacts.add(join(fixture.dbPath, ".."));
+      const records = readFileSync(fixture.rollout, "utf8").trim().split("\n").map(line => JSON.parse(line));
+      if (marker === "ordinal") records.forEach((record, ordinal) => { record.ordinal = ordinal; });
+      else records[0].payload.history_mode = "paginated";
+      const before = records.map(record => JSON.stringify(record)).join("\n") + "\n";
+      writeFileSync(fixture.rollout, before);
+      const result = syncCodexHistoryProvider("opencodex", fixture.dbPath, fixture.backupPath);
+      expect(result).toMatchObject({ rows: 0, files: 0, failed: true, integrityCode: "history_paginated_requires_native_writer" });
+      expect(readFileSync(fixture.rollout, "utf8")).toBe(before);
+      expect(existsSync(fixture.backupPath)).toBe(false);
+      const db = new Database(fixture.dbPath, { readonly: true });
+      expect(db.query("SELECT model_provider FROM threads WHERE id = 'thread-1'").get()).toEqual({ model_provider: "openai" });
+      db.close();
+    });
+  }
+
+  test("preserves a routed paginated rollout and its restore manifest", () => {
+    const fixture = makeFixture();
+    noopSnapshotArtifacts.add(join(fixture.dbPath, ".."));
+    expect(syncCodexHistoryProvider("opencodex", fixture.dbPath, fixture.backupPath).failed).toBeUndefined();
+    const records = readFileSync(fixture.rollout, "utf8").trim().split("\n").map(line => JSON.parse(line));
+    records.forEach((record, ordinal) => { record.ordinal = ordinal; });
+    const before = records.map(record => JSON.stringify(record)).join("\n") + "\n";
+    writeFileSync(fixture.rollout, before);
+    const manifest = readFileSync(fixture.backupPath, "utf8");
+    for (const result of [syncCodexHistoryProvider("openai", fixture.dbPath, fixture.backupPath), restoreLegacyOpenaiHistory(fixture.dbPath)]) {
+      expect(result).toMatchObject({ rows: 0, files: 0, failed: true, integrityCode: "history_paginated_requires_native_writer" });
+    }
+    expect(readFileSync(fixture.rollout, "utf8")).toBe(before);
+    expect(readFileSync(fixture.backupPath, "utf8")).toBe(manifest);
+    const db = new Database(fixture.dbPath, { readonly: true });
+    expect(db.query("SELECT model_provider FROM threads WHERE id = 'thread-1'").get()).toEqual({ model_provider: "opencodex" });
+    db.close();
+  });
+
   test("maps resumable Codex threads to opencodex via the latest session_meta", () => {
     const { dbPath, backupPath, rollout } = makeFixture();
 
diff --git a/tests/codex-integration/codex-inject-integration.test.ts b/tests/codex-integration/codex-inject-integration.test.ts
index 57e83650f1..eb981fe214 100644
--- a/tests/codex-integration/codex-inject-integration.test.ts
+++ b/tests/codex-integration/codex-inject-integration.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, test, beforeEach, afterEach, setDefaultTimeout } from "bun:test";
-import { existsSync, mkdirSync, mkdtempSync, writeFileSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, writeFileSync, readFileSync, realpathSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
@@ -34,10 +34,10 @@ function runInject(codexHome: string, ocxHome: string, configJson = "{}"): { std
   return { stdout: result.stdout?.trim() ?? "", status: result.status ?? 1 };
 }
 
-function runRestore(codexHome: string, ocxHome: string): { stdout: string; status: number } {
+function runRestore(codexHome: string, ocxHome: string, asyncRestore = false): { stdout: string; status: number } {
   const script = `
-    const { restoreNativeCodex } = require("./src/codex/inject");
-    console.log(JSON.stringify(restoreNativeCodex()));
+    const { restoreNativeCodex, restoreNativeCodexAsync } = require("./src/codex/inject");
+    console.log(JSON.stringify(${asyncRestore ? "await restoreNativeCodexAsync()" : "restoreNativeCodex()"}));
   `;
   const result = spawnSync(process.execPath, ["--eval", script], {
     cwd: repoRoot,
@@ -59,8 +59,8 @@ describe("injectCodexConfig integration (Design B)", () => {
   let ocxHome: string;
 
   beforeEach(() => {
-    codexHome = mkdtempSync(join(tmpdir(), "ocx-inject-codex-"));
-    ocxHome = mkdtempSync(join(tmpdir(), "ocx-inject-home-"));
+    codexHome = realpathSync.native(mkdtempSync(join(tmpdir(), "ocx-inject-codex-")));
+    ocxHome = realpathSync.native(mkdtempSync(join(tmpdir(), "ocx-inject-home-")));
   });
 
   afterEach(() => {
@@ -68,6 +68,220 @@ describe("injectCodexConfig integration (Design B)", () => {
     removeTreeWithRetry(ocxHome);
   });
 
+  test.each(["sync", "async"])("manifest-owned native rows refuse restore before artifact changes (%s)", (kind) => {
+    writeFileSync(join(codexHome, "config.toml"), 'model="test"\n');
+    const script = `
+      const fs = require("node:fs");
+      const { join } = require("node:path");
+      const { Database } = require("bun:sqlite");
+      const { injectCodexConfig, restoreNativeCodex, restoreNativeCodexAsync } = require("./src/codex/inject");
+      const { syncCodexHistoryProvider, historyBackupPathFor } = require("./src/codex/history-provider");
+      const { resolveCodexStateDbPath } = require("./src/codex/paths");
+      const enabled = await injectCodexConfig(10100, {});
+      if (!enabled.success) throw new Error("fixture injection failed");
+      const dbPath = join(process.env.CODEX_HOME, "state_5.sqlite");
+      const rollout = join(process.env.CODEX_HOME, "manifest-fixture.jsonl");
+      fs.writeFileSync(rollout, JSON.stringify({type:"session_meta",payload:{id:"fixture",model_provider:"openai",source:"cli"}})+String.fromCharCode(10));
+      const db = new Database(dbPath);
+      db.run("CREATE TABLE threads (id TEXT PRIMARY KEY, rollout_path TEXT, model_provider TEXT, source TEXT, first_user_message TEXT, has_user_event INTEGER)");
+      db.run("INSERT INTO threads VALUES ('fixture', ?, 'openai', 'cli', 'hello', 1)", rollout);
+      const routed = syncCodexHistoryProvider("opencodex", dbPath);
+      if (routed.failed || routed.rows !== 1) throw new Error("fixture history route failed");
+      db.run("UPDATE threads SET model_provider='openai'");
+      db.run("ALTER TABLE threads ADD COLUMN history_mode TEXT DEFAULT 'legacy'");
+      db.close();
+      const backup = historyBackupPathFor(dbPath);
+      const entries = Object.keys(JSON.parse(fs.readFileSync(backup,"utf8")).entries).length;
+      const defaultEntries = Object.keys(JSON.parse(fs.readFileSync(historyBackupPathFor(resolveCodexStateDbPath()),"utf8")).entries).length;
+      const paths = ["config.toml","opencodex.config.toml","opencodex-journal.json"].map(p=>join(process.env.CODEX_HOME,p)).concat([backup,rollout]);
+      const before = paths.map(p=>fs.readFileSync(p,"utf8"));
+      const result = ${kind === "sync" ? "restoreNativeCodex()" : "await restoreNativeCodexAsync()"};
+      console.log(JSON.stringify({entries,defaultEntries,result,preserved:paths.every((p,i)=>fs.readFileSync(p,"utf8")===before[i])}));
+    `;
+    const child = spawnSync(process.execPath, ["--eval", script], {
+      cwd: repoRoot, env: { ...process.env, CODEX_HOME: codexHome, OPENCODEX_HOME: ocxHome },
+      encoding: "utf8", timeout: SPAWN_BUDGET_MS - 5_000,
+    });
+    expect(child.status, child.stderr).toBe(0);
+    const result = JSON.parse(child.stdout);
+    expect(result.entries).toBe(1);
+    expect(result.defaultEntries).toBe(1);
+    expect(result.result.success).toBe(false);
+    expect(result.result.message).toContain("history_paginated_requires_native_writer");
+    expect(result.preserved).toBe(true);
+  });
+
+  // The denial has to be a real filesystem permission. `inject-coordination.ts`
+  // binds `readFileSync` as an ESM named import, so `spyOn(fs, "readFileSync")`
+  // on the child's `require("node:fs")` handle never reached it: the mock
+  // matched nothing and every assertion below passed through an undenied run.
+  // `unreadable` now proves the precondition before anything depends on it.
+  // Root reads a mode-0 file regardless, and Windows chmod only toggles the
+  // read-only bit, so neither can express the permission this test needs.
+  const unreadablePreimages =
+    process.platform === "win32" || process.getuid?.() === 0 ? test.skip : test;
+  unreadablePreimages("unreadable preimages abort capture and remain visible as compensation failures", () => {
+    const script = `
+      const fs = require("node:fs");
+      const { join } = require("node:path");
+      const target = require("./src/codex/paths").CODEX_PROFILE_PATH;
+      const configPath = join(process.env.CODEX_HOME,"config.toml");
+      fs.writeFileSync(configPath,'model="test"');
+      const {injectCodexConfig,restoreNativeCodex,restoreNativeCodexAsync}=require("./src/codex/inject");
+      const initial=await injectCodexConfig(10100,{});
+      if(!initial.success) throw new Error("fixture injection failed");
+      const watched=[configPath,target,join(process.env.CODEX_HOME,"opencodex-journal.json")];
+      const original=watched.map(path=>fs.readFileSync(path,"utf8"));
+      const deny=()=>fs.chmodSync(target,0o000);
+      const allow=()=>fs.chmodSync(target,0o600);
+      const readWatched=()=>{allow();const seen=watched.map(path=>fs.readFileSync(path,"utf8"));deny();return seen;};
+      deny();
+      let unreadable=false;
+      try { fs.readFileSync(target,"utf8"); } catch(error) { unreadable=error.code==="EACCES"; }
+      const {captureCodexPreImages,restoreCodexPreImages}=require("./src/codex/inject-coordination");
+      let captureCode;
+      try { captureCodexPreImages(); } catch(error) { captureCode=error.code; }
+      const outcomes=[];
+      const unchangedAfterEach=[];
+      for(const operation of [()=>restoreNativeCodex(),()=>restoreNativeCodexAsync(),()=>injectCodexConfig(10100,{})]) {
+        try { outcomes.push((await operation()).success===false); }
+        catch(error) { outcomes.push(error.code==="EACCES"); }
+        unchangedAfterEach.push(readWatched().every((bytes,i)=>bytes===original[i]));
+      }
+      const restored=restoreCodexPreImages({config:original[0],profile:original[1],journal:original[2]});
+      const preserved=readWatched().every((bytes,i)=>bytes===original[i]);
+      allow();
+      console.log(JSON.stringify({unreadable,captureCode,restored,outcomes,unchangedAfterEach,preserved}));
+    `;
+    const child = spawnSync(process.execPath, ["--eval", script], {
+      cwd: repoRoot, env: { ...process.env, CODEX_HOME: codexHome, OPENCODEX_HOME: ocxHome },
+      encoding: "utf8", timeout: SPAWN_BUDGET_MS - 5_000,
+    });
+    expect(child.status, child.stderr).toBe(0);
+    expect(JSON.parse(child.stdout)).toEqual({
+      unreadable: true, captureCode: "EACCES", restored: { complete: false, unrestored: ["profile"] }, outcomes: [true, true, true], unchangedAfterEach: [true, true, true], preserved: true,
+    });
+  });
+
+  for (const stage of ["before-preflight", "after-preflight", "after-config", "after-artifacts"]) {
+  test.each([false,true])(`commit-boundary history refusal returns a result after rollback (${stage}, legacy=%s)`,(legacy)=>{
+    const original=legacy ? DESIGN_B_BLOCK+"\n" : 'model="test"\n';
+    writeFileSync(join(codexHome,"config.toml"),original);
+    if(legacy) writeFileSync(join(codexHome,"opencodex.config.toml"),"[invalid profile\n");
+    const script=`
+      const {Database}=require("bun:sqlite");
+      const {join}=require("node:path");
+      const {injectCodexConfig,setBeforeHistoryArtifactCommitForTests,setHistoryArtifactStageForTests}=require("./src/codex/inject");
+      let kind;
+      const migrate=()=>{
+        const db=new Database(join(process.env.CODEX_HOME,"state_5.sqlite"));
+        db.run("CREATE TABLE threads (rollout_path TEXT, model_provider TEXT, history_mode TEXT)");
+        db.run("INSERT INTO threads VALUES ('fixture','opencodex','paginated')");
+        db.close();
+      };
+      setBeforeHistoryArtifactCommitForTests(value=>{
+        kind=value;
+        if (${JSON.stringify(stage)} === "before-preflight") migrate();
+      });
+      setHistoryArtifactStageForTests(value=>{if(value===${JSON.stringify(stage)})migrate();});
+      const result=await injectCodexConfig(10100,{});
+      console.log(JSON.stringify({kind,result}));
+    `;
+    const child=spawnSync(process.execPath,["--eval",script],{cwd:repoRoot,env:{...process.env,CODEX_HOME:codexHome,OPENCODEX_HOME:ocxHome},encoding:"utf8",timeout:SPAWN_BUDGET_MS-5000});
+    expect(child.status).toBe(0);
+    const value=JSON.parse(child.stdout);
+    expect(value.kind).toBe(legacy?"legacy-uncoordinated":"coordinated");
+    expect(value.result).toMatchObject({success:false});
+    expect(value.result.message).toContain("history_paginated_requires_native_writer");
+    expect(readFileSync(join(codexHome,"config.toml"),"utf8")).toBe(original);
+    expect(existsSync(join(codexHome,"opencodex-journal.json"))).toBe(false);
+    if(legacy) expect(readFileSync(join(codexHome,"opencodex.config.toml"),"utf8")).toBe("[invalid profile\n");
+    else expect(existsSync(join(codexHome,"opencodex.config.toml"))).toBe(false);
+  });
+  }
+
+  test.each(["sync", "legacy-uncoordinated", "coordinated"])("config restore failure aborts every later artifact (%s)", (kind) => {
+    const original = kind === "coordinated" ? 'model="test"\n' : DESIGN_B_BLOCK + "\n";
+    writeFileSync(join(codexHome, "config.toml"), original);
+    if (kind !== "coordinated") writeFileSync(join(codexHome, "opencodex.config.toml"), "[invalid profile\n");
+    const catalog = '{"models":[],"sentinel":"preserve"}\n';
+    writeFileSync(join(codexHome, "models_cache.json"), catalog);
+    const script = `
+      const {Database}=require("bun:sqlite");
+      const {join}=require("node:path");
+      const {restoreNativeCodex,restoreNativeCodexAsync,setBeforeRestoreConfigForTests}=require("./src/codex/inject");
+      const readState=${kind === "coordinated" ? 'require("./src/codex/transition-state").readCodexTransitionState' : "()=>null"};
+      const before=readState();
+      let observed;
+      setBeforeRestoreConfigForTests(value=>{
+        observed=value;
+        const db=new Database(join(process.env.CODEX_HOME,"state_5.sqlite"));
+        db.run("CREATE TABLE threads (rollout_path TEXT, model_provider TEXT, history_mode TEXT)");
+        db.run("INSERT INTO threads VALUES ('fixture','opencodex','paginated')");
+        db.close();
+      });
+      const result=${kind === "sync" ? "restoreNativeCodex()" : "await restoreNativeCodexAsync()"};
+      console.log(JSON.stringify({observed,result,before,after:readState()}));
+    `;
+    const child=spawnSync(process.execPath,["--eval",script],{cwd:repoRoot,env:{...process.env,CODEX_HOME:codexHome,OPENCODEX_HOME:ocxHome},encoding:"utf8",timeout:SPAWN_BUDGET_MS-5000});
+    expect(child.status).toBe(0);
+    const value=JSON.parse(child.stdout);
+    expect(value.observed).toBe(kind);
+    expect(value.result.success).toBe(false);
+    if(kind==="coordinated") {
+      // Never advance durable generation/tx state when config restoration fails.
+      expect(value.before.state).toMatchObject({nativeGeneration:0,currentTxId:null});
+      expect(value.after.state).toEqual(value.before.state);
+    }
+    expect(value.result.artifacts.config).toMatchObject({state:"failed",changed:false});
+    for (const artifact of [value.result.artifacts.catalog, value.result.artifacts.history]) {
+      expect(artifact).toMatchObject({state:"skipped",changed:false});
+    }
+    expect(readFileSync(join(codexHome,"config.toml"),"utf8")).toBe(original);
+    expect(readFileSync(join(codexHome,"models_cache.json"),"utf8")).toBe(catalog);
+    expect(existsSync(join(codexHome,"opencodex-journal.json"))).toBe(false);
+    if(kind!=="coordinated") expect(readFileSync(join(codexHome,"opencodex.config.toml"),"utf8")).toBe("[invalid profile\n");
+    else expect(existsSync(join(codexHome,"opencodex.config.toml"))).toBe(false);
+  });
+
+  test.each([false, true])("paginated history preserves config and profile before provider transition (authless=%s)", (authless) => {
+    const original = 'model_provider = "opencodex"\n[model_providers.opencodex]\nname="OpenCodex"\nbase_url="http://127.0.0.1:10100/v1"\nwire_api="responses"\n';
+    const configPath = join(codexHome, "config.toml");
+    const profilePath = join(codexHome, "opencodex.config.toml");
+    writeFileSync(configPath, original);
+    writeFileSync(profilePath, "# preserve profile\n");
+    const rollout = join(codexHome, "fixture.jsonl");
+    const bytes = JSON.stringify({ordinal:0,type:"session_meta",payload:{id:"fixture",history_mode:"paginated",model_provider:"opencodex"}}) + "\n";
+    writeFileSync(rollout, bytes);
+    const db = new Database(join(codexHome, "state_5.sqlite"));
+    db.run("CREATE TABLE threads (id TEXT, rollout_path TEXT, model_provider TEXT, history_mode TEXT)");
+    db.run("INSERT INTO threads VALUES ('fixture', ?, 'opencodex', 'paginated')", rollout);
+    db.close();
+    const result = runInject(codexHome, ocxHome, JSON.stringify({codexDesktopAuthless:authless}));
+    expect(result.status).toBe(0);
+    expect(JSON.parse(result.stdout)).toMatchObject({success:false});
+    expect(result.stdout).toContain("history_paginated_requires_native_writer");
+    expect(readFileSync(configPath,"utf8")).toBe(original);
+    expect(readFileSync(profilePath,"utf8")).toBe("# preserve profile\n");
+    expect(readFileSync(rollout,"utf8")).toBe(bytes);
+    expect(existsSync(join(codexHome,"opencodex-journal.json"))).toBe(false);
+    const restoreScript = `
+      const { restoreNativeCodex, restoreNativeCodexAsync, removeCodexConfig } = require("./src/codex/inject");
+      const results = [restoreNativeCodex(), await restoreNativeCodexAsync(), removeCodexConfig()];
+      console.log(JSON.stringify(results));
+    `;
+    const restored = spawnSync(process.execPath, ["--eval", restoreScript], {
+      cwd: repoRoot, env: { ...process.env, CODEX_HOME: codexHome, OPENCODEX_HOME: ocxHome },
+      encoding: "utf8", timeout: SPAWN_BUDGET_MS - 5_000,
+    });
+    expect(restored.status).toBe(0);
+    for (const outcome of JSON.parse(restored.stdout)) expect(outcome.success).toBe(false);
+    expect(readFileSync(configPath,"utf8")).toBe(original);
+    expect(readFileSync(profilePath,"utf8")).toBe("# preserve profile\n");
+    expect(readFileSync(rollout,"utf8")).toBe(bytes);
+    expect(existsSync(join(codexHome,"opencodex-journal.json"))).toBe(false);
+  });
+
   test("remote target validate-only writes nothing; commit journals client ownership and restores exact preimage", () => {
     const original = '# remote baseline\nmodel_provider = "openai"\n';
     writeFileSync(join(codexHome, "config.toml"), original, "utf8");
@@ -760,7 +974,7 @@ describe("injectCodexConfig integration (Design B)", () => {
     expect(readFileSync(join(codexHome, "config.toml"), "utf8")).toBe(original);
   });
 
-  test("restoreNativeCodex removes a stale journal without changing external provider state", () => {
+  test.each([false,true])("restore removes a stale journal without changing external provider state (async=%s)", (asyncRestore) => {
     const configPath = join(codexHome, "config.toml");
     const config = 'model_provider = "custom"\nmodel = "third-party-model"\n';
     writeFileSync(configPath, config, "utf8");
@@ -782,7 +996,9 @@ describe("injectCodexConfig integration (Design B)", () => {
       id TEXT PRIMARY KEY, rollout_path TEXT NOT NULL, model_provider TEXT NOT NULL,
       source TEXT NOT NULL, first_user_message TEXT NOT NULL, has_user_event INTEGER NOT NULL
     )`);
-    db.run(`INSERT INTO threads VALUES ('thread-custom', ?, 'custom', 'cli', 'hello', 1)`, rolloutPath);
+      db.run(`INSERT INTO threads VALUES ('thread-custom', ?, 'custom', 'cli', 'hello', 1)`, rolloutPath);
+      db.run("ALTER TABLE threads ADD COLUMN history_mode TEXT DEFAULT 'legacy'");
+      db.run("INSERT INTO threads VALUES ('old-routed', ?, 'opencodex', 'cli', 'older', 1, 'paginated')", rolloutPath);
     db.close();
     const dbBefore = readFileSync(dbPath);
 
@@ -795,7 +1011,7 @@ describe("injectCodexConfig integration (Design B)", () => {
       timestamp: new Date().toISOString(),
     }), "utf8");
 
-    const r = runRestore(codexHome, ocxHome);
+      const r = runRestore(codexHome, ocxHome, asyncRestore);
     expect(r.status).toBe(0);
     const result = JSON.parse(r.stdout);
     expect(result.success).toBe(true);
diff --git a/tests/codex-integration/codex-inject.test.ts b/tests/codex-integration/codex-inject.test.ts
index 5208e93653..01518fa445 100644
--- a/tests/codex-integration/codex-inject.test.ts
+++ b/tests/codex-integration/codex-inject.test.ts
@@ -1,7 +1,9 @@
+// Holds INV-TOML-01 from structure/overview.md; keep the id here if this file is split or renamed.
 import { describe, expect, test } from "bun:test";
 import {
   applyEol,
   buildOpenaiBaseUrlLine,
+  buildRealtimeWsBaseUrlLine,
   buildProfileFile,
   buildProviderTableBlock,
   chooseCatalogPathForInjection,
@@ -13,7 +15,7 @@ import {
   stripRootContextWindowOverrides,
   standaloneCodexRoutingTarget,
 } from "../../src/codex/inject";
-import { stripJournaledOpenaiBaseUrl } from "../../src/codex/injected-marker";
+import { OCX_SECTION_MARKER, stripJournaledOpenaiBaseUrl } from "../../src/codex/injected-marker";
 import {
   MANAGED_AGENTS_TABLE_MARKER,
   MANAGED_SUBAGENT_DEFAULT_MARKER,
@@ -737,3 +739,33 @@ describe("EOL boundary helpers (Windows CRLF configs)", () => {
     expect(applyEol(crlf, "\r\n")).toBe(crlf);
   });
 });
+
+test('managed injection is idempotent and retains every unrelated value',()=>{
+ const source=`model = "gpt-6-astra"\n${OCX_SECTION_MARKER}\nopenai_base_url = "http://127.0.0.1:10100/v1"\nservice_tier = "fast"\n[features]\ncontext_management.experimental_mode = true\n[features.multi_agent_v2]\nenabled = true\n`;
+ const target={baseUrl:'http://127.0.0.1:10100/v1',requiresAdmissionToken:false,tokenEnv:'OPENCODEX_API_AUTH_TOKEN' as const};
+ const result=setRootOpenaiBaseUrl(source,target);
+ expect(result.keptUserBaseUrl).toBe(false);
+ expect(result.content).toBe(source.replace('10100/v1','10100/backend-api/codex'));
+ expect(setRootOpenaiBaseUrl(result.content,target).content).toBe(result.content);
+ expect(buildRealtimeWsBaseUrlLine(target)).toContain('10100/v1');
+ expect(setRootOpenaiBaseUrl(source,10100).content).toBe(result.content);
+});
+test('feature disabled and user-owned routing remain intact',()=>{
+ const source='openai_base_url = "http://127.0.0.1:10100/v1"\n[features]\ncontext_management.experimental_mode = true\n';
+ expect(setRootOpenaiBaseUrl(source,10100)).toEqual({content:source,keptUserBaseUrl:true});
+ const managed=`${OCX_SECTION_MARKER}\nopenai_base_url = "http://127.0.0.1:10100/v1"\n[features]\ncontext_management.experimental_mode = false\n`;
+ expect(setRootOpenaiBaseUrl(managed,10100).content).toBe(managed);
+});
+
+
+test("malformed TOML preserves user routing and does not enable context injection", () => {
+  const target = { baseUrl: "http://127.0.0.1:10100/v1", requiresAdmissionToken: false, tokenEnv: "OPENCODEX_API_AUTH_TOKEN" as const };
+  for (const malformed of ['model = "unterminated', '[features]\ncontext_management.experimental_mode = true\nbroken = [']) {
+    const userOwned = `openai_base_url = "https://example.invalid/v1"\n${malformed}\n`;
+    const managed = `${OCX_SECTION_MARKER}\nopenai_base_url = "http://127.0.0.1:10100/v1"\n${malformed}\n`;
+    for (const inject of [(source: string) => setRootOpenaiBaseUrl(source, 10100), (source: string) => setRootOpenaiBaseUrl(source, target)]) {
+      expect(inject(userOwned)).toEqual({ content: userOwned, keptUserBaseUrl: true });
+      expect(inject(managed)).toEqual({ content: managed, keptUserBaseUrl: false });
+    }
+  }
+});
diff --git a/tests/codex-integration/codex-journal.test.ts b/tests/codex-integration/codex-journal.test.ts
index 05d6d14e37..efb6faeb32 100644
--- a/tests/codex-integration/codex-journal.test.ts
+++ b/tests/codex-integration/codex-journal.test.ts
@@ -167,7 +167,11 @@ describe("codex-journal", () => {
     expect(r.status).toBe(0);
     const out = JSON.parse(r.stdout);
     expect(out.result.success).toBe(false);
-    expect(out.result.artifacts.config.state).toBe("failed");
+    expect(out.result.message).toContain("journal recovery was not verified");
+    expect(out.result.artifacts.config).toMatchObject({ state: "failed", changed: false });
+    for (const artifact of [out.result.artifacts.catalog, out.result.artifacts.history]) {
+      expect(artifact).toMatchObject({ state: "skipped", changed: false });
+    }
     expect(out.config).toBe(edited);
     expect(out.journalPreserved).toBe(true);
   });
@@ -515,17 +519,23 @@ describe("codex-journal", () => {
           marker + '\\ndefault_subagent_model',
           marker + '\\n\\ndefault_subagent_model',
         ), "utf8");
-        console.log(JSON.stringify(restoreNativeCodex()));
+        const paths = ["config.toml", "opencodex.config.toml", "opencodex-journal.json"].map(name => path.join(process.env.CODEX_HOME, name));
+        const snapshot = () => paths.map(file => ({ exists: fs.existsSync(file), content: fs.existsSync(file) ? fs.readFileSync(file, "utf8") : null }));
+        const before = snapshot();
+        const result = restoreNativeCodex();
+        console.log(JSON.stringify({ result, before, after: snapshot() }));
       })();
     `);
 
     expect(r.status).toBe(0);
-    const result = JSON.parse(r.stdout);
-    expect(result.success).toBe(false);
-    expect(result.message).toContain("could not be safely removed");
-    expect(result.message).toContain("orphaned managed subagent default marker");
+    const out = JSON.parse(r.stdout);
+    expect(out.result.success).toBe(false);
+    expect(out.result.message).toContain("could not be safely removed");
+    expect(out.result.message).toContain("orphaned managed subagent default marker");
+    expect(out.after).toEqual(out.before);
+    expect(out.result.artifacts.config.state).toBe("failed");
     const after = readFileSync(join(testDir, "config.toml"), "utf8");
-    expect(after).not.toContain("openai_base_url");
+    expect(after).toContain("openai_base_url");
     expect(after).toContain("# Managed by opencodex: native subagent default");
     expect(after).toContain('default_subagent_model = "gpt-5.6-sol"');
     expect(existsSync(join(testDir, "opencodex-journal.json"))).toBe(true);
diff --git a/tests/codex-integration/codex-metadata-integrity.test.ts b/tests/codex-integration/codex-metadata-integrity.test.ts
index c03d03eb8c..ee70d4829e 100644
--- a/tests/codex-integration/codex-metadata-integrity.test.ts
+++ b/tests/codex-integration/codex-metadata-integrity.test.ts
@@ -23,11 +23,11 @@ const poolAuthContext = {
 
 function minimalParsed(): OcxParsedRequest {
   return {
-    modelId: "gpt-5.4",
+    modelId: "gpt-5.6-luna",
     context: { messages: [] },
     stream: false,
     options: {},
-    _rawBody: { model: "gpt-5.4", input: [] },
+    _rawBody: { model: "gpt-5.6-luna", input: [] },
   };
 }
 
@@ -184,7 +184,7 @@ describe("Codex request transport metadata", () => {
 
   test("canonical adapter forwards Lite through selected auth and derives the final wire tier/model", async () => {
     const parsed = minimalParsed();
-    parsed.modelId = "gpt-5.4";
+    parsed.modelId = "gpt-5.6-luna";
     parsed._rawBody = { model: "gpt-5.6-sol", input: [], service_tier: "flex" };
     parsed.options.tierDecision = { kind: "set", value: "priority" };
     const before = JSON.stringify(parsed._rawBody);
@@ -298,7 +298,7 @@ describe("Codex request transport metadata", () => {
     for (const lite of [undefined, "yes", "1", "TRUE", "true, false"]) {
       const headers = new Headers({ "openai-beta": "responses_websockets=existing" });
       if (lite !== undefined) headers.set(liteHeader, lite);
-      const prepared = prepareCodexWsRequest(url, { headers, body: JSON.stringify({ model: "gpt-5.4",
+      const prepared = prepareCodexWsRequest(url, { headers, body: JSON.stringify({ model: "gpt-5.6-luna",
         client_metadata: { [liteKey]: "false", thread_id: "thread-fixture" }, stream: true,
       }) })!;
       expect(JSON.parse(prepared.frameText).client_metadata).toEqual({ [liteKey]: "false", thread_id: "thread-fixture" });
@@ -306,10 +306,10 @@ describe("Codex request transport metadata", () => {
       expect(new Headers(prepared.headers).has("originator")).toBe(false);
       expect(new Headers(prepared.headers).has("user-agent")).toBe(false);
     }
-    const absent = prepareCodexWsRequest(url, { body: '{"model":"gpt-5.4","stream":true}' })!;
+    const absent = prepareCodexWsRequest(url, { body: '{"model":"gpt-5.6-luna","stream":true}' })!;
     expect(JSON.parse(absent.frameText).client_metadata).toBeUndefined();
     const explicit = prepareCodexWsRequest(url, {
-      headers: { [liteHeader]: "true" }, body: '{"model":"gpt-5.4","stream":true}',
+      headers: { [liteHeader]: "true" }, body: '{"model":"gpt-5.6-luna","stream":true}',
     })!;
     expect(JSON.parse(explicit.frameText).client_metadata).toEqual({ [liteKey]: "true" });
   });
@@ -336,7 +336,7 @@ describe("Codex request transport metadata", () => {
       expect(prepareCodexWsRequest(url, { body })).toBeNull();
     }
     for (const client_metadata of [null, [], true, 1, "text", { unrelated: false }, { [liteKey]: true }]) {
-      const init = { body: JSON.stringify({ model: "gpt-5.4", client_metadata }), headers: { [liteHeader]: "true" } };
+      const init = { body: JSON.stringify({ model: "gpt-5.6-luna", client_metadata }), headers: { [liteHeader]: "true" } };
       const before = JSON.stringify(init);
       expect(prepareCodexWsRequest(url, init)).toBeNull();
       expect(JSON.stringify(init)).toBe(before);
@@ -347,8 +347,8 @@ describe("Codex request transport metadata", () => {
     const { applyCodexRoutingHint } = await import("../../src/codex/forward-transport-headers");
     const invalid = ["", " ", "model;service_tier=priority", "model=tier", "a b", "a\t", "a\n", "a\r", "a\0", "a\x7f", "é", null, 42];
     for (const body of [null, [], "text", {}, ...invalid.map(model => ({ model })),
-      ...invalid.map(service_tier => ({ model: "gpt-5.4", service_tier })),
-      { model: "m".repeat(257) }, { model: "gpt-5.4", service_tier: "t".repeat(65) }]) {
+      ...invalid.map(service_tier => ({ model: "gpt-5.6-luna", service_tier })),
+      { model: "m".repeat(257) }, { model: "gpt-5.6-luna", service_tier: "t".repeat(65) }]) {
       const headers = new Headers({ [hintHeader]: "model=stale;service_tier=priority", originator: "unchanged" });
       const before = JSON.stringify(body);
       applyCodexRoutingHint(headers, body);
@@ -359,7 +359,7 @@ describe("Codex request transport metadata", () => {
     const headers = new Headers();
     applyCodexRoutingHint(headers, { model: "m".repeat(256), service_tier: "t".repeat(64) });
     expect(headers.get(hintHeader)).toBe(`model=${"m".repeat(256)};tier=${"t".repeat(64)}`);
-    applyCodexRoutingHint(headers, { model: "gpt-5.4" });
-    expect(headers.get(hintHeader)).toBe("model=gpt-5.4");
+    applyCodexRoutingHint(headers, { model: "gpt-5.6-luna" });
+    expect(headers.get(hintHeader)).toBe("model=gpt-5.6-luna");
   });
 });
diff --git a/tests/codex-integration/codex-pool-rotation.test.ts b/tests/codex-integration/codex-pool-rotation.test.ts
index 1a69a0e269..1f7905a16f 100644
--- a/tests/codex-integration/codex-pool-rotation.test.ts
+++ b/tests/codex-integration/codex-pool-rotation.test.ts
@@ -17,13 +17,16 @@ import {
 } from "../../src/codex/account-priority";
 import {
   clearCodexUpstreamHealth,
+  clearCodexUpstreamHealthForAccount,
   clearThreadAccountMap,
   CODEX_TRANSIENT_SOFT_AVOID_MS,
+  CODEX_THREAD_AFFINITY_REEVAL_INTERVAL_MS,
   previewCodexAccountForRequest,
   getEffectiveActiveCodexAccountId,
   isCodexAccountInCooldown,
   pickAlternateCodexAccount,
   recordCodexUpstreamOutcome,
+  reconcileCodexRoutingHealth,
   resetCodexRoutingForManualSelection,
   resolveCodexAccountForThread,
 } from "../../src/codex/routing";
@@ -60,6 +63,24 @@ function saveTestCredential(id: string): void {
   });
 }
 
+/**
+ * `reconcileCodexRoutingHealth` ignores a generation it has already seen, and the counter is
+ * module state shared by every test in this file, so each call needs a strictly higher one.
+ */
+let sweepGeneration = 9_000_000;
+function generationContext(codexAccountIds: ReadonlySet<string>) {
+  sweepGeneration += 1;
+  return {
+    generation: sweepGeneration,
+    providerNames: new Set<string>(),
+    comboIds: new Set<string>(),
+    comboTargets: new Set<string>(),
+    codexAccountIds,
+    oauthAccountKeys: new Set<string>(),
+    configRoots: new Set<string>(),
+  };
+}
+
 function makeThreeAccountConfig(overrides: Partial<OcxConfig> = {}): OcxConfig {
   const ids = ["a", "b", "c"];
   for (const id of ids) saveTestCredential(id);
@@ -1021,4 +1042,250 @@ describe("selection order across rotation strategies", () => {
     expect(pickAlternateCodexAccount(config, "a", Date.now(), "shared", selectionOptions))
       .toBe(MAIN_CODEX_ACCOUNT_ID);
   });
+
+  describe("an operator selection outranks the pool cursor", () => {
+
+  test.each([true, false])(
+    "cache affinity outranks quota when the flag is %s",
+    (cacheAffinity) => {
+      const config = makeThreeAccountConfig({
+        accountPoolStrategy: "quota",
+        autoSwitchThreshold: 80,
+        activeCodexAccountId: "a",
+        ...(cacheAffinity ? { pool: { cacheAffinity: true } } : {}),
+      } as Partial<OcxConfig>);
+      const threadId = "cache-affine-thread";
+      // Bind the thread while "a" is the natural quota pick, which is how a real conversation
+      // acquires its affinity in the first place.
+      updateAccountQuota("a", 10);
+      updateAccountQuota("b", 50);
+      updateAccountQuota("c", 50);
+      expect(resolveCodexAccountForThread(threadId, config)).toBe("a");
+      // Now "a" is past the threshold but NOT spent, and the siblings have far more room.
+      updateAccountQuota("a", 90);
+      updateAccountQuota("b", 10);
+      updateAccountQuota("c", 10);
+
+      const later = Date.now() + CODEX_THREAD_AFFINITY_REEVAL_INTERVAL_MS + 1;
+      const served = resolveCodexAccountForThread(threadId, config, later);
+      if (cacheAffinity) {
+        // c-4: the cache-affine account is chosen over the higher-headroom one. The prompt
+        // cache lives on "a"; crossing a threshold is a hint, not evidence "a" cannot serve.
+        expect(served).toBe("a");
+      } else {
+        // Flag off is byte-identical to today: the thread moves at the threshold.
+        expect(served).not.toBe("a");
+      }
+    },
+  );
+
+  test("a bound thread still leaves an account that is genuinely spent", () => {
+    const config = makeThreeAccountConfig({
+      accountPoolStrategy: "quota",
+      autoSwitchThreshold: 80,
+      activeCodexAccountId: "a",
+      pool: { cacheAffinity: true },
+    } as Partial<OcxConfig>);
+    updateAccountQuota("a", 10);
+    updateAccountQuota("b", 10);
+    updateAccountQuota("c", 10);
+
+    const threadId = "spent-account-thread";
+    expect(resolveCodexAccountForThread(threadId, config)).toBe("a");
+
+    // Fully spent, not merely busy. This is the half that keeps the change a REORDERING rather
+    // than a pin: affinity outranks quota, it does not outrank exhaustion.
+    updateAccountQuota("a", 100);
+    const later = Date.now() + CODEX_THREAD_AFFINITY_REEVAL_INTERVAL_MS + 1;
+    expect(resolveCodexAccountForThread(threadId, config, later)).not.toBe("a");
+  });
+
+  test("preview and resolve agree under cache affinity", () => {
+    const config = makeThreeAccountConfig({
+      accountPoolStrategy: "quota",
+      autoSwitchThreshold: 80,
+      activeCodexAccountId: "a",
+      pool: { cacheAffinity: true },
+    } as Partial<OcxConfig>);
+    const threadId = "preview-agrees-thread";
+    updateAccountQuota("a", 10);
+    updateAccountQuota("b", 50);
+    updateAccountQuota("c", 50);
+    expect(resolveCodexAccountForThread(threadId, config)).toBe("a");
+    updateAccountQuota("a", 90);
+    updateAccountQuota("b", 10);
+    updateAccountQuota("c", 10);
+    const later = Date.now() + CODEX_THREAD_AFFINITY_REEVAL_INTERVAL_MS + 1;
+    // Two copies of the same rule live in this file; a preview that disagreed with the final
+    // answer would hand subagent fallback a different account than the request actually uses.
+    expect(previewCodexAccountForRequest(threadId, config, later)).toBe("a");
+    expect(resolveCodexAccountForThread(threadId, config, later)).toBe("a");
+  });
+
+    test("the pool moves, then a manual pick wins the next unbound dispatch", () => {
+      const config = makeThreeAccountConfig({
+        accountPoolStrategy: "round-robin",
+        accountPoolStickyLimit: 1,
+        activeCodexAccountId: "a",
+      });
+      updateAccountQuota("a", 10);
+      updateAccountQuota("b", 20);
+      updateAccountQuota("c", 30);
+
+      // Let the pool move the runtime cursor off the operator account.
+      const first = resolveCodexAccountForThread(null, config)!;
+      recordCodexUpstreamOutcome(config, first, 429);
+      const promoted = getEffectiveActiveCodexAccountId(config);
+      expect(promoted).not.toBe(first);
+
+      // The operator now selects the third account, one the pool did not choose and that
+      // carries no cooldown. Before this feature the runtime cursor kept winning and the
+      // next dispatch still served the pool account, which is the defect this phase fixes.
+      const chosen = ["a", "b", "c"].find(id => id !== first && id !== promoted)!;
+      config.activeCodexAccountId = chosen;
+      resetCodexRoutingForManualSelection(chosen);
+
+      expect(getEffectiveActiveCodexAccountId(config)).toBe(chosen);
+      expect(resolveCodexAccountForThread(null, config)).toBe(chosen);
+    });
+
+    // The three tests below are the ones that carry the feature. Each was driven red against
+    // the parent branch first: an assertion that passes with the production change reverted
+    // proves nothing, and the first draft of this block was exactly that — three tests that
+    // all passed without the guard, because they only re-asserted what
+    // resetCodexRoutingForManualSelection and the exempt failover promote already did.
+    test("an over-threshold operator account is served around, not replaced", () => {
+      const config = makeThreeAccountConfig({
+        accountPoolStrategy: "fill-first",
+        activeCodexAccountId: "a",
+        autoSwitchThreshold: 80,
+      });
+      // The operator's account is past the switch threshold, so fill-first advances off it.
+      // This is the ordinary case the report was about: the account the operator chose is
+      // temporarily spent, not wrong.
+      updateAccountQuota("a", 90);
+      updateAccountQuota("b", 10);
+      updateAccountQuota("c", 10);
+      resetCodexRoutingForManualSelection("a");
+
+      const served = resolveCodexAccountForThread(null, config)!;
+      expect(served).not.toBe("a");
+
+      // Serving the request from another account is the pool doing its job. Writing that
+      // account over the operator's selection is not: when a's window rolls over there
+      // would be nothing left pointing back at it. Without the guard this reads `served`.
+      expect(getEffectiveActiveCodexAccountId(config)).toBe("a");
+    });
+
+    test("a successful dispatch spends the one-shot so the pool may move again", () => {
+      const config = makeThreeAccountConfig({
+        accountPoolStrategy: "fill-first",
+        activeCodexAccountId: "a",
+        autoSwitchThreshold: 80,
+      });
+      updateAccountQuota("a", 10);
+      updateAccountQuota("b", 10);
+      updateAccountQuota("c", 10);
+      resetCodexRoutingForManualSelection("a");
+      expect(resolveCodexAccountForThread(null, config)).toBe("a");
+
+      // The operator got what they asked for, so the hold is released. Without a consume
+      // site the preference is permanent and the cursor could never move again — measured:
+      // guard without consume fails 15 of the 69 rotation tests in this file.
+      recordCodexUpstreamOutcome(config, "a", 200);
+
+      updateAccountQuota("a", 90);
+      const served = resolveCodexAccountForThread(null, config)!;
+      expect(served).not.toBe("a");
+      expect(getEffectiveActiveCodexAccountId(config)).toBe(served);
+    });
+
+    test("deleting the preferred account releases the hold", () => {
+      const config = makeThreeAccountConfig({
+        accountPoolStrategy: "round-robin",
+        accountPoolStickyLimit: 1,
+        activeCodexAccountId: "a",
+      });
+      updateAccountQuota("a", 10);
+      updateAccountQuota("b", 20);
+      updateAccountQuota("c", 30);
+      resetCodexRoutingForManualSelection("a");
+
+      // Delete is the operator exit with no reconcile behind it: the account can never
+      // succeed again, so nothing else would ever spend the one-shot. The account-lifecycle
+      // delete path reaches routing through exactly this call.
+      config.codexAccounts = config.codexAccounts!.filter(account => account.id !== "a");
+      config.activeCodexAccountId = undefined;
+      clearCodexUpstreamHealthForAccount("a");
+
+      const served = resolveCodexAccountForThread(null, config)!;
+      expect(served).not.toBe("a");
+      // Without the revocation the preference outlives its account and blocks every write,
+      // so the effective active stays empty and the pool can never commit a replacement.
+      expect(getEffectiveActiveCodexAccountId(config)).toBe(served);
+    });
+
+    test("the generation sweep drops a preference whose account is gone", () => {
+      const config = makeThreeAccountConfig({
+        accountPoolStrategy: "fill-first",
+        activeCodexAccountId: "a",
+        autoSwitchThreshold: 80,
+      });
+      updateAccountQuota("a", 10);
+      updateAccountQuota("b", 10);
+      updateAccountQuota("c", 10);
+      resetCodexRoutingForManualSelection("a");
+
+      // The other removal path: an account edited out of the config by something the runtime
+      // never observed, so no delete call ever reached routing. The sweep is the only thing
+      // standing between that and a preference that can never be spent.
+      reconcileCodexRoutingHealth(generationContext(new Set(["b", "c"])));
+
+      config.codexAccounts = config.codexAccounts!.filter(account => account.id !== "a");
+      config.activeCodexAccountId = undefined;
+      const served = resolveCodexAccountForThread(null, config)!;
+      expect(served).not.toBe("a");
+      expect(getEffectiveActiveCodexAccountId(config)).toBe(served);
+    });
+
+    test("the generation sweep keeps a preference whose account is still live", () => {
+      const config = makeThreeAccountConfig({
+        accountPoolStrategy: "fill-first",
+        activeCodexAccountId: "a",
+        autoSwitchThreshold: 80,
+      });
+      updateAccountQuota("a", 90);
+      updateAccountQuota("b", 10);
+      updateAccountQuota("c", 10);
+      resetCodexRoutingForManualSelection("a");
+
+      // The half that makes the sweep a sweep rather than a reset: "a" is over threshold and
+      // is about to be routed around, but it is still in the roster, so the operator's
+      // selection has to survive.
+      reconcileCodexRoutingHealth(generationContext(new Set(["a", "b", "c"])));
+
+      const served = resolveCodexAccountForThread(null, config)!;
+      expect(served).not.toBe("a");
+      expect(getEffectiveActiveCodexAccountId(config)).toBe("a");
+    });
+
+    test("a 429 on the preferred account still promotes away from it", () => {
+      const config = makeThreeAccountConfig({
+        accountPoolStrategy: "round-robin",
+        accountPoolStickyLimit: 1,
+        activeCodexAccountId: "a",
+      });
+      updateAccountQuota("a", 10);
+      updateAccountQuota("b", 20);
+      updateAccountQuota("c", 30);
+      resetCodexRoutingForManualSelection("a");
+
+      // The failover promote is exempt from the preference guard on purpose: it only runs
+      // because the account in use just failed, so it is never an automatic pick competing
+      // with the operator. Guarding it would trap routing on a cooled account.
+      recordCodexUpstreamOutcome(config, "a", 429);
+      expect(isCodexAccountInCooldown("a")).toBe(true);
+      expect(getEffectiveActiveCodexAccountId(config)).not.toBe("a");
+    });
+  });
 });
diff --git a/tests/codex-integration/codex-quota-auto-refresh-main-admission.test.ts b/tests/codex-integration/codex-quota-auto-refresh-main-admission.test.ts
index 88080d5a4d..204436b3a8 100644
--- a/tests/codex-integration/codex-quota-auto-refresh-main-admission.test.ts
+++ b/tests/codex-integration/codex-quota-auto-refresh-main-admission.test.ts
@@ -287,7 +287,7 @@ describe("quota auto-refresh native-main admission", () => {
     });
     await runCodexQuotaAutoRefresh(cfg, now, { persistCompleted: recordMarkers });
     expect(calls).toEqual([responsesUrl, responsesUrl]);
-    expect(models).toEqual(["gpt-5.4-mini", "gpt-5.5"]);
+    expect(models).toEqual(["gpt-5.6-luna", "gpt-5.5"]);
     expect(cfg.codexQuotaAutoRefresh?.[MAIN]?.lastWeeklyResetAt).toBe(RESET_MILLISECONDS);
     expect(getNativeMainProfileRequestCount()).toBe(0);
   });
diff --git a/tests/codex-integration/codex-quota-parser-parity.test.ts b/tests/codex-integration/codex-quota-parser-parity.test.ts
index 353d5e0ed6..c0865549ac 100644
--- a/tests/codex-integration/codex-quota-parser-parity.test.ts
+++ b/tests/codex-integration/codex-quota-parser-parity.test.ts
@@ -6,10 +6,19 @@ import {
   parseUpstreamQuotaHeaders,
   parseUsageQuota,
   setAccountQuotaFromParsed,
+  updateAccountQuota,
 } from "../../src/codex/quota";
 import { codexPoolQuotaEvidence } from "../../src/routing/quota";
 
 describe("Spark quota survives partial header updates", () => {
+  it.each([1, 1000])("legacy quota updates expire short reset units (divisor %s)", divisor => {
+    clearAccountQuota();
+    setAccountQuotaFromParsed("legacy-expiry", { shortPercent: 4,
+      shortResetAt: (Date.now() - 60_000) / divisor, shortWindowSeconds: 18_000 });
+    updateAccountQuota("legacy-expiry", 29);
+    expect(getAccountQuota("legacy-expiry")).toEqual({ weeklyPercent: 29, updatedAt: expect.any(Number) });
+  });
+
   it("keeps the WHAM Spark window when an ordinary response updates standard quota", () => {
     clearAccountQuota();
     const refreshed = parseUsageQuota({
@@ -124,6 +133,141 @@ describe("Spark-model header responses attribute the 5h window to the model limi
     expect(getAccountQuota("legacy-5h")?.shortPercent).toBe(97);
     expect(getAccountQuota("legacy-5h")?.shortWindowSeconds).toBe(18_000);
   });
+
+  it("drops an elapsed account-level short tuple when a Spark refresh omits the account short slot", () => {
+    // #4122 stopped new Spark writes into short*, but mergeAccountQuota kept carrying the
+    // already-polluted tuple and rewriting updatedAt, so the six-hour disk TTL never fired.
+    clearAccountQuota();
+    setAccountQuotaFromParsed("spark-stale", {
+      weeklyPercent: 29,
+      weeklyResetAt: 1789436116,
+      shortPercent: 4,
+      shortObservedAt: 1788956674678,
+      shortResetAt: 1788974652,
+      shortWindowSeconds: 18_000,
+    });
+    applyAccountQuotaFromUpstreamHeaders("spark-stale", new Headers(SPARK_HEADERS), undefined, undefined, {
+      modelId: "gpt-5.3-codex-spark",
+    });
+    const quota = getAccountQuota("spark-stale");
+    expect(quota?.shortPercent).toBeUndefined();
+    expect(quota?.shortResetAt).toBeUndefined();
+    expect(quota?.shortObservedAt).toBeUndefined();
+    expect(quota?.shortWindowSeconds).toBeUndefined();
+    expect(quota?.weeklyPercent).toBe(21);
+    expect(quota?.customWindows).toEqual([{ label: "GPT-5.3-Codex-Spark 5h", percent: 4, resetAt: 1788974652 }]);
+  });
+
+  it("drops an elapsed account-level short tuple on a WHAM weekly+Spark refresh", () => {
+    // Live path for the 2026-09-12 Pro row: WHAM reports weekly primary + Spark additional
+    // limits and never rewrites shortObservedAt, so merge must drop the elapsed carry.
+    clearAccountQuota();
+    setAccountQuotaFromParsed("wham-stale", {
+      weeklyPercent: 29,
+      shortPercent: 4,
+      shortObservedAt: 1788956674678,
+      shortResetAt: 1788974652,
+      shortWindowSeconds: 18_000,
+    });
+    const refreshed = parseUsageQuota({
+      plan_type: "pro",
+      rate_limit: { primary_window: { used_percent: 29, limit_window_seconds: 604_800, reset_at: 1789436116 } },
+      additional_rate_limits: [{
+        metered_feature: "codex_bengalfox",
+        limit_name: "GPT-5.3-Codex-Spark",
+        rate_limit: {
+          primary_window: { used_percent: 0, reset_at: 1789200311, limit_window_seconds: 18_000 },
+          secondary_window: { used_percent: 2, reset_at: 1789561452, limit_window_seconds: 604_800 },
+        },
+      }],
+    });
+    setAccountQuotaFromParsed("wham-stale", refreshed);
+    const quota = getAccountQuota("wham-stale");
+    expect(quota?.shortPercent).toBeUndefined();
+    expect(quota?.shortResetAt).toBeUndefined();
+    expect(quota?.shortObservedAt).toBeUndefined();
+    expect(quota?.shortWindowSeconds).toBeUndefined();
+    expect(quota?.weeklyPercent).toBe(29);
+    expect(quota?.customWindows?.map(window => window.label)).toEqual([
+      "GPT-5.3-Codex-Spark 5h",
+      "GPT-5.3-Codex-Spark Weekly",
+    ]);
+  });
+
+  it("drops an elapsed account-level short tuple on a weekly-only refresh", () => {
+    clearAccountQuota();
+    const elapsedSec = Math.floor(Date.now() / 1000) - 60;
+    setAccountQuotaFromParsed("pro-stale", {
+      weeklyPercent: 29,
+      shortPercent: 4,
+      shortObservedAt: Date.now() - 3 * 60 * 60_000,
+      shortResetAt: elapsedSec,
+      shortWindowSeconds: 18_000,
+    });
+    applyAccountQuotaFromUpstreamHeaders("pro-stale", new Headers({
+      "x-codex-primary-used-percent": "31",
+      "x-codex-primary-window-minutes": "10080",
+    }));
+    const quota = getAccountQuota("pro-stale");
+    expect(quota?.shortPercent).toBeUndefined();
+    expect(quota?.shortResetAt).toBeUndefined();
+    expect(quota?.shortWindowSeconds).toBeUndefined();
+    expect(quota?.weeklyPercent).toBe(31);
+  });
+
+  it("keeps a still-open account-level short window across a weekly-only refresh", () => {
+    clearAccountQuota();
+    const futureSec = Math.floor(Date.now() / 1000) + 3600;
+    setAccountQuotaFromParsed("plus-live", {
+      weeklyPercent: 4,
+      shortPercent: 0,
+      shortObservedAt: Date.now(),
+      shortResetAt: futureSec,
+      shortWindowSeconds: 18_000,
+    });
+    applyAccountQuotaFromUpstreamHeaders("plus-live", new Headers({
+      "x-codex-primary-used-percent": "5",
+      "x-codex-primary-window-minutes": "10080",
+    }));
+    const quota = getAccountQuota("plus-live");
+    expect(quota?.shortPercent).toBe(0);
+    expect(quota?.shortResetAt).toBe(futureSec);
+    expect(quota?.shortWindowSeconds).toBe(18_000);
+    expect(quota?.weeklyPercent).toBe(5);
+  });
+
+  it("still stores an explicit incoming short tuple even when its reset is already elapsed", () => {
+    clearAccountQuota();
+    const elapsedSec = Math.floor(Date.now() / 1000) - 60;
+    setAccountQuotaFromParsed("incoming-elapsed", {
+      shortPercent: 100,
+      shortResetAt: elapsedSec,
+      shortWindowSeconds: 18_000,
+    });
+    const quota = getAccountQuota("incoming-elapsed");
+    expect(quota?.shortPercent).toBe(100);
+    expect(quota?.shortResetAt).toBe(elapsedSec);
+    expect(quota?.shortWindowSeconds).toBe(18_000);
+  });
+
+  it("drops an elapsed short tuple on a credits-only update", () => {
+    clearAccountQuota();
+    const elapsedSec = Math.floor(Date.now() / 1000) - 60;
+    setAccountQuotaFromParsed("credits-stale", {
+      weeklyPercent: 29,
+      shortPercent: 4,
+      shortObservedAt: Date.now() - 3 * 60 * 60_000,
+      shortResetAt: elapsedSec,
+      shortWindowSeconds: 18_000,
+    });
+    setAccountQuotaFromParsed("credits-stale", { resetCredits: 2 });
+    const quota = getAccountQuota("credits-stale");
+    expect(quota?.shortPercent).toBeUndefined();
+    expect(quota?.shortResetAt).toBeUndefined();
+    expect(quota?.shortWindowSeconds).toBeUndefined();
+    expect(quota?.weeklyPercent).toBe(29);
+    expect(quota?.resetCredits).toBe(2);
+  });
 });
 
 /**
diff --git a/tests/codex-integration/codex-quota-rejection.test.ts b/tests/codex-integration/codex-quota-rejection.test.ts
index f413e6bb4b..f9a44a4748 100644
--- a/tests/codex-integration/codex-quota-rejection.test.ts
+++ b/tests/codex-integration/codex-quota-rejection.test.ts
@@ -1,7 +1,12 @@
 import { describe, expect, test } from "bun:test";
 import { classifyCodexPreStreamRejection } from "../../src/codex/quota-rejection";
 import { BOUNDED_BODY_MAX_BYTES } from "../../src/lib/bounded-body";
-import { consumeComboFailure, shouldRetryCodexPoolAccountQuota } from "../../src/server/responses/core";
+import {
+  consumeComboFailure,
+  shouldRetryCodexPoolAccountQuota,
+  shouldRetryCodexPoolAccountTransient,
+} from "../../src/server/responses/core";
+import { markResponseNonReplayable } from "../../src/lib/upstream-retry";
 
 function jsonRejection(status: number, error: Record<string, unknown>): Response {
   return Response.json({ error }, { status });
@@ -91,6 +96,38 @@ describe("Codex pre-stream quota rejection classification", () => {
     await expect(shouldRetryCodexPoolAccountQuota(response)).resolves.toBe(false);
   });
 
+  test.each([
+    [500, true],
+    [502, true],
+    [503, true],
+    [504, true],
+    [520, true],
+    [507, false],
+    [429, false],
+    [400, false],
+    [200, false],
+  ])("selects transient pool-account retries by HTTP %i", (status, expected) => {
+    expect(shouldRetryCodexPoolAccountTransient(new Response(null, { status }))).toBe(expected);
+  });
+
+  test("a server_is_overloaded 503 moves to another account even though it carries no quota evidence", () => {
+    // The shape that wedged a live pool: the backend refuses in under a second, the body says
+    // nothing about quota, and the account keeps winning selection because nothing recorded a
+    // failure against it.
+    const response = Response.json({
+      error: { type: "server_error", code: "server_is_overloaded", message: "server is overloaded" },
+    }, { status: 503 });
+    expect(shouldRetryCodexPoolAccountTransient(response)).toBe(true);
+  });
+
+  test("a non-replayable gateway status is never sent from a second account", () => {
+    // The body already reached the origin, so a second send could duplicate a turn it may
+    // still be running. This is the one 5xx that stays put.
+    const response = new Response(null, { status: 502 });
+    markResponseNonReplayable(response);
+    expect(shouldRetryCodexPoolAccountTransient(response)).toBe(false);
+  });
+
   test.each([
     ["error.message", { error: { message: "The usage limit has been reached" } }],
     ["last_error.message", { last_error: { message: "The usage limit has been reached" } }],
diff --git a/tests/codex-integration/codex-routing.test.ts b/tests/codex-integration/codex-routing.test.ts
index 85ecb3a3fd..72919b8dff 100644
--- a/tests/codex-integration/codex-routing.test.ts
+++ b/tests/codex-integration/codex-routing.test.ts
@@ -948,6 +948,147 @@ describe("codex routing", () => {
     expect(resolveCodexAccountForThread("quota-next", config)).toBe("b");
   });
 
+  test("a bound thread does not return to the quota group that refused it once the capped cooldown lapses", () => {
+    const config = makeConfig();
+    const now = 1_800_000_000_000;
+    updateAccountQuota("a", 10);
+    updateAccountQuota("b", 20);
+    expect(resolveCodexAccountForThread("spark-refused", config, now, "spark")).toBe("a");
+
+    // The refusal announces a window that reopens in four hours, but a reset-derived cooldown is
+    // capped at 15 minutes so the account is selectable again long before that window moves.
+    recordCodexUpstreamOutcome(config, "a", 429, {
+      now,
+      threadId: "spark-refused",
+      modelId: "gpt-5.3-codex-spark",
+      resetAt: Math.floor((now + 4 * 60 * 60_000) / 1_000),
+    });
+
+    // Usage is still the lowest in the pool and well under the threshold, so nothing else would
+    // move this thread: without the refusal it rebinds to the account that just turned it away.
+    expect(resolveCodexAccountForThread("spark-refused", config, now + 16 * 60_000, "spark")).toBe("b");
+    // The shared lane never refused this thread, so a spent Spark window leaves it alone.
+    expect(resolveCodexAccountForThread("spark-refused", config, now + 16 * 60_000, "shared")).toBe("a");
+  });
+
+  test("the main login is passed over by the window its own refusal announced", () => {
+    // The main account is not in `config.codexAccounts`, so it reaches selection through a
+    // separate re-insertion branch. That branch is the only place an avoidance window can
+    // exclude it, and it is the case the pool filters above cannot cover.
+    writeFileSync(join(TEST_DIR, "auth.json"), JSON.stringify({
+      tokens: { access_token: "main-access", account_id: "main-chatgpt-id" },
+    }));
+    const config = makeConfig({
+      codexAccounts: [{ id: "a", email: "a@test", isMain: false }],
+      activeCodexAccountId: MAIN_CODEX_ACCOUNT_ID,
+    });
+    const now = 1_800_000_000_000;
+    updateAccountQuota(MAIN_CODEX_ACCOUNT_ID, 10);
+    updateAccountQuota("a", 20);
+    expect(resolveCodexAccountForThread("main-spark-first", config, now, "spark")).toBe(MAIN_CODEX_ACCOUNT_ID);
+
+    recordCodexUpstreamOutcome(config, MAIN_CODEX_ACCOUNT_ID, 429, {
+      now,
+      threadId: "main-spark-first",
+      modelId: "gpt-5.3-codex-spark",
+      resetAt: Math.floor((now + 4 * 60 * 60_000) / 1_000),
+    });
+
+    // Selection has to actually reach the re-insertion branch for this to prove anything.
+    // Leaving the main login active would exclude it by id on the fallback instead, so move
+    // the active account and put it over the switch threshold: now a cooler candidate is
+    // wanted, and the only thing that can keep the main login out is its avoidance window.
+    config.activeCodexAccountId = "a";
+    updateAccountQuota("a", 85);
+
+    // The capped cooldown has lapsed and the weekly bar still reads coolest, so without the
+    // window this request goes straight back to the account that just refused one.
+    expect(resolveCodexAccountForThread("main-spark-next", config, now + 16 * 60_000, "spark")).toBe("a");
+  });
+
+  test("naming the account overrules an avoidance the refusal recorded on the scoped lane", () => {
+    const config = makeConfig();
+    const now = 1_800_000_000_000;
+    updateAccountQuota("a", 10);
+    updateAccountQuota("b", 20);
+    recordCodexUpstreamOutcome(config, "a", 429, {
+      now,
+      threadId: "scoped-manual",
+      modelId: "gpt-5.3-codex-spark",
+      resetAt: Math.floor((now + 4 * 60 * 60_000) / 1_000),
+    });
+    expect(resolveCodexAccountForThread("scoped-avoided", config, now + 16 * 60_000, "spark")).toBe("b");
+
+    // A reset-derived refusal writes only the scoped entry, so an operator naming the account
+    // has to reach that map. Stopping at the account-wide entry leaves the pick refused.
+    config.activeCodexAccountId = "a";
+    resetCodexRoutingForManualSelection("a");
+
+    expect(resolveCodexAccountForThread("scoped-named", config, now + 17 * 60_000, "spark")).toBe("a");
+  });
+
+  test("clearing the cooldown also lifts the avoidance that refusal announced", () => {
+    const config = makeConfig();
+    const now = 1_800_000_000_000;
+    updateAccountQuota("a", 10);
+    updateAccountQuota("b", 20);
+    recordCodexUpstreamOutcome(config, "a", 429, {
+      now,
+      modelId: "gpt-5.3-codex-spark",
+      resetAt: Math.floor((now + 4 * 60 * 60_000) / 1_000),
+    });
+    expect(resolveCodexAccountForThread("cleared-before", config, now + 16 * 60_000, "spark")).toBe("b");
+
+    // The escape hatch has to escape. Automatic probe recovery already drops the window; an
+    // operator lifting the same cooldown by hand was leaving it in place for up to six hours.
+    expect(clearCodexAccountCooldown("a", now + 60_000)).toBe(true);
+
+    expect(resolveCodexAccountForThread("cleared-after", config, now + 61_000, "spark")).toBe("a");
+  });
+
+  test("clearing a lapsed cooldown still lifts the avoidance it left behind", () => {
+    const config = makeConfig();
+    const now = 1_800_000_000_000;
+    updateAccountQuota("a", 10);
+    updateAccountQuota("b", 20);
+    recordCodexUpstreamOutcome(config, "a", 429, {
+      now,
+      modelId: "gpt-5.3-codex-spark",
+      resetAt: Math.floor((now + 4 * 60 * 60_000) / 1_000),
+    });
+
+    // The capped cooldown is already gone and only the announced window is still holding the
+    // account out, which is exactly when an operator reaches for this button. Reading the
+    // cooldown alone made the call a no-op for the next several hours.
+    expect(isCodexAccountInCooldown("a", now + 16 * 60_000)).toBe(false);
+    expect(resolveCodexAccountForThread("lapsed-before", config, now + 16 * 60_000, "spark")).toBe("b");
+
+    expect(clearCodexAccountCooldown("a", now + 16 * 60_000)).toBe(true);
+
+    expect(resolveCodexAccountForThread("lapsed-after", config, now + 17 * 60_000, "spark")).toBe("a");
+  });
+
+  test("a request the account serves releases the threads its quota refusal moved", () => {
+    const config = makeConfig();
+    const now = 1_800_000_000_000;
+    updateAccountQuota("a", 10);
+    updateAccountQuota("b", 20);
+    expect(resolveCodexAccountForThread("spark-recovered", config, now, "spark")).toBe("a");
+    recordCodexUpstreamOutcome(config, "a", 429, {
+      now,
+      threadId: "spark-recovered",
+      modelId: "gpt-5.3-codex-spark",
+      resetAt: Math.floor((now + 4 * 60 * 60_000) / 1_000),
+    });
+    expect(resolveCodexAccountForThread("spark-recovered", config, now + 16 * 60_000, "spark")).toBe("b");
+
+    // Selection never stopped offering the account to unbound requests, and the first one it
+    // serves is what ends the refusal — a rebound thread then keeps it across turns.
+    recordCodexUpstreamOutcome(config, "a", 200, { now: now + 17 * 60_000, modelId: "gpt-5.3-codex-spark" });
+    expect(resolveCodexAccountForThread("spark-rebound", config, now + 18 * 60_000, "spark")).toBe("a");
+    expect(resolveCodexAccountForThread("spark-rebound", config, now + 19 * 60_000, "spark")).toBe("a");
+  });
+
   test("shared native reset cooldown clears affinity and rotates the active account", () => {
     const config = makeConfig();
     const now = 1_800_000_000_000;
diff --git a/tests/codex-integration/codex-v2-gate.test.ts b/tests/codex-integration/codex-v2-gate.test.ts
index 39ec9a342c..7b9ce035ae 100644
--- a/tests/codex-integration/codex-v2-gate.test.ts
+++ b/tests/codex-integration/codex-v2-gate.test.ts
@@ -1890,8 +1890,8 @@ describe("3-state multi-agent mode", () => {
       }];
       const accountBoundEntries = [{
         ...template(),
-        slug: "team/gpt-5.4",
-        display_name: "team / GPT-5.4",
+        slug: "team/gpt-5.6-luna",
+        display_name: "team / GPT-5.6 Luna",
         opencodex_catalog_kind: CODEX_ACCOUNT_BOUND_CATALOG_KIND,
         service_tier: "fast",
       }];
diff --git a/tests/codex-integration/codex-warmup.test.ts b/tests/codex-integration/codex-warmup.test.ts
index d186fb7221..9339920918 100644
--- a/tests/codex-integration/codex-warmup.test.ts
+++ b/tests/codex-integration/codex-warmup.test.ts
@@ -35,7 +35,7 @@ describe("codex warmup", () => {
     expect(requests).toBe(1);
   });
 
-  test("posts a minimal gpt-5.4-mini Responses stream request and accepts response.completed", async () => {
+  test("posts a minimal gpt-5.6-luna Responses stream request and accepts response.completed", async () => {
     let body: Record<string, unknown> | undefined;
     let auth: string | null = null;
     let account: string | null = null;
@@ -52,7 +52,7 @@ describe("codex warmup", () => {
     expect(auth).toBe("Bearer access-test");
     expect(account).toBe("acct-test");
     expect(body).toMatchObject({
-      model: "gpt-5.4-mini",
+      model: "gpt-5.6-luna",
       instructions: "Reply with OK.",
       input: [{ type: "message", role: "user", content: [{ type: "input_text", text: "hi" }] }],
       stream: true,
diff --git a/tests/codex-integration/combos.test.ts b/tests/codex-integration/combos.test.ts
index 98174c3848..76e4f26ca9 100644
--- a/tests/codex-integration/combos.test.ts
+++ b/tests/codex-integration/combos.test.ts
@@ -910,7 +910,7 @@ describe("combo failure policy and advancement", () => {
     expect(sleeps).toEqual([1_000]);
   });
 
-  test("still filters exhausted quota on a noncanonical forward destination", () => {
+  test("does not infer provider-wide quota from a noncanonical forward row without a credential", () => {
     const now = 50_000;
     const config = baseConfig({
       providers: {
@@ -927,7 +927,8 @@ describe("combo failure policy and advancement", () => {
 
     const pick = pickComboTarget(config, "free", { now });
 
-    expect(pick?.target.provider).toBe("b");
+    // This is quota selection, not proof that this custom forward route can authenticate.
+    expect(pick?.target.provider).toBe("a");
   });
 
   test("retains caller eligibility restrictions for native targets", () => {
@@ -1150,6 +1151,20 @@ describe("deterministic combo selection", () => {
     });
   });
 
+  test.each(["oauth", "header", "key-pool"])("reset-window does not rank an inapplicable snapshot: %s", kind => {
+    const now = Date.now();
+    const config = baseConfig({ combos: { free: { strategy: "reset-window", targets: [
+      { provider: "a", model: "m1" }, { provider: "b", model: "m2" },
+    ] } } });
+    setCachedProviderQuotaForTests("a", { updatedAt: now, weeklyResetAt: now + 2_000 });
+    setCachedProviderQuotaForTests("b", { updatedAt: now, weeklyResetAt: now + 1_000 });
+    expect(pickComboTarget(config, "free", { now })?.target.provider).toBe("b");
+    if (kind === "oauth") config.providers.b!.authMode = "oauth";
+    else if (kind === "header") config.providers.b!.headers = { Authorization: "Bearer different-key" };
+    else config.providers.b!.apiKeyPool = [{ id: "one", key: "one" }, { id: "two", key: "two" }];
+    expect(pickComboTarget(config, "free", { now })?.target.provider).toBe("a");
+  });
+
   test("reset-window treats elapsed resets as unknown and falls back to configured order", () => {
     const now = Date.now();
     const config = baseConfig({
diff --git a/tests/codex-integration/context-compat.test.ts b/tests/codex-integration/context-compat.test.ts
new file mode 100644
index 0000000000..a0e19f4c60
--- /dev/null
+++ b/tests/codex-integration/context-compat.test.ts
@@ -0,0 +1,22 @@
+import { describe, test, expect } from "bun:test";
+import { codexCompatibleUrl, contextEndpoint, contextCompatibleBaseLine } from "../../src/codex/context-compat";
+
+describe("route and config isolation", () => {
+  test("aliases data-plane routes and preserves query; never aliases management", () => {
+    for (const route of ["responses", "responses/compact", "models", "alpha/search", "live", "realtime/calls"]) {
+      expect(codexCompatibleUrl(`http://127.0.0.1:10100/backend-api/codex/${route}?a=1`).pathname).toBe(`/v1/${route}`);
+    }
+    expect(codexCompatibleUrl("http://127.0.0.1:10100/v1/responses?a=1").href).toBe("http://127.0.0.1:10100/v1/responses?a=1");
+    expect(codexCompatibleUrl("http://127.0.0.1:10100/backend-api/codex/api/config").pathname).toBe("/v1/api/config");
+    expect(contextEndpoint("/v1/alpha/notes/v2/write_file")).toBe("alpha/notes/v2/write_file");
+    expect(contextEndpoint("/v1/alpha/notes/v2/delete_file")).toBeUndefined();
+    expect(contextEndpoint("/v1/alpha/notes/v2/../write_file")).toBeUndefined();
+  });
+  test("opt-in changes only the built-in loopback base URL", () => {
+    const line='openai_base_url = "http://127.0.0.1:10100/v1"';
+    expect(contextCompatibleBaseLine('[features]\ncontext_management.experimental_mode = true\n',line)).toBe('openai_base_url = "http://127.0.0.1:10100/backend-api/codex"');
+    for(const content of ['','[features]\ncontext_management.experimental_mode = false\n']) expect(contextCompatibleBaseLine(content,line)).toBe(line);
+    const remote='openai_base_url = "https://example.com/v1"';
+    expect(contextCompatibleBaseLine('[features.context_management]\nexperimental_mode=true\n',remote)).toBe(remote);
+  });
+});
diff --git a/tests/codex-integration/effort-policy.test.ts b/tests/codex-integration/effort-policy.test.ts
index 2f1e65c10c..0d3ac76018 100644
--- a/tests/codex-integration/effort-policy.test.ts
+++ b/tests/codex-integration/effort-policy.test.ts
@@ -278,7 +278,7 @@ describe("supportedLadderFor (real routeModel routes)", () => {
     tempCodexHome = mkdtempSync(join(tmpdir(), "ocx-effort-catalog-"));
     process.env.CODEX_HOME = tempCodexHome;
     writeFileSync(join(tempCodexHome, "opencodex-catalog.json"), JSON.stringify({
-      models: [{ slug: "gpt-5.4", display_name: "gpt-5.4", supported_reasoning_levels: [
+      models: [{ slug: "gpt-5.5", display_name: "gpt-5.5", supported_reasoning_levels: [
         { effort: "low", description: "low" }, { effort: "medium", description: "medium" },
       ] }],
     }));
@@ -286,13 +286,13 @@ describe("supportedLadderFor (real routeModel routes)", () => {
       providers: {
         selfhosted: {
           adapter: "openai-responses", baseUrl: "https://example.com/v1", authMode: "key",
-          apiKey: "k", models: ["gpt-5.4"],
+          apiKey: "k", models: ["gpt-5.5"],
         },
       },
       defaultProvider: "selfhosted",
     } as Partial<OcxConfig>);
-    expect(() => routeModel(config, "gpt-5.4")).toThrow(NoEnabledOpenAiProviderError);
-    const namespaced = routeModel(config, "selfhosted/gpt-5.4");
+    expect(() => routeModel(config, "gpt-5.5")).toThrow(NoEnabledOpenAiProviderError);
+    const namespaced = routeModel(config, "selfhosted/gpt-5.5");
     expect(namespaced.providerName).toBe("selfhosted");
     expect(supportedLadderFor(namespaced)).toBeUndefined();
   });
@@ -301,7 +301,7 @@ describe("supportedLadderFor (real routeModel routes)", () => {
     tempCodexHome = mkdtempSync(join(tmpdir(), "ocx-effort-catalog-"));
     process.env.CODEX_HOME = tempCodexHome;
     writeFileSync(join(tempCodexHome, "opencodex-catalog.json"), JSON.stringify({
-      models: [{ slug: "gpt-5.4", display_name: "gpt-5.4", supported_reasoning_levels: [
+      models: [{ slug: "gpt-5.5", display_name: "gpt-5.5", supported_reasoning_levels: [
         { effort: "low", description: "low" }, { effort: "medium", description: "medium" },
         { effort: "high", description: "high" }, { effort: "xhigh", description: "xhigh" },
       ] }],
@@ -312,7 +312,7 @@ describe("supportedLadderFor (real routeModel routes)", () => {
       },
       defaultProvider: "openai",
     } as Partial<OcxConfig>);
-    const route = routeModel(config, "gpt-5.4");
+    const route = routeModel(config, "gpt-5.5");
     expect(supportedLadderFor(route)).toEqual(["low", "medium", "high", "xhigh"]);
   });
 });
@@ -432,11 +432,11 @@ describe("cap composition with downstream clamps", () => {
   });
 
   test("synthetic native top rung is still lowered by nativeEffortClamp after the cap block", () => {
-    // gpt-5.4's real ladder stops at xhigh: an uncapped (or xhigh-capped) max/ultra
+    // gpt-5.5's real ladder stops at xhigh: an uncapped (or xhigh-capped) max/ultra
     // arrival is repaired by the native clamp that runs AFTER applyEffortCap.
-    expect(nativeEffortClamp("gpt-5.4", "max")).toBe("xhigh");
-    expect(nativeEffortClamp("gpt-5.4", "ultra")).toBe("xhigh");
-    expect(nativeEffortClamp("gpt-5.4", "medium")).toBeNull();
+    expect(nativeEffortClamp("gpt-5.5", "max")).toBe("xhigh");
+    expect(nativeEffortClamp("gpt-5.5", "ultra")).toBe("xhigh");
+    expect(nativeEffortClamp("gpt-5.5", "medium")).toBeNull();
   });
 });
 
diff --git a/tests/codex-integration/issue-702-expired-replay-state.test.ts b/tests/codex-integration/issue-702-expired-replay-state.test.ts
index 13b96be638..1a9b3bd092 100644
--- a/tests/codex-integration/issue-702-expired-replay-state.test.ts
+++ b/tests/codex-integration/issue-702-expired-replay-state.test.ts
@@ -286,6 +286,126 @@ afterEach(() => {
   else process.env.OPENCODEX_API_AUTH_TOKEN = previousApiToken;
 });
 
+describe("routed replay recovery", () => {
+  test.each([
+    { stateless: true, custom: false, expired: false },
+    { stateless: true, custom: false, expired: true },
+    { stateless: false, custom: true, expired: false },
+    { stateless: false, custom: true, expired: true },
+    { stateless: false, custom: true, expired: false, authMode: "forward" },
+    { stateless: true, custom: false, expired: false, adapter: "openai-chat" },
+  ] as const)("recovers missing history without orphaning tool results: %j", async scenario => {
+    const { stateless, custom, expired } = scenario;
+    const upstreamRequests: Record<string, unknown>[] = [];
+    const realNow = Date.now;
+    const toolCall = custom
+      ? { type: "custom_tool_call", call_id: "call_replay", name: "exec", input: "text(1)", status: "completed" }
+      : { type: "function_call", call_id: "call_replay", name: "lookup", arguments: "{}", status: "completed" };
+    const toolResult = {
+      type: custom ? "custom_tool_call_output" : "function_call_output",
+      call_id: "call_replay", output: "1",
+    };
+    const reasoning = { type: "reasoning", content: [{ type: "reasoning_text", text: "Use the lookup result." }] };
+    const history = [inputMessage(HISTORICAL_USER_SENTINEL), reasoning, toolCall];
+    const tools = custom
+      ? [{ type: "custom", name: "exec", description: "Run JavaScript", format: { type: "text" } }]
+      : [{ type: "function", name: "lookup", parameters: { type: "object", properties: {} } }];
+    const upstream = Bun.serve({
+      port: 0,
+      async fetch(request) {
+        const body = await request.json() as Record<string, unknown>;
+        upstreamRequests.push(body);
+        const items = body.input as Array<Record<string, unknown>>;
+        // A strict upstream cannot resolve a tool result without its matching function call.
+        if (!items.some(item => item.type === "function_call" && item.call_id === "call_replay")
+          || !items.some(item => item.type === "function_call_output" && item.call_id === "call_replay")) {
+          return Response.json({ error: { type: "invalid_request_error", message: "No matching tool call" } }, { status: 400 });
+        }
+        return new Response(completedSse("resp_routed_recovered", "recovered"), {
+          headers: { "content-type": "text/event-stream" },
+        });
+      },
+    });
+    let server: ReturnType<typeof startServer> | null = null;
+    let socket: WebSocket | null = null;
+    try {
+      if (expired) {
+        Date.now = () => realNow() - EXPIRED_AGE_MS;
+        rememberResponseState(
+          { input: [history[0]], tools, store: false },
+          { id: FIRST_RESPONSE_ID, status: "completed", output: [reasoning, toolCall] },
+          undefined, { force: true },
+        );
+        Date.now = realNow;
+      }
+      saveConfig({
+        port: 0, hostname: "127.0.0.1", websockets: true, defaultProvider: "routed-test",
+        providers: {
+          "routed-test": {
+            adapter: "adapter" in scenario ? scenario.adapter : "openai-responses",
+            modelAdapters: { "test-model": "openai-responses" },
+            baseUrl: upstream.url.toString(), allowPrivateNetwork: true,
+            authMode: "authMode" in scenario ? scenario.authMode : "key", apiKey: "synthetic-key", defaultModel: "test-model",
+            statelessResponses: stateless, preserveResponsesReasoningContent: true,
+          },
+        },
+      } as OcxConfig);
+      server = startServer(0);
+      const deltaRequest = {
+        model: "routed-test/test-model", previous_response_id: FIRST_RESPONSE_ID,
+        input: [toolResult], tools, store: false,
+      };
+      const httpRejected = await originalFetch(new URL("/v1/responses", server.url), {
+        method: "POST", headers: { "content-type": "application/json" },
+        body: JSON.stringify(deltaRequest),
+      });
+      expect(httpRejected.status).toBe(400);
+      expect(await httpRejected.json()).toMatchObject({ error: { code: "previous_response_not_found" } });
+      expect(upstreamRequests).toHaveLength(0);
+      socket = await openResponseSocket(server.url, {});
+      const rejected = await sendSocketTurn(socket, deltaRequest);
+      expect(rejected).toMatchObject({
+        type: "error", status: 400,
+        error: { type: "invalid_request_error", code: "previous_response_not_found" },
+      });
+      expect(upstreamRequests).toHaveLength(0);
+
+      socket.close();
+      socket = await openResponseSocket(server.url, {});
+      const recovered = await sendSocketTurn(socket, {
+        model: "routed-test/test-model", input: [...history, toolResult], tools, store: false,
+      });
+      expect(recovered.type).toBe("response.completed");
+      expect(upstreamRequests).toHaveLength(1);
+      expect(upstreamRequests[0]!.previous_response_id).toBeUndefined();
+      expect(upstreamRequests[0]!.input).toEqual([
+        history[0], reasoning,
+        { type: "function_call", call_id: "call_replay", name: custom ? "exec" : "lookup",
+          arguments: custom ? JSON.stringify({ input: "text(1)" }) : "{}", status: "completed" },
+        { ...toolResult, type: "function_call_output" },
+      ]);
+      await waitForRecordedResponseState();
+
+      // Recovery must seed complete local history so the next delta does not repeat the miss.
+      const continued = await sendSocketTurn(socket, {
+        model: "routed-test/test-model", previous_response_id: "resp_routed_recovered",
+        input: [inputMessage(CURRENT_USER_SENTINEL)], tools, store: false,
+      });
+      expect(continued.type).toBe("response.completed");
+      expect(upstreamRequests).toHaveLength(2);
+      expect(upstreamRequests[1]!.previous_response_id).toBeUndefined();
+      const items = upstreamRequests[1]!.input as Array<Record<string, unknown>>;
+      expect(items.filter(item => item.call_id === "call_replay")).toHaveLength(2);
+      expect(items.at(-1)).toEqual(inputMessage(CURRENT_USER_SENTINEL));
+    } finally {
+      Date.now = realNow;
+      socket?.close();
+      await server?.stop(true);
+      await upstream.stop(true);
+    }
+  }, SERVER_BUDGET_MS);
+});
+
 describe("Issue #702 expired forward replay state", () => {
   test("known continuation spill failure returns terminal structured previous_response_not_found before upstream I/O", async () => {
     const responseId = "resp_issue_702_missing_spill";
@@ -512,7 +632,7 @@ describe("Issue #702 expired forward replay state", () => {
     expect(JSON.stringify(scenario.upstreamRequests[0]!.body)).toContain(HISTORICAL_USER_SENTINEL);
   });
 
-  test("API-key Responses providers can still forward native previous_response_id state", async () => {
+  test.each(["message", "function", "custom"] as const)("API-key Responses providers can still forward native %s continuation state", async kind => {
     const upstreamRequests: Record<string, unknown>[] = [];
     const realNow = Date.now;
     let upstream: ReturnType<typeof Bun.serve> | null = null;
@@ -539,6 +659,7 @@ describe("Issue #702 expired forward replay state", () => {
             allowPrivateNetwork: true,
             apiKey: "provider-key",
             defaultModel: "gpt-5.5",
+            statelessResponses: false,
           },
         },
       } as OcxConfig);
@@ -551,6 +672,12 @@ describe("Issue #702 expired forward replay state", () => {
           model: "test-openai/gpt-5.5",
           previous_response_id: "resp_upstream_native_state",
           input: [inputMessage(CURRENT_USER_SENTINEL)],
+          ...(kind === "message" ? {} : {
+            tools: [kind === "custom"
+              ? { type: "custom", name: "apply_patch", description: "Apply patch", format: { type: "text" } }
+              : { type: "function", name: "lookup", parameters: { type: "object", properties: {} } }],
+            input: [{ type: kind === "custom" ? "custom_tool_call_output" : "function_call_output", call_id: "call_native", output: "done" }],
+          }),
           stream: true,
         }),
       });
@@ -558,6 +685,9 @@ describe("Issue #702 expired forward replay state", () => {
       await response.text();
       expect(upstreamRequests).toHaveLength(1);
       expect(upstreamRequests[0]!.previous_response_id).toBe("resp_upstream_native_state");
+      if (kind !== "message") expect(upstreamRequests[0]!.input).toEqual([
+        { type: kind === "custom" ? "custom_tool_call_output" : "function_call_output", call_id: "call_native", output: "done" },
+      ]);
     } finally {
       Date.now = realNow;
       globalThis.fetch = originalFetch;
diff --git a/tests/codex-integration/main-account-hard-lock-policy.test.ts b/tests/codex-integration/main-account-hard-lock-policy.test.ts
index a01b181bba..cf1a99d699 100644
--- a/tests/codex-integration/main-account-hard-lock-policy.test.ts
+++ b/tests/codex-integration/main-account-hard-lock-policy.test.ts
@@ -4,7 +4,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { getMainAccountHardLockStatus, isMainAccountHardLocked } from "../../src/codex/main-account-hard-lock";
 import { captureMainQuotaWriter, clearMainAccountInfoCache, observeMainQuotaIdentity } from "../../src/codex/main-account-cache";
-import { clearAccountQuota, setAccountQuotaFromParsed, type StoredAccountQuota } from "../../src/codex/quota";
+import { clearAccountQuota, getAccountQuota, getMainPolicyQuota, setAccountQuotaFromParsed, type StoredAccountQuota } from "../../src/codex/quota";
 import { removeTreeWithRetry } from "../helpers/remove-tree";
 
 const now = Date.UTC(2026, 8, 5);
@@ -67,6 +67,28 @@ describe("identity-bound main-account hard-lock policy", () => {
     expect(getMainAccountHardLockStatus(enabled, now + 120_000)).toEqual({ enabled: true, state: "ready" });
   });
 
+  test.each([
+    { resetCredits: 2 },
+    { weeklyPercent: 20 },
+    { shortWindowSeconds: 18_000, shortResetAt: 4_000_000_000 },
+  ])("partial update %j preserves expired main blocking evidence", partial => {
+    const elapsed = Math.floor(Date.now() / 1000) - 60;
+    observe({ shortPercent: 99, shortWindowSeconds: 18_000, shortResetAt: elapsed, weeklyPercent: 20 });
+    expect(getMainAccountHardLockStatus(enabled).state).toBe("blocked");
+    const before = getMainPolicyQuota();
+    observe(partial);
+    expect(getMainPolicyQuota()).toMatchObject({
+      shortPercent: 99,
+      shortResetAt: elapsed,
+      shortWindowSeconds: 18_000,
+      shortObservedAt: before?.shortObservedAt,
+    });
+    expect(getAccountQuota("__main__")?.shortPercent).toBeUndefined();
+    expect(getMainAccountHardLockStatus(enabled).state).toBe("blocked");
+    observe({ shortPercent: 0 });
+    expect(getMainAccountHardLockStatus(enabled).state).toBe("ready");
+  });
+
   test("one missing reset prevents a false scheduled-unlock promise", () => {
     observe({ weeklyPercent: 99, monthlyPercent: 99, monthlyResetAt: now + 60_000 });
     expect(getMainAccountHardLockStatus(enabled, now)).toEqual({ enabled: true, state: "blocked" });
diff --git a/tests/codex-integration/model-visibility-management-api.test.ts b/tests/codex-integration/model-visibility-management-api.test.ts
index e11ebc2428..9fef0adefe 100644
--- a/tests/codex-integration/model-visibility-management-api.test.ts
+++ b/tests/codex-integration/model-visibility-management-api.test.ts
@@ -373,12 +373,12 @@ test("configured manual OpenAI rows can be toggled alongside native rows", async
   const config = loadConfig();
   config.providers.openai = {adapter:"openai-responses",authMode:"forward",baseUrl:"https://chatgpt.com/backend-api/codex",liveModels:false};
   config.customModels = [{id:"manual-gpt",provider:"openai",modelId:"gpt-5.5",contextWindow:128_000}];
-  config.disabledModels = ["openai/gpt-5.5", "gpt-5.4"];
+  config.disabledModels = ["openai/gpt-5.5", "gpt-5.6-luna"];
   expect((await putWithConfig({scope:"models",provider:"openai",targets:[{id:"gpt-5.5",native:false}],enabled:true},config)).status).toBe(200);
-  expect(config.disabledModels).toEqual(["gpt-5.4"]);
-  expect((await putWithConfig({scope:"models",provider:"openai",targets:[{id:"gpt-5.5",native:false},{id:"gpt-5.4",native:true}],enabled:false},config)).status).toBe(200);
+  expect(config.disabledModels).toEqual(["gpt-5.6-luna"]);
+  expect((await putWithConfig({scope:"models",provider:"openai",targets:[{id:"gpt-5.5",native:false},{id:"gpt-5.6-luna",native:true}],enabled:false},config)).status).toBe(200);
   expect(config.disabledModels).toContain("openai/gpt-5.5");
-  expect(config.disabledModels).toContain("gpt-5.4");
+  expect(config.disabledModels).toContain("gpt-5.6-luna");
   expect((await putWithConfig({scope:"models",provider:"openai",targets:[{id:"not-configured",native:false}],enabled:true},config)).status).toBe(400);
 });
 
@@ -391,15 +391,15 @@ test("provider-group toggles persist mixed native and manual OpenAI targets toge
   config.customModels = [{ id: "manual-gpt", provider: "openai", modelId: "gpt-5.5" }];
   const unrelatedDisabled = [...config.disabledModels!];
   const unrelatedProvider = structuredClone(config.providers["google-antigravity"]);
-  const targets = [{ id: "gpt-5.5", native: false }, { id: "gpt-5.4", native: true }];
+  const targets = [{ id: "gpt-5.5", native: false }, { id: "gpt-5.6-luna", native: true }];
   saveConfig(config);
 
   const disabled = await putWithConfig({ scope: "provider", provider: "openai", targets, enabled: false }, config);
   expect(disabled.status).toBe(200);
   expect(await disabled.json()).toMatchObject({ ok: true, scope: "provider", provider: "openai", enabled: false });
-  expect(config.disabledModels).toEqual([...unrelatedDisabled, "openai/gpt-5.5", "gpt-5.4"]);
+  expect(config.disabledModels).toEqual([...unrelatedDisabled, "openai/gpt-5.5", "gpt-5.6-luna"]);
   expect(config.providers.openai.selectedModels).toEqual(["gpt-5.5"]);
-  expect(loadConfig().disabledModels).toEqual([...unrelatedDisabled, "openai/gpt-5.5", "gpt-5.4"]);
+  expect(loadConfig().disabledModels).toEqual([...unrelatedDisabled, "openai/gpt-5.5", "gpt-5.6-luna"]);
   expect(loadConfig().providers.openai.selectedModels).toEqual(["gpt-5.5"]);
   expect(loadConfig().providers["google-antigravity"]).toEqual(unrelatedProvider);
   expect(refreshes).toBe(1);
@@ -426,14 +426,14 @@ test("an invalid trailing target leaves a mixed OpenAI provider-group update ato
 
   for (const enabled of [false, true]) {
     // Both valid targets would change state before the final invalid target is reached.
-    config.disabledModels = enabled ? ["other/keep", "openai/gpt-5.5", "gpt-5.4"] : ["other/keep"];
+    config.disabledModels = enabled ? ["other/keep", "openai/gpt-5.5", "gpt-5.6-luna"] : ["other/keep"];
     saveConfig(config);
     const before = structuredClone(config);
     const persistedBefore = loadConfig();
     for (const invalid of [{ id: "not-configured", native: false }, { id: "gpt-9.9-imaginary", native: true }]) {
       const response = await putWithConfig({
         scope: "provider", provider: "openai", enabled,
-        targets: [{ id: "gpt-5.5", native: false }, { id: "gpt-5.4", native: true }, invalid],
+        targets: [{ id: "gpt-5.5", native: false }, { id: "gpt-5.6-luna", native: true }, invalid],
       }, config);
       expect(response.status).toBe(400);
       expect(await response.json()).toMatchObject({ error: "invalid model visibility target" });
diff --git a/tests/codex-integration/native-model-toggle.test.ts b/tests/codex-integration/native-model-toggle.test.ts
index 0ac18f1ad2..7e90a6f05c 100644
--- a/tests/codex-integration/native-model-toggle.test.ts
+++ b/tests/codex-integration/native-model-toggle.test.ts
@@ -68,8 +68,8 @@ function nativeTemplate(): Record<string, unknown> {
 
 describe("native GPT model toggles (bare slugs in disabledModels)", () => {
   test("disabledNativeSlugs picks bare ids only; routed namespaced ids are ignored", () => {
-    const set = disabledNativeSlugs({ disabledModels: ["gpt-5.4", "kiro/claude-opus-4.6", "gpt-5.6-luna"] });
-    expect([...set].sort()).toEqual(["gpt-5.4", "gpt-5.6-luna"]);
+    const set = disabledNativeSlugs({ disabledModels: ["gpt-5.5", "kiro/claude-opus-4.6", "gpt-5.6-luna"] });
+    expect([...set].sort()).toEqual(["gpt-5.5", "gpt-5.6-luna"]);
   });
 
   test("visibleNativeSlugs omits disabled natives from the bare availability list", () => {
@@ -230,8 +230,12 @@ describe("native GPT model toggles (bare slugs in disabledModels)", () => {
   });
 
   test("the on-disk catalog preserves a lower retained native compaction threshold", () => {
+    // A retired slug is no longer a valid subject: nativeOpenAiAutoCompactTokenLimit
+    // requires a known native window, so a configured lowering would not apply to
+    // gpt-5.4-mini after its override and membership were removed. gpt-5.5 is the
+    // surviving old-ladder native whose 272k window matches this retained row.
     const retained = {
-      slug: "gpt-5.4-mini",
+      slug: "gpt-5.5",
       context_window: 272_000,
       max_context_window: 272_000,
       auto_compact_token_limit: 100_000,
@@ -240,7 +244,7 @@ describe("native GPT model toggles (bare slugs in disabledModels)", () => {
     expect(retained.auto_compact_token_limit).toBe(100_000);
 
     const configured = {
-      providers: { openai: { modelAutoCompactTokenLimits: { "gpt-5.4-mini": 80_000 } } },
+      providers: { openai: { modelAutoCompactTokenLimits: { "gpt-5.5": 80_000 } } },
     } as never;
     const lowered = { ...retained };
     applyNativeOpenAiContextOverride(lowered as never, nativeContextLimits(configured));
@@ -296,7 +300,10 @@ describe("native GPT model toggles (bare slugs in disabledModels)", () => {
     const over = nativeModelRows({ providerContextCaps: { openai: 2_000_000 } });
     expect(over.find(r => r.slug === "gpt-5.6-sol")?.contextWindow).toBe(922_000);
     expect(raised.find(r => r.slug === "gpt-5.5")?.contextWindow).toBe(272_000);
-    expect(raised.find(r => r.slug === "gpt-5.4")?.contextWindow).toBe(922_000);
+    // gpt-5.4 was the only native with a 1M override. Retirement deleted that
+    // membership and the override; nothing else inherits a 1M window.
+    expect(raised.find(r => r.slug === "gpt-5.4")).toBeUndefined();
+    expect(raised.every(r => (r.contextWindow ?? 0) <= 922_000)).toBe(true);
   });
 
   test("nativeModelRows applies providerContextCaps.openai as a ceiling (#1430)", () => {
diff --git a/tests/codex-integration/reasoning-effort.test.ts b/tests/codex-integration/reasoning-effort.test.ts
index a5d3cd1114..3f0b85da34 100644
--- a/tests/codex-integration/reasoning-effort.test.ts
+++ b/tests/codex-integration/reasoning-effort.test.ts
@@ -194,11 +194,11 @@ describe("provider-specific reasoning effort mapping", () => {
           adapter: "openai-chat",
           baseUrl: "https://api.deepseek.com",
           apiKey: "key",
-          models: ["deepseek-v4-pro"],
+          models: ["deepseek-flash"],
         },
       },
     };
-    const route = routeModel(config, "deepseek/deepseek-v4-pro");
+    const route = routeModel(config, "deepseek/deepseek-flash");
 
     const req = createOpenAIChatAdapter(route.provider).buildRequest({
       modelId: route.modelId,
@@ -271,7 +271,8 @@ describe("provider-specific reasoning effort mapping", () => {
     });
     const body = JSON.parse(req.body as string) as { messages: Record<string, unknown>[] };
 
-    expect(route.provider.preserveReasoningContentModels).toEqual(["deepseek-v4-pro", "deepseek-v4-flash"]);
+    expect(route.provider.preserveReasoningContentModels)
+      .toEqual(["deepseek-flash", "deepseek-v4-flash"]);
     expect(body.messages[1].reasoning_content).toBeUndefined();
   });
 
diff --git a/tests/codex-integration/slug-codec.test.ts b/tests/codex-integration/slug-codec.test.ts
index 611754ce18..5248b75020 100644
--- a/tests/codex-integration/slug-codec.test.ts
+++ b/tests/codex-integration/slug-codec.test.ts
@@ -241,8 +241,8 @@ describe("routeModel decode (proxy layer)", () => {
   test("commandcode API-key preset decodes its native slash ids from the registry effort table", () => {
     // Regression: the `commandcode` (API-key) registry entry must share the official
     // reasoning-facts table with the OAuth `command-code` entry. Without it the router's
-    // known-ids source misses `deepseek/deepseek-v4-pro` / `zai-org/GLM-5.3`, so the
-    // Codex-facing slugs (`commandcode/deepseek-deepseek-v4-pro`) pass through unchanged
+    // known-ids source misses `deepseek/deepseek-v4-flash` / `zai-org/GLM-5.3`, so the
+    // Codex-facing slugs (`commandcode/deepseek-deepseek-v4-flash`) pass through unchanged
     // and upstream rejects them with `unsupported_model`.
     const prov = {
       adapter: "openai-chat",
@@ -252,9 +252,9 @@ describe("routeModel decode (proxy layer)", () => {
       liveModels: true,
     };
     const ids = knownModelIdsForProvider("commandcode", prov);
-    expect(ids).toContain("deepseek/deepseek-v4-pro");
+    expect(ids).toContain("deepseek/deepseek-v4-flash");
     expect(ids).toContain("zai-org/GLM-5.3");
-    expect(decodeRoutedModelId("deepseek-deepseek-v4-pro", ids)).toBe("deepseek/deepseek-v4-pro");
+    expect(decodeRoutedModelId("deepseek-deepseek-v4-flash", ids)).toBe("deepseek/deepseek-v4-flash");
     expect(decodeRoutedModelId("zai-org-GLM-5.3", ids)).toBe("zai-org/GLM-5.3");
   });
 });
diff --git a/tests/codex-integration/token-guardian.test.ts b/tests/codex-integration/token-guardian.test.ts
index 3e0ef632d8..3bb215d7dc 100644
--- a/tests/codex-integration/token-guardian.test.ts
+++ b/tests/codex-integration/token-guardian.test.ts
@@ -4,6 +4,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { saveCredential } from "../../src/oauth/store";
 import { getConfigPath } from "../../src/config";
+import { flushConfigDirHardening } from "../../src/config/paths";
 import { markCodexAccountValidated, readCodexAccountRecord, saveCodexAccountCredential } from "../../src/codex/account-store";
 import { __resetGuardianState, guardianSweep } from "../../src/oauth/token-guardian";
 import type { OcxConfig, OcxProviderConfig } from "../../src/types";
@@ -46,7 +47,9 @@ beforeEach(() => {
   __resetGuardianState();
 });
 
-afterEach(() => {
+afterEach(async () => {
+  // Optional Windows ACL work can outlive credential writes and keep this home open.
+  await flushConfigDirHardening(join(tmp, "ocx"));
   resetLifecycleDrainStateForTests();
   if (origHome === undefined) delete process.env.HOME; else process.env.HOME = origHome;
   if (origOcxHome === undefined) delete process.env.OPENCODEX_HOME; else process.env.OPENCODEX_HOME = origOcxHome;
@@ -247,7 +250,7 @@ describe("token guardian", () => {
 
     expect(res.refreshed).toEqual([]);
     expect(res.warmed).toContain("codex:acct-warm");
-    expect(mock.body()).toMatchObject({ model: "gpt-5.4-mini", input: WARMUP_INPUT, stream: true, store: false });
+    expect(mock.body()).toMatchObject({ model: "gpt-5.6-luna", input: WARMUP_INPUT, stream: true, store: false });
     expect(readCodexAccountRecord("acct-warm")?.lastCodexValidationStatus).toBe("ok");
     expect(readCodexAccountRecord("acct-warm")?.lastCodexValidatedAt).toBeGreaterThan(Date.now() - 30_000);
   });
diff --git a/tests/codex-integration/warmup.test.ts b/tests/codex-integration/warmup.test.ts
index 5590e62ae1..1c25005860 100644
--- a/tests/codex-integration/warmup.test.ts
+++ b/tests/codex-integration/warmup.test.ts
@@ -94,7 +94,7 @@ describe("codex warmup improvements", () => {
       const body = JSON.parse(String(init?.body)) as Record<string, unknown>;
       parsedBodies.push(body);
 
-      if (body.model === "gpt-5.4-mini") {
+      if (body.model === "gpt-5.6-luna") {
         return new Response(JSON.stringify({ detail: "unknown model" }), { status: 400 });
       }
 
@@ -110,23 +110,18 @@ describe("codex warmup improvements", () => {
     }
 
     expect(fetchMock).toHaveBeenCalledTimes(2);
-    expect(parsedBodies.map(body => body.model)).toEqual(["gpt-5.4-mini", "gpt-5.5"]);
+    expect(parsedBodies.map(body => body.model)).toEqual(["gpt-5.6-luna", "gpt-5.5"]);
   });
-  test("warmCodexAccount retries FALLBACK_MODELS on HTTP 404 and falls through to gpt-5.6-luna", async () => {
+  test("warmCodexAccount retries FALLBACK_MODELS on HTTP 404", async () => {
     const parsedBodies: Record<string, unknown>[] = [];
     const fetchMock = mock(async (_input: RequestInfo | URL, init?: RequestInit) => {
       const body = JSON.parse(String(init?.body)) as Record<string, unknown>;
       parsedBodies.push(body);
 
-      if (body.model === "gpt-5.4-mini") {
-        return new Response(JSON.stringify({ detail: "model not found" }), { status: 404 });
-      }
-      if (body.model === "gpt-5.5") {
-        return new Response(JSON.stringify({ detail: "model not supported for free tier" }), { status: 400 });
-      }
       if (body.model === "gpt-5.6-luna") {
-        return sseResponse();
+        return new Response(JSON.stringify({ detail: "model not found" }), { status: 404 });
       }
+      if (body.model === "gpt-5.5") return sseResponse();
       return new Response("unexpected model", { status: 500 });
     });
     const fetchSpy = spyOn(globalThis, "fetch").mockImplementation(fetchMock as unknown as typeof fetch);
@@ -137,8 +132,8 @@ describe("codex warmup improvements", () => {
       fetchSpy.mockRestore();
     }
 
-    expect(fetchMock).toHaveBeenCalledTimes(3);
-    expect(parsedBodies.map(body => body.model)).toEqual(["gpt-5.4-mini", "gpt-5.5", "gpt-5.6-luna"]);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(parsedBodies.map(body => body.model)).toEqual(["gpt-5.6-luna", "gpt-5.5"]);
   });
 
   test("warmCodexAccount does not retry on 401 and immediately fails", async () => {
diff --git a/tests/config/client-config-export-new-clients.test.ts b/tests/config/client-config-export-new-clients.test.ts
index 5a381d6237..3a9c171238 100644
--- a/tests/config/client-config-export-new-clients.test.ts
+++ b/tests/config/client-config-export-new-clients.test.ts
@@ -61,11 +61,11 @@ describe("no secret reaches a client config", () => {
     // Pi, Kimi, Gajae, Aside and Raycast cannot emit the dedicated admission
     // header -- Aside's observed provider block has four keys and none is
     // `headers`; Raycast's `api_keys` is read literally with no env
-    // interpolation. OMP and Prime can carry provider headers, but remote
+    // interpolation. OMP, Prime and omo can carry provider headers, but remote
     // credential wiring is deliberately deferred from those initial generated
-    // integrations.
+    // integrations -- omo reuses Pi's builder, which emits no headers at all.
     const loopbackOnly = EXPORT_CLIENT_IDS.filter(id => EXPORT_CLIENTS[id].loopbackOnly);
-    expect(loopbackOnly).toEqual(["pi", "omp", "kimi", "gajae", "dsh", "mcode", "zcode", "prime", "aside", "raycast"]);
+    expect(loopbackOnly).toEqual(["pi", "omp", "kimi", "gajae", "dsh", "mcode", "zcode", "prime", "aside", "raycast", "omo", "cline"]);
   });
 
   test("every client that is not loopback-only carries the header on a remote bind", () => {
diff --git a/tests/config/client-config-export.test.ts b/tests/config/client-config-export.test.ts
index 17b3ce9c93..53e47c6276 100644
--- a/tests/config/client-config-export.test.ts
+++ b/tests/config/client-config-export.test.ts
@@ -120,7 +120,7 @@ describe("split config-export public facade", () => {
       ["omp", ["providers", "opencodex"], '{"providers":{"opencodex":{"baseUrl":"http://127.0.0.1:10100/v1","api":"openai-completions","apiKey":"opencodex-loopback","models":[{"id":"test/known","name":"known (test)","input":["text","image"],"contextWindow":8192,"maxTokens":8192,"reasoning":true,"thinking":{"mode":"effort","efforts":["high"]}}]}}}'],
       ["dsh", ["llm-pi-ai", "providers", "opencodex"], '{"llm-pi-ai":{"providers":{"opencodex":{"displayName":"OpenCodex","api":"openai-responses","baseURL":"http://127.0.0.1:10100/v1","headers":{"Authorization":"Bearer ocx_data_dsh"},"models":[{"id":"test/known","name":"known (test)","input":["text","image"],"contextWindow":8192,"reasoningEfforts":{"high":"high"}}]}}}}'],
       ["mcode", ["custom_provider", "opencodex"], '{"custom_provider":{"opencodex":{"name":"OpenCodex","kind":"custom","enabled":true,"api":"anthropic-messages","options":{"apiKey":"opencodex-loopback","baseURL":"http://127.0.0.1:10100","authMode":"api-key"},"models":{"test/known":{"limit":{"context":8192},"thinking":{"effortOptions":["high"]}}}}}}'],
-      ["zcode", ["provider", "opencodex"], '{"provider":{"opencodex":{"name":"OpenCodex","kind":"openai-compatible","enabled":true,"source":"custom","options":{"apiKey":"opencodex-loopback","baseURL":"http://127.0.0.1:10100/v1","apiKeyRequired":true},"models":{"test/known":{"name":"known (test)","modalities":{"input":["text","image"],"output":["text"]},"limit":{"context":8192},"reasoning":{"enabled":true,"variants":["high"]}}}}}}'],
+      ["zcode", ["provider", "opencodex"], '{"provider":{"opencodex":{"name":"OpenCodex","kind":"openai","enabled":true,"source":"custom","options":{"apiKey":"opencodex-loopback","baseURL":"http://127.0.0.1:10100/v1","apiKeyRequired":true},"models":{"test/known":{"name":"known (test)","modalities":{"input":["text","image"],"output":["text"]},"limit":{"context":8192},"reasoning":{"enabled":true,"variants":["high"]}}}}}}'],
     ] as const;
     for (const [id, path, expectedBytes] of cases) {
       const built = buildClientConfigText(id, context);
@@ -752,11 +752,16 @@ describe("hub-resolved Fast exports", () => {
       expect(block.models["z/sparse--fast"]).toEqual({ name: "z/sparse Fast (routed)" });
     }
     const expanded = opencodeProviderBlocks(BASE_URL, [eligible], cfg({ fastRows: false }));
+    // A Fast row is a second selector for the same model, so it inherits the capabilities the
+    // base row declared. Without them opencode would gate images on exactly the row a user who
+    // turned Fast on selects (#4286).
     expect(expanded.v1.models["remote/model--fast"]).toEqual({
       name: "Remote Model Fast (remote)", limit: { context: 8192, output: 8192 },
+      attachment: true, modalities: { input: ["text", "image"], output: ["text"] },
     });
     expect(expanded.v2.models["remote/model--fast"]).toEqual({
       name: "Remote Model Fast (remote)", limit: { context: 8192, output: 8192 },
+      attachment: true, modalities: { input: ["text", "image"], output: ["text"] },
       variants: [
         { id: "high", settings: { reasoningEffort: "high" } },
         { id: "ultra", settings: { reasoningEffort: "ultra" } },
@@ -769,6 +774,12 @@ describe("hub-resolved Fast exports", () => {
     expect(remote.v2.settings).toEqual(remote.v1.options);
   });
 
+  test("each generation owns its modalities map, so an edit to one cannot move the other", () => {
+    const blocks = opencodeProviderBlocks(BASE_URL, [eligible], cfg({ fastRows: false }));
+    blocks.v1.models["remote/model"]!.modalities!.input.push("audio");
+    expect(blocks.v2.models["remote/model"]!.modalities!.input).toEqual(["text", "image"]);
+  });
+
   test("both CLI projections retain hub true/false/absence despite conflicting local settings", () => {
     for (const localFast of [false, true]) {
       for (const hubFast of [undefined, false, true]) {
@@ -805,11 +816,29 @@ describe("hub-resolved Fast exports", () => {
     expect(Object.keys(blocks.v1.models)).toEqual(["remote/model"]);
     expect(Object.keys(blocks.v2.models)).toEqual(["remote/model"]);
   });
+
+  test("a disabled duplicate cannot donate its modalities to the visible row", () => {
+    // `exportModelsFromProxyRows` used to re-join modalities from the RAW `/api/models` rows,
+    // keyed by `namespaced` with the first row winning — so a hidden or disabled duplicate
+    // could hand its modality list to the visible entry, the same donation the availability and
+    // ladder rules already refuse. The catalog entry carries them now, so the row that is
+    // exported is the row that declares.
+    const shadowed = { ...eligible, fastRowAvailable: false, inputModalities: ["text"] };
+    const rows = [
+      { ...eligible, fastRowAvailable: false, disabled: true, inputModalities: ["text", "image", "audio"] },
+      shadowed,
+    ];
+    const config = cfg({ fastRows: false });
+    expect(exportModelsFromProxyRows(rows, config)).toEqual([shadowed]);
+    const blocks = opencodeProviderBlocks(BASE_URL, opencodeCatalogFromProxyRows(rows, config), config);
+    expect(blocks.v1.models["remote/model"]!.modalities).toEqual({ input: ["text"], output: ["text"] });
+    expect(blocks.v2.models["remote/model"]!.modalities).toEqual({ input: ["text"], output: ["text"] });
+  });
 });
 
 describe("EXPORT_CLIENTS registry", () => {
-  test("covers exactly the thirteen file-toggle clients", () => {
-    expect(EXPORT_CLIENT_IDS).toEqual(["opencode", "pi", "omp", "hermes", "openclaw", "kimi", "gajae", "dsh", "mcode", "zcode", "prime", "aside", "raycast"]);
+  test("covers exactly the fourteen file-toggle clients", () => {
+    expect(EXPORT_CLIENT_IDS).toEqual(["opencode", "pi", "omp", "hermes", "openclaw", "kimi", "gajae", "dsh", "mcode", "zcode", "prime", "aside", "raycast", "omo", "cline"]);
     for (const id of EXPORT_CLIENT_IDS) expect(isExportClientId(id)).toBe(true);
     // The exception clients keep their own surfaces and are not export clients.
     expect(isExportClientId("claude-desktop")).toBe(false);
diff --git a/tests/config/yaml-fragment-source.test.ts b/tests/config/yaml-fragment-source.test.ts
index 68450fb7f9..49112f49f0 100644
--- a/tests/config/yaml-fragment-source.test.ts
+++ b/tests/config/yaml-fragment-source.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { patchYamlFragmentSource } from "../../src/integrations/omp-yaml-source";
+import { patchYamlFragmentSource, yamlFragmentUnsupportedStyle } from "../../src/integrations/omp-yaml-source";
 
 const DSH_PATH = ["llm-pi-ai", "providers", "opencodex"] as const;
 const VALUE = { api: "openai-responses", baseURL: "http://127.0.0.1:10100/v1" };
@@ -31,6 +31,55 @@ describe("generic source-preserving YAML fragment mutation", () => {
     expect(patched).toEndWith("# tail\n");
   });
 
+  // #4260: the DSH toggle wrote nothing and blamed comments or formatting. Both
+  // shapes below are what a DSH-managed file looks like before any provider
+  // exists, and neither contains a comment.
+  test("adopts an empty providers container, whether block or inline", () => {
+    const expected = {
+      "llm-pi-ai": { providers: { opencodex: VALUE } },
+      "ui-theme": { preference: "system" },
+    };
+    const sources = {
+      "valueless block key": "llm-pi-ai:\n  providers:\nui-theme:\n  preference: system\n",
+      "empty inline map": "llm-pi-ai:\n  providers: {}\nui-theme:\n  preference: system\n",
+      "empty inline map, inner space": "llm-pi-ai:\n  providers: {  }\nui-theme:\n  preference: system\n",
+    };
+    for (const [label, source] of Object.entries(sources)) {
+      const patched = upsert(source, expected);
+      expect(patched, label).not.toBeNull();
+      expect(Bun.YAML.parse(patched!), label).toEqual(expected);
+      // The untouched sibling keeps its own bytes.
+      expect(patched, label).toContain("ui-theme:\n  preference: system\n");
+      expect(yamlFragmentUnsupportedStyle(source, DSH_PATH), label).toBe(false);
+    }
+  });
+
+  // Still refused — re-rendering a user's populated flow collection is exactly
+  // what this module exists not to do — but the cause is now nameable, so the
+  // caller stops pointing at a comment that is not there.
+  test("names a populated flow container as its own refusal cause", () => {
+    const multiline = [
+      "llm-pi-ai:",
+      "  providers:",
+      "    {",
+      "      native:",
+      "        {",
+      "          api: openai-completions",
+      "        }",
+      "    }",
+      "ui-theme:",
+      "  preference: system",
+      "",
+    ].join("\n");
+    const inline = "llm-pi-ai:\n  providers: { native: { api: openai-completions } }\n";
+    for (const source of [multiline, inline]) {
+      const expected = Bun.YAML.parse(source) as Record<string, unknown>;
+      ((expected["llm-pi-ai"] as { providers: Record<string, unknown> }).providers).opencodex = VALUE;
+      expect(upsert(source, expected)).toBeNull();
+      expect(yamlFragmentUnsupportedStyle(source, DSH_PATH)).toBe(true);
+    }
+  });
+
   test("creates every missing container and preserves CRLF plus missing final newline", () => {
     const source = "agent-default-model: native\r\nother: keep";
     const expected = {
diff --git a/tests/e2e-style/phase100-native-parity.test.ts b/tests/e2e-style/phase100-native-parity.test.ts
index fa60965738..04088ace30 100644
--- a/tests/e2e-style/phase100-native-parity.test.ts
+++ b/tests/e2e-style/phase100-native-parity.test.ts
@@ -59,7 +59,7 @@ describe("Phase 100 Codex-native parity smoke", () => {
       adapter: "openai-chat",
       baseUrl: "https://routed.example/v1",
       apiKey: "routed-key",
-      noVisionModels: ["deepseek-v4-pro"],
+      noVisionModels: ["deepseek-v4-flash"],
     };
     const forwardProvider: OcxProviderConfig = {
       adapter: "openai-responses",
@@ -76,9 +76,9 @@ describe("Phase 100 Codex-native parity smoke", () => {
     };
 
     const catalog = buildCatalogEntries(nativeTemplate(), ["gpt-5.5"], [
-      { provider: "opencode-go", id: "deepseek-v4-pro" },
+      { provider: "opencode-go", id: "deepseek-v4-flash" },
     ], undefined, false);
-    const routed = catalog.find(entry => entry.slug === "opencode-go/deepseek-v4-pro");
+    const routed = catalog.find(entry => entry.slug === "opencode-go/deepseek-v4-flash");
     expect(routed).toMatchObject({
       web_search_tool_type: "text_and_image",
       supports_search_tool: true,
@@ -90,7 +90,7 @@ describe("Phase 100 Codex-native parity smoke", () => {
     expect(routed).not.toHaveProperty("supports_websockets");
 
     const parsed = parseRequest({
-      model: "opencode-go/deepseek-v4-pro",
+      model: "opencode-go/deepseek-v4-flash",
       stream: true,
       input: "Search current docs, then answer.",
       tools: [
@@ -106,7 +106,7 @@ describe("Phase 100 Codex-native parity smoke", () => {
       parsed,
       false,
       routedProvider,
-      "deepseek-v4-pro",
+      "deepseek-v4-flash",
       {
         providerName: "openai",
         provider: forwardProvider,
@@ -125,7 +125,7 @@ describe("Phase 100 Codex-native parity smoke", () => {
 
     const frames = await collectSse(bridgeToResponsesSSE(replay([
       { type: "error", message: "Your input exceeds the context window" },
-    ]), "deepseek-v4-pro"));
+    ]), "deepseek-v4-flash"));
     const failed = frames.find(frame => frame.event === "response.failed")?.data.response as Record<string, unknown>;
     expect(failed.error).toMatchObject({
       code: "context_length_exceeded",
diff --git a/tests/fixtures/baseten-models.json b/tests/fixtures/baseten-models.json
index 7852c4374f..bd1795c81a 100644
--- a/tests/fixtures/baseten-models.json
+++ b/tests/fixtures/baseten-models.json
@@ -2,7 +2,7 @@
   "object": "list",
   "data": [
     {
-      "id": "deepseek-ai/DeepSeek-V4-Pro"
+      "id": "thinkingmachines/inkling"
     },
     {
       "id": "moonshotai/Kimi-K2.6"
diff --git a/tests/fixtures/test-layout-expected.json b/tests/fixtures/test-layout-expected.json
index a6fef10432..b56ab03905 100644
--- a/tests/fixtures/test-layout-expected.json
+++ b/tests/fixtures/test-layout-expected.json
@@ -113,6 +113,7 @@
   "catalog-vision-sidecar-modalities.test.ts": "codex-integration",
   "catalog-zero-credit-picker.test.ts": "codex-integration",
   "chat-completions-endpoint.test.ts": "responses",
+  "chat-conversation-affinity.test.ts": "responses",
   "chat-json-sse-fallback.test.ts": "responses",
   "chat-refusal.test.ts": "responses",
   "chatgpt-device-auth.test.ts": "oauth",
@@ -145,6 +146,7 @@
   "claude-desktop-remote-hub.test.ts": "claude-integration",
   "claude-dotenv-provenance-transport.test.ts": "claude-integration",
   "claude-gateway-cache.test.ts": "claude-integration",
+  "claude-inbound-cache-stabilize.test.ts": "claude-integration",
   "claude-inbound-debug.test.ts": "claude-integration",
   "claude-inbound.test.ts": "claude-integration",
   "claude-management-api.test.ts": "claude-integration",
@@ -152,6 +154,7 @@
   "claude-messages-endpoint.test.ts": "claude-integration",
   "claude-model-info.test.ts": "claude-integration",
   "claude-models-discovery.test.ts": "claude-integration",
+  "claude-native-affinity.test.ts": "claude-integration",
   "claude-native-passthrough.test.ts": "claude-integration",
   "claude-outbound.test.ts": "claude-integration",
   "claude-shell-hook.test.ts": "claude-integration",
@@ -212,10 +215,12 @@
   "client-injection-guard.test.ts": "codex-integration",
   "client-lifecycle-lock.test.ts": "clients",
   "client-machine-listener.test.ts": "clients",
+  "cline-client.test.ts": "clients",
   "cline-pass-deepseek-v4-tool-replay.test.ts": "providers",
   "cline-pass-provider.test.ts": "providers",
   "cline-pass-reasoning-efforts.test.ts": "providers",
   "cline-provider.test.ts": "providers",
+  "cline-writer.test.ts": "clients",
   "closed-pr-branch-cleanup.test.ts": "ci-workflows",
   "codebuddy-adapter.test.ts": "providers",
   "codebuddy-protocol.test.ts": "providers",
@@ -249,6 +254,7 @@
   "codex-cli-update-zero-effect.test.ts": "codex-integration",
   "codex-composed-acceptance.test.ts": "codex-integration",
   "codex-config-generation.test.ts": "codex-integration",
+  "codex-context-owner.test.ts": "codex-integration",
   "codex-convergence-account-selectors.test.ts": "codex-integration",
   "codex-convergence-contract.test.ts": "codex-integration",
   "codex-cooldown-recovery.test.ts": "codex-integration",
@@ -366,6 +372,9 @@
   "consume-for-inspection-cancel.test.ts": "server",
   "container-bootstrap.test.ts": "service",
   "context-cap-unknown-window.test.ts": "providers",
+  "context-compat.test.ts": "codex-integration",
+  "context-history-ownership.test.ts": "server",
+  "context-history.test.ts": "server",
   "continuation-dedup.test.ts": "responses",
   "core-lab-boundary.test.ts": "lab",
   "cost-cap-unknown-evidence.test.ts": "usage",
@@ -454,6 +463,9 @@
   "desktop-profile.test.ts": "clients",
   "desktop-remote-store.test.ts": "clients",
   "destination-policy-resolved.test.ts": "routing",
+  "devin-adapter.test.ts": "providers",
+  "devin-cli-adapter.test.ts": "providers",
+  "devin-hardening.test.ts": "providers",
   "digitalocean-scaleway-provider.test.ts": "providers",
   "docs-429-failover-claims.test.ts": "ci-workflows",
   "docs-bun-source-requirement.test.ts": "ci-workflows",
@@ -531,6 +543,8 @@
   "grok-management-api.test.ts": "providers/xai",
   "grok-models-effort-list.test.ts": "providers/xai",
   "grok-orphan-adoption.test.ts": "providers/xai",
+  "grok-reset-coupon-cli.test.ts": "providers/xai",
+  "grok-reset-coupons.test.ts": "providers/xai",
   "grok-selection.test.ts": "providers/xai",
   "grok-status.test.ts": "providers/xai",
   "grok-sync.test.ts": "providers/xai",
@@ -685,6 +699,7 @@
   "model-pinned-effort.test.ts": "codex-integration",
   "model-presets.test.ts": "providers",
   "model-rename-migration.test.ts": "providers",
+  "context-window-seed-repair.test.ts": "providers",
   "model-selection-guidance.test.ts": "cli",
   "model-visibility-management-api.test.ts": "codex-integration",
   "models-feedback-callback.test.ts": "gui",
@@ -761,6 +776,7 @@
   "ollama-show-enrichment-v7.test.ts": "providers/ollama",
   "ollama-show-enrichment.test.ts": "providers/ollama",
   "ollama-show-ignore-abort.test.ts": "providers/ollama",
+  "omo-client.test.ts": "clients",
   "omp-path-contract.test.ts": "clients",
   "omp-yaml-source-inline-comments.test.ts": "clients",
   "openai-api-virtual-models.test.ts": "adapters/openai",
@@ -769,6 +785,7 @@
   "openai-chat-hardening.test.ts": "adapters/openai",
   "openai-chat-invalid-tool-call-diagnostics.test.ts": "adapters/openai",
   "openai-chat-model-suffix.test.ts": "adapters/openai",
+  "openai-chat-path-override.test.ts": "adapters/openai",
   "openai-chat-native-policy.test.ts": "adapters/openai",
   "openai-chat-parallel-stream.test.ts": "adapters/openai",
   "openai-chat-system-order.test.ts": "adapters/openai",
@@ -809,6 +826,7 @@
   "plan-video.test.ts": "videos",
   "plan.test.ts": "images",
   "policy-execution.test.ts": "routing",
+  "pool-kernel-generic-sweep.test.ts": "oauth",
   "port-reclaim.test.ts": "server",
   "ports.test.ts": "server",
   "prime-client.test.ts": "clients",
@@ -877,6 +895,9 @@
   "release-notes.test.ts": "ci-workflows",
   "release-version-line.test.ts": "ci-workflows",
   "remote-catalog.test.ts": "clients",
+  "remote-control-prototype.test.ts": "clients",
+  "remote-workspace-protocol.test.ts": "clients",
+  "remote-workspace-rpc-framing.test.ts": "clients",
   "remove-tree-helper.test.ts": "lib",
   "repo-hygiene.test.ts": "ci-workflows",
   "request-decompress.test.ts": "usage",
@@ -1015,6 +1036,7 @@
   "sidecar-settings-web-search-stream.test.ts": "vision",
   "sidecar-tracker.test.ts": "vision",
   "skill-ocx.test.ts": "ci-workflows",
+  "structure-ssot.test.ts": "ci-workflows",
   "slug-codec.test.ts": "codex-integration",
   "sponsor-presets.test.ts": "providers",
   "sse-client-frame-bounds.test.ts": "responses",
@@ -1179,5 +1201,7 @@
   "zhipu-bigmodel-responses-quota.test.ts": "providers",
   "zz-ci-api-usage-isolation.test.ts": "ci-workflows",
   "zz-ci-storage-policy-isolation.test.ts": "ci-workflows",
-  "zz-pr-coderabbit-readiness-revalidation.test.ts": "ci-workflows"
-}
+  "zz-pr-coderabbit-readiness-revalidation.test.ts": "ci-workflows",
+  "devin-cli-login.test.ts": "providers",
+  "devin-cli-authmode-migration.test.ts": "providers"
+}
\ No newline at end of file
diff --git a/tests/gui/alibaba-intl-token-plan.test.ts b/tests/gui/alibaba-intl-token-plan.test.ts
index e5fb297e0d..8ff822e5e0 100644
--- a/tests/gui/alibaba-intl-token-plan.test.ts
+++ b/tests/gui/alibaba-intl-token-plan.test.ts
@@ -28,14 +28,14 @@ describe("alibaba-token-plan-intl registry entry", () => {
   test("model list includes multi-vendor lineup", () => {
     const entry = PROVIDER_REGISTRY.find(e => e.id === "alibaba-token-plan-intl");
     expect(entry!.models).toContain("qwen3.7-max");
-    expect(entry!.models).toContain("deepseek-v4-pro");
+    expect(entry!.models).not.toContain("deepseek-v4-pro");
     expect(entry!.models).toContain("kimi-k2.7-code");
     expect(entry!.models).toContain("glm-5.2");
     expect(entry!.models).toContain("glm-5.3");
     expect(entry!.models).toContain("glm-5.3-flash");
     expect(entry!.models).toContain("MiniMax-M2.5");
     expect(entry!.models).toContain("qwen3.8-max");
-    expect(entry!.models!.length).toBe(17);
+    expect(entry!.models!.length).toBe(16);
   });
 
   test("MiniMax case-insensitive normalization is set", () => {
diff --git a/tests/gui/combo-workspace-data.test.ts b/tests/gui/combo-workspace-data.test.ts
index e3d340f2f8..e754020636 100644
--- a/tests/gui/combo-workspace-data.test.ts
+++ b/tests/gui/combo-workspace-data.test.ts
@@ -13,6 +13,7 @@ import {
   isValidComboId,
   parseComboList,
   providerQuotaStatesFromReports,
+  nextProviderQuotaStateExpiration,
   toPutBody,
   updateComboAliasDraft,
   validateComboDraft,
@@ -42,6 +43,31 @@ function quotaReport(
   };
 }
 
+describe("server-scoped Combo quota", () => {
+  test("display exhaustion without routing authority stays unknown", () => {
+    expect(providerQuotaStatesFromReports([
+      quotaReport("oauth", { fiveHourPercent: 100 }),
+      quotaReport("search", { customWindows: [{ label: "Search", percent: 100 }] }),
+    ], QUOTA_NOW)).toEqual({ oauth: "unknown", search: "unknown" });
+  });
+
+  test("uses current server routing state instead of display windows", () => {
+    expect(providerQuotaStatesFromReports([
+      quotaReport("search", { customWindows: [{ label: "Search", percent: 100 }] }, {
+        routingQuota: { state: "available", updatedAt: QUOTA_NOW, validUntil: QUOTA_NOW + 60_000 },
+      }),
+    ], QUOTA_NOW)).toEqual({ search: "available" });
+  });
+
+  test("expires routing authority at its reset boundary", () => {
+    expect(providerQuotaStatesFromReports([
+      quotaReport("spent", { fiveHourPercent: 100 }, {
+        routingQuota: { state: "exhausted", updatedAt: QUOTA_NOW - 100, validUntil: QUOTA_NOW },
+      }),
+    ], QUOTA_NOW)).toEqual({ spent: "unknown" });
+  });
+});
+
 function combo(overrides: Partial<ComboItem> = {}): ComboItem {
   return {
     id: "free",
@@ -297,87 +323,57 @@ describe("combo-workspace-data", () => {
     ]);
   });
 
-  test("derives exhausted state from USD, percentage, and custom-window evidence", () => {
+  test("accepts known routing states independently of display data", () => {
     expect(providerQuotaStatesFromReports([
-      quotaReport("usd", {
-        creditsUsd: { used: 10, limit: 10, remaining: 0, percent: 100 },
+      quotaReport("  keyed  ", { fiveHourPercent: 0 }, {
+        routingQuota: { state: "exhausted", updatedAt: QUOTA_NOW, validUntil: QUOTA_NOW + 60_000 },
       }),
-      quotaReport("percent", { fiveHourPercent: 100 }),
-      quotaReport("custom", { customWindows: [{ label: "Daily", percent: 101 }] }),
-    ], QUOTA_NOW)).toEqual({
-      usd: "exhausted",
-      percent: "exhausted",
-      custom: "exhausted",
-    });
-  });
-
-  test("keeps unlimited credits available and stale or malformed evidence unknown", () => {
-    expect(providerQuotaStatesFromReports([
-      quotaReport("unlimited", {
-        creditsUsd: { used: 0, limit: 0, remaining: 0, percent: 0, unlimited: true },
+      quotaReport("unlimited", { creditsUsd: { remaining: 0, unlimited: true } }, {
+        routingQuota: { state: "available", updatedAt: QUOTA_NOW, validUntil: QUOTA_NOW + 60_000 },
       }),
-      quotaReport("stale", { weeklyPercent: 100 }, { updatedAt: QUOTA_NOW - 30 * 60_000 }),
-      quotaReport("malformed", { fiveHourPercent: "100" }),
-      quotaReport("missing", {}),
-    ], QUOTA_NOW)).toEqual({
-      unlimited: "available",
-      stale: "unknown",
-      malformed: "unknown",
-      missing: "unknown",
-    });
+    ], QUOTA_NOW)).toEqual({ keyed: "exhausted", unlimited: "available" });
+  });
+
+  test("rejects malformed, future, stale and overlong routing lifetimes", () => {
+    const fresh = { state: "exhausted", updatedAt: QUOTA_NOW, validUntil: QUOTA_NOW + 1000 };
+    const bad = [
+      undefined, null, [], { ...fresh, state: "maybe" },
+      { ...fresh, updatedAt: "100" }, { ...fresh, updatedAt: NaN },
+      { ...fresh, updatedAt: -1 }, { ...fresh, updatedAt: QUOTA_NOW + 1 },
+      { ...fresh, updatedAt: QUOTA_NOW - 30 * 60_000 },
+      { ...fresh, validUntil: undefined }, { ...fresh, validUntil: Infinity },
+      { ...fresh, validUntil: QUOTA_NOW }, { ...fresh, validUntil: QUOTA_NOW + 30 * 60_000 + 1 },
+    ];
+    for (const routingQuota of bad) {
+      expect(providerQuotaStatesFromReports([
+        quotaReport("keyed", { weeklyPercent: 100 }, { routingQuota }),
+      ], QUOTA_NOW)).toEqual({ keyed: "unknown" });
+    }
   });
 
-  test("trims provider ids and rejects incomplete aggregate quota evidence", () => {
+  test("complete display aggregates cannot authorize a provider-wide block", () => {
     expect(providerQuotaStatesFromReports([
-      quotaReport("  openai  ", { weeklyPercent: 75 }),
       quotaReport("pool", { weeklyPercent: 100 }, {
         aggregation: {
-          kind: "capacity-weighted-v1",
-          scope: "routable-known",
-          presentation: "aggregate",
-          incomplete: true,
-          excludedAccounts: 1,
-          unknownPlanAccounts: 0,
+          kind: "capacity-weighted-v1", scope: "routable-known", presentation: "aggregate",
+          incomplete: false, includedAccounts: 2, excludedAccounts: 0, unknownPlanAccounts: 0,
+          missingQuotaAccounts: 0, pausedAccounts: 0, reauthAccounts: 0, staleQuotaAccounts: 0,
           partialWindowAccounts: 0,
+          weekly: { usedPercent: 100, includedAccounts: 2, excludedAccounts: 0, incomplete: false, updatedAt: QUOTA_NOW },
         },
       }),
-      quotaReport("malformed-pool", { weeklyPercent: 100 }, {
-        aggregation: {
-          kind: "capacity-weighted-v1",
-          scope: "routable-known",
-          presentation: "aggregate",
-          incomplete: false,
-        },
-      }),
-      quotaReport("complete-pool", { weeklyPercent: 100 }, {
-        aggregation: {
-          kind: "capacity-weighted-v1",
-          scope: "routable-known",
-          presentation: "aggregate",
-          incomplete: false,
-          includedAccounts: 2,
-          excludedAccounts: 0,
-          unknownPlanAccounts: 0,
-          missingQuotaAccounts: 0,
-          pausedAccounts: 0,
-          reauthAccounts: 0,
-          staleQuotaAccounts: 0,
-          partialWindowAccounts: 0,
-          weekly: {
-            usedPercent: 100,
-            includedAccounts: 2,
-            excludedAccounts: 0,
-            incomplete: false,
-            updatedAt: QUOTA_NOW,
-          },
-        },
-      }),
-    ], QUOTA_NOW)).toEqual({
-      openai: "available",
-      pool: "unknown",
-      "malformed-pool": "unknown",
-      "complete-pool": "exhausted",
-    });
+    ], QUOTA_NOW)).toEqual({ pool: "unknown" });
+  });
+
+  test("conflicting duplicate rows stay unknown and the next valid expiry is selected", () => {
+    const rows = [
+      quotaReport("keyed", {}, { routingQuota: { state: "available", updatedAt: QUOTA_NOW, validUntil: QUOTA_NOW + 5000 } }),
+      quotaReport("keyed", {}, { routingQuota: { state: "exhausted", updatedAt: QUOTA_NOW, validUntil: QUOTA_NOW + 1000 } }),
+      quotaReport("bad", {}, { routingQuota: { state: "exhausted", updatedAt: QUOTA_NOW, validUntil: QUOTA_NOW - 1 } }),
+    ];
+    expect(providerQuotaStatesFromReports(rows, QUOTA_NOW)).toEqual({ keyed: "unknown", bad: "unknown" });
+    expect(nextProviderQuotaStateExpiration(rows, QUOTA_NOW)).toBe(QUOTA_NOW + 1000);
+    expect(nextProviderQuotaStateExpiration(rows, QUOTA_NOW + 5000)).toBeUndefined();
   });
 
   test("combo quota excludes disabled targets and disables only when every usable target is exhausted", () => {
diff --git a/tests/gui/integrations-invariants.test.ts b/tests/gui/integrations-invariants.test.ts
index 47b196b688..78e0d20f2c 100644
--- a/tests/gui/integrations-invariants.test.ts
+++ b/tests/gui/integrations-invariants.test.ts
@@ -3,6 +3,8 @@ import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync,
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { EXPORT_CLIENTS, EXPORT_CLIENT_IDS, type ExportModel } from "../../src/clients/config-export";
+import { createClineIO } from "../../src/integrations/cline-io";
+import { parseClineDocument } from "../../src/integrations/cline-document";
 import { parseConfig } from "../../src/integrations/config-io";
 import { INTEGRATION_CLIENTS, INTEGRATION_CLIENT_IDS, type IntegrationClientId } from "../../src/integrations/registry";
 import { createIntegrationStateStore, type IntegrationStateStore } from "../../src/integrations/store";
@@ -78,9 +80,9 @@ afterEach(() => {
 });
 
 describe("the client registries cannot drift apart", () => {
-  test("every list of clients holds exactly the same thirteen ids", async () => {
+  test("every list of clients holds exactly the same registered ids", async () => {
     /*
-     * Five lists name the same thirteen clients, and two of them are maintained by
+     * Five lists name the same registered clients, and two of them are maintained by
      * hand: the GUI cannot import the backend registry, because that would
      * pull node:os and node:path into the browser bundle. A client added
      * server-side renders no row until someone remembers the tuple, and the
@@ -91,7 +93,7 @@ describe("the client registries cannot drift apart", () => {
     const guiRouting = await import("../../gui/src/app-routing");
 
     const expected = [...EXPORT_CLIENT_IDS].sort();
-    expect(expected).toHaveLength(13);
+    expect(expected).toHaveLength(15);
 
     expect([...INTEGRATION_CLIENT_IDS].sort()).toEqual(expected);
     expect([...gui.CLIENTS].sort()).toEqual(expected);
@@ -115,7 +117,7 @@ describe("the client registries cannot drift apart", () => {
     expect(INTEGRATION_CLIENTS.dsh.sourcePreservingYaml?.path).toEqual([
       "llm-pi-ai", "providers", "opencodex",
     ]);
-    expect(INTEGRATION_CLIENT_IDS.filter(id => INTEGRATION_CLIENTS[id].writerLock)).toEqual(["dsh", "mcode"]);
+    expect(INTEGRATION_CLIENT_IDS.filter(id => INTEGRATION_CLIENTS[id].writerLock)).toEqual(["dsh", "mcode", "cline"]);
     expect(INTEGRATION_CLIENTS.dsh.writerLock).toEqual({ suffix: ".lock" });
     expect(INTEGRATION_CLIENTS.mcode.writerLock).toEqual({ suffix: ".lock" });
   });
@@ -157,6 +159,7 @@ describe("the journal is metadata, never a copy of the file", () => {
 describe("every client survives a full lifecycle", () => {
   /** A pre-existing user document in each client's own format. */
   const SEED: Record<IntegrationClientId, string> = {
+    cline: '{"version":1,"modes":{},"providers":{"mine":{"settings":{"provider":"mine"},"updatedAt":"2026-01-01T00:00:00.000Z","tokenSource":"manual"}}}\n',
     opencode: '{\n  "provider": {\n    "mine": { "npm": "keep-me" }\n  }\n}\n',
     pi: '{\n  "providers": {\n    "mine": { "api": "http://keep-me" }\n  }\n}\n',
     omp: "providers:\n  mine:\n    api: http://keep-me\n",
@@ -174,6 +177,10 @@ describe("every client survives a full lifecycle", () => {
     // Raycast's `providers` is a SEQUENCE keyed by `id`, so the user's entry is
     // a sibling element rather than a sibling map key.
     raycast: "providers:\n  - id: lmstudio\n    name: LM Studio\n    base_url: http://localhost:1234/v1\n    models: []\n",
+    // omo is senpi under an omo brand, and senpi reads Pi's models.json
+    // contract -- verified against senpi's own compiled validator, not assumed
+    // from the family resemblance (260912 plan unit, 001).
+    omo: '{\n  "providers": {\n    "mine": { "api": "http://keep-me" }\n  }\n}\n',
   };
   /** Where the seed's user-owned entry lives when the seed is a sequence. */
   const USER_ELEMENT: Partial<Record<IntegrationClientId, readonly string[]>> = {
@@ -186,7 +193,15 @@ describe("every client survives a full lifecycle", () => {
       const seed = SEED[clientId];
       writeFileSync(configPath, seed);
       const format = EXPORT_CLIENTS[clientId].format;
-      const original = parseConfig(seed, format);
+      // Paired Cline files are one logical ownership document, but remain native files on disk.
+      if (clientId === "cline") writeFileSync(join(dirname(configPath), "models.json"), '{"version":1,"providers":{}}\n');
+      const readDocument = () => {
+        if (clientId !== "cline") return parseConfig(readFileSync(configPath, "utf8"), format);
+        const read = createClineIO(store.io(), configPath, store).readText(configPath);
+        if (read.kind !== "text") throw new Error("missing Cline fixture pair");
+        return parseClineDocument(read.text);
+      };
+      const original = readDocument();
 
       const applied = applyIntegration({
         clientId, models: MODELS, config: CONFIG, port: 10100,
@@ -195,7 +210,7 @@ describe("every client survives a full lifecycle", () => {
       expect(applied.ok).toBe(true);
 
       // Our fragments are present…
-      const afterApply = parseConfig(readFileSync(configPath, "utf8"), format);
+      const afterApply = readDocument();
       const record = store.readRecords()[clientId]!;
       expect(record.fragmentPaths.length).toBeGreaterThan(0);
       // Read through the writer's own segment grammar: Raycast's path holds a
@@ -227,7 +242,7 @@ describe("every client survives a full lifecycle", () => {
        * that is what the snapshot is for. What disable owes the user is that
        * every value they had is still there and ours is gone.
        */
-      const afterDisable = parseConfig(readFileSync(configPath, "utf8"), format);
+      const afterDisable = readDocument();
       expect(afterDisable).toEqual(original);
     });
   }
diff --git a/tests/gui/provider-workspace-data.test.ts b/tests/gui/provider-workspace-data.test.ts
index 68a653f4b2..48502e5daf 100644
--- a/tests/gui/provider-workspace-data.test.ts
+++ b/tests/gui/provider-workspace-data.test.ts
@@ -34,6 +34,11 @@ import {
   bucketPresets,
   filterPresets,
   presetTier,
+  noteNeedsReveal,
+  matchesCatalogQuery,
+  sortCatalogMatches,
+  filterAccountRows,
+  dropPresetsCoveredByAccounts,
   type CatalogPreset,
 } from "../../gui/src/components/provider-catalog/provider-presets";
 import { isLocalProvider, providerKind } from "../../gui/src/provider-workspace/kind";
@@ -520,17 +525,40 @@ describe("add-provider catalog presets (WP050a)", () => {
     expect(presetTier(preset({ id: "xai", auth: "oauth" }))).toBe("paid");
   });
 
-  test("bucketPresets partitions all three tiers preserving input order", () => {
+  test("bucketPresets partitions all four catalog tabs preserving input order", () => {
     const rows = [
       preset({ id: "venice" }),
       preset({ id: "openai", adapter: "openai-responses", baseUrl: "https://chatgpt.com/backend-api/codex", auth: "forward" }),
       preset({ id: "nvidia", freeTier: true }),
       preset({ id: "groq" }),
+      preset({ id: "ollama", auth: "local", baseUrl: "http://localhost:11434/v1" }),
+      preset({ id: "vllm", baseUrl: "http://127.0.0.1:8000/v1" }),
     ];
     const buckets = bucketPresets(rows);
     expect(buckets.accounts.map(p => p.id)).toEqual(["openai"]);
     expect(buckets.free.map(p => p.id)).toEqual(["nvidia"]);
     expect(buckets.paid.map(p => p.id)).toEqual(["venice", "groq"]);
+    // The Local tab is a catalog-only split: a loopback base URL alone is enough, and a
+    // local row must not also appear under Free even though `presetTier` still calls it free.
+    expect(buckets.local.map(p => p.id)).toEqual(["ollama", "vllm"]);
+    expect(presetTier(rows[4]!)).toBe("free");
+  });
+
+  // A forward guard, not a live case: `isAccountProvider` requires the exact ChatGPT base
+  // URL, so no row is both accounts-tier and loopback today. This pins the ordering so a
+  // future widening of that classifier cannot quietly move an account row into Local.
+  test("the accounts classifier outranks the local peel", () => {
+    const buckets = bucketPresets([
+      preset({
+        id: "openai",
+        adapter: "openai-responses",
+        baseUrl: "https://chatgpt.com/backend-api/codex",
+        auth: "forward",
+      }),
+      preset({ id: "lm-studio", auth: "local", baseUrl: "http://localhost:1234/v1" }),
+    ]);
+    expect(buckets.accounts.map(p => p.id)).toEqual(["openai"]);
+    expect(buckets.local.map(p => p.id)).toEqual(["lm-studio"]);
   });
 
   test("search matches label and id only, never adapter or baseUrl", () => {
@@ -543,6 +571,69 @@ describe("add-provider catalog presets (WP050a)", () => {
     expect(filterPresets(rows, "").map(p => p.id)).toEqual(["nvidia", "groq"]);
   });
 
+  test("every nonempty note remains readable regardless of rendered width", () => {
+    expect(noteNeedsReveal("Local — key usually blank")).toBe(true);
+    expect(noteNeedsReveal("Short")).toBe(true);
+    expect(noteNeedsReveal("x".repeat(1126))).toBe(true);
+    expect(noteNeedsReveal(undefined)).toBe(false);
+    expect(noteNeedsReveal("   ")).toBe(false);
+  });
+
+  test("unified search widens by adapter EQUALITY, never by adapter prefix or base URL", () => {
+    const ollama = preset({ id: "ollama", label: "Ollama (local)", auth: "local", baseUrl: "http://localhost:11434/v1" });
+    const cursor = preset({ id: "cursor", label: "Cursor", adapter: "cursor", baseUrl: "https://api.cursor.com/v1" });
+
+    // The whole reason the haystack is not the adapter: openai-chat is the adapter of
+    // Ollama, vLLM, LM Studio, Groq, Cerebras and PackyCode, so a prefix match on
+    // "openai" would return half the catalog.
+    expect(matchesCatalogQuery(ollama, "openai")).toBe(false);
+    expect(matchesCatalogQuery(ollama, "openai-chat")).toBe(true);
+    expect(matchesCatalogQuery(cursor, "cursor")).toBe(true);
+
+    // Base URLs stay out of the haystack: otherwise "api" returns most of the Paid tab.
+    expect(matchesCatalogQuery(cursor, "api.cursor.com")).toBe(false);
+
+    // Aliases reach the Local group through the classifier, not through a substring.
+    expect(matchesCatalogQuery(ollama, "localhost")).toBe(true);
+    expect(matchesCatalogQuery(ollama, "self-hosted")).toBe(true);
+    expect(matchesCatalogQuery(cursor, "localhost")).toBe(false);
+
+    // Label and id remain the ordinary path, case-insensitively.
+    expect(matchesCatalogQuery(cursor, "CURS")).toBe(true);
+    expect(matchesCatalogQuery(cursor, "")).toBe(true);
+  });
+
+  test("search ranking is exact, then prefix, then the order the caller already chose", () => {
+    // Incoming order carries the sponsor pin, then usage rank, then label — this must
+    // only reorder for exact and prefix hits, never re-rank the tail.
+    const rows = [
+      preset({ id: "groq-cloud", label: "Groq Cloud" }),
+      preset({ id: "xyz", label: "Not a groq thing" }),
+      preset({ id: "groq", label: "Groq" }),
+    ];
+    expect(sortCatalogMatches(rows, "groq").map(p => p.id)).toEqual(["groq", "groq-cloud", "xyz"]);
+    // An empty query is browse mode: the caller's order is returned untouched.
+    expect(sortCatalogMatches(rows, "").map(p => p.id)).toEqual(["groq-cloud", "xyz", "groq"]);
+  });
+
+  test("a login in flight survives a query that does not match it", () => {
+    const rows = [
+      { id: "cursor", label: "Cursor" },
+      { id: "anthropic", label: "Anthropic (Claude)" },
+    ];
+    expect(filterAccountRows(rows, "claude").map(r => r.id)).toEqual(["anthropic"]);
+    // The busy row owns the authorization URL and the paste field; unmounting it
+    // mid-login throws away what the user is in the middle of doing.
+    expect(filterAccountRows(rows, "claude", "cursor").map(r => r.id)).toEqual(["cursor", "anthropic"]);
+    expect(filterAccountRows(rows, "").map(r => r.id)).toEqual(["cursor", "anthropic"]);
+  });
+
+  test("a provider that already has a login row is not also listed as a preset", () => {
+    const presets = [preset({ id: "openai", label: "OpenAI" }), preset({ id: "groq", label: "Groq" })];
+    expect(dropPresetsCoveredByAccounts(presets, [{ id: "openai" }]).map(p => p.id)).toEqual(["groq"]);
+    expect(dropPresetsCoveredByAccounts(presets, []).map(p => p.id)).toEqual(["openai", "groq"]);
+  });
+
 });
 
 describe("provider kind classification (WP080a)", () => {
diff --git a/tests/gui/volcengine-providers.test.ts b/tests/gui/volcengine-providers.test.ts
index c6bcf2c743..868a5bbc89 100644
--- a/tests/gui/volcengine-providers.test.ts
+++ b/tests/gui/volcengine-providers.test.ts
@@ -34,7 +34,6 @@ describe("Volcengine Ark providers", () => {
         "doubao-seed-2-1-pro-260628",
         "doubao-seed-2-1-turbo-260628",
         "doubao-seed-evolving",
-        "deepseek-v4-pro-260425",
         "deepseek-v4-flash-260425",
         "deepseek-v3-2-251201",
         "glm-5-2-260617",
@@ -57,7 +56,6 @@ describe("Volcengine Ark providers", () => {
       models: [
         "ark-code-latest",
         "doubao-seed-2.0-code",
-        "deepseek-v4-pro",
         "deepseek-v4-flash",
         "glm-5.3",
         "glm-5.3-flash",
@@ -73,14 +71,12 @@ describe("Volcengine Ark providers", () => {
       // #1057: per-model ladders. Since the V4 Pro GA (DeepSeek-V4-Pro-0813) the
       // vendor table is identical for both models; `xhigh` stays an unadvertised alias.
       modelReasoningEfforts: {
-        "deepseek-v4-pro": ["low", "high", "max"],
         "deepseek-v4-flash": ["low", "high", "max"],
       },
       modelReasoningEffortMap: {
-        "deepseek-v4-pro": { low: "low", medium: "high", high: "high", xhigh: "high", max: "max" },
         "deepseek-v4-flash": { low: "low", medium: "high", high: "high", xhigh: "high", max: "max" },
       },
-      preserveReasoningContentModels: ["deepseek-v4-pro", "deepseek-v4-flash"],
+      preserveReasoningContentModels: ["deepseek-v4-flash"],
     });
     expect(PROVIDER_REGISTRY.find(provider => provider.id === "volcengine-agent-plan")).toMatchObject({
       label: "Volcengine Ark Agent Plan",
@@ -89,9 +85,8 @@ describe("Volcengine Ark providers", () => {
       adapter: "openai-responses",
       authKind: "key",
       preserveCustomDestination: true,
-      defaultModel: "deepseek-v4-pro",
+      defaultModel: "deepseek-v4-flash",
       models: [
-        "deepseek-v4-pro",
         "deepseek-v4-flash",
         "glm-5.3",
         "glm-5.3-flash",
@@ -118,13 +113,13 @@ describe("Volcengine Ark providers", () => {
       baseUrl: "https://ark.cn-beijing.volces.com/api/coding/v3",
       defaultModel: "ark-code-latest",
       liveModels: false,
-      preserveReasoningContentModels: ["deepseek-v4-pro", "deepseek-v4-flash"],
+      preserveReasoningContentModels: ["deepseek-v4-flash"],
     });
     expect(KEY_LOGIN_PROVIDERS["volcengine-agent-plan"]).toMatchObject({
       baseUrl: "https://ark.cn-beijing.volces.com/api/plan/v3",
       responsesPath: "/responses",
       adapter: "openai-responses",
-      defaultModel: "deepseek-v4-pro",
+      defaultModel: "deepseek-v4-flash",
       liveModels: false,
     });
     for (const id of ["volcengine", "volcengine-coding-plan", "volcengine-agent-plan"]) {
@@ -147,7 +142,7 @@ describe("Volcengine Ark providers", () => {
         },
       },
     };
-    const route = routeModel(config, "volcengine-agent-plan/deepseek-v4-pro");
+    const route = routeModel(config, "volcengine-agent-plan/deepseek-v4-flash");
     expect(route.provider.responsesPath).toBe("/responses");
 
     const request = createResponsesPassthroughAdapter(route.provider).buildRequest({
@@ -215,7 +210,7 @@ describe("Volcengine Ark providers", () => {
     expect(body).not.toHaveProperty("reasoning_effort");
   });
 
-  test.each(["deepseek-v4-pro", "deepseek-v4-flash"])(
+  test.each(["deepseek-v4-flash"])(
     "preserves %s tool-call reasoning and maps Codex efforts on Coding Plan",
     modelId => {
       const config: OcxConfig = {
@@ -316,11 +311,11 @@ describe("Volcengine Ark providers", () => {
       },
     });
     const request = createResponsesPassthroughAdapter(postBody.provider).buildRequest({
-      modelId: "deepseek-v4-pro",
+      modelId: "deepseek-v4-flash",
       context: { messages: [] },
       stream: true,
       options: {},
-      _rawBody: { model: "deepseek-v4-pro", input: "ping", stream: true },
+      _rawBody: { model: "deepseek-v4-flash", input: "ping", stream: true },
     }, { headers: new Headers() });
     expect(request.url).toBe("https://ark.cn-beijing.volces.com/api/plan/v3/responses");
   });
diff --git a/tests/oauth/generic-oauth-failover.test.ts b/tests/oauth/generic-oauth-failover.test.ts
index 48fb2782ec..fbf47c776a 100644
--- a/tests/oauth/generic-oauth-failover.test.ts
+++ b/tests/oauth/generic-oauth-failover.test.ts
@@ -9,6 +9,7 @@ import {
   hasFailoverAccountQuorum,
   isGenericFailoverProvider,
   isGenericOAuthFailoverEnabled,
+  noteGenericPoolSelection,
   preferredInitialAccount,
   rotateGenericOAuthAccountOn429,
 } from "../../src/oauth/generic-account-failover";
@@ -525,3 +526,131 @@ describe("#2807 a 429 rotation pairs the bearer with its OWN origin", () => {
     expect(rotated.baseUrl).toBe(CANONICAL);
   });
 });
+
+describe("#695 the generic pool consumes its persisted strategy behind pool.kernel", () => {
+  /** Proactive preference on, plus whichever strategy this case is about. */
+  function kernelConfig(strategy?: "quota" | "round-robin" | "fill-first", extra: Record<string, unknown> = {}): OcxConfig {
+    return {
+      pool: { kernel: true },
+      providers: {
+        xai: {
+          ...OAUTH_PROVIDER,
+          oauthAccountFailover: { enabled: true, ...(strategy ? { strategy } : {}), ...extra },
+        },
+      },
+    } as unknown as OcxConfig;
+  }
+
+  test("round-robin rotates a provider with no quota data at all", async () => {
+    const ids = await seed(3);
+    await setActiveAccount("xai", ids[0]!);
+    // Deliberately NO quota is cached. This is the case the evidence guard refuses outright,
+    // and it is exactly where round-robin is the point: with nothing measured there is no
+    // ranking to make, only a turn to take.
+    const cfg = kernelConfig("round-robin");
+
+    const served: string[] = [];
+    for (let i = 0; i < 4; i += 1) {
+      const preferred = preferredInitialAccount(cfg, "xai");
+      const account = preferred ?? getAccountSet("xai")!.activeAccountId!;
+      served.push(account);
+      // Admission is what advances the ring; the proposal above only peeks.
+      noteGenericPoolSelection(cfg, "xai", account);
+    }
+    expect(new Set(served).size).toBeGreaterThan(1);
+  });
+
+  test("round-robin is a no-op while pool.kernel is off", async () => {
+    const ids = await seed(3);
+    await setActiveAccount("xai", ids[0]!);
+    const off = {
+      providers: { xai: { ...OAUTH_PROVIDER, oauthAccountFailover: { enabled: true, strategy: "round-robin" } } },
+    } as unknown as OcxConfig;
+
+    for (let i = 0; i < 4; i += 1) {
+      // Same roster, same strategy, flag off: the pre-kernel answer is null every time,
+      // because no quota was ever measured. Reversibility is the whole point of the flag.
+      expect(preferredInitialAccount(off, "xai")).toBeNull();
+      noteGenericPoolSelection(off, "xai", ids[0]!);
+    }
+  });
+
+  test("fill-first holds the active account under its threshold and advances over it", async () => {
+    const ids = await seed(3);
+    const sorted = [...ids].sort((left, right) => left.localeCompare(right));
+    const active = sorted[0]!;
+    await setActiveAccount("xai", active);
+    const cfg = kernelConfig("fill-first", { autoSwitchThreshold: 80 });
+
+    setCachedProviderAccountQuotaForTests("xai", active, { weeklyPercent: 40, updatedAt: Date.now() });
+    // Under threshold: fill-first is supposed to keep filling this one.
+    expect(preferredInitialAccount(cfg, "xai")).toBeNull();
+
+    setCachedProviderAccountQuotaForTests("xai", active, { weeklyPercent: 90, updatedAt: Date.now() });
+    // Over threshold: it advances, and to the NEXT account in the sorted roster rather than
+    // to whichever id the login order happened to put first.
+    expect(preferredInitialAccount(cfg, "xai")).toBe(sorted[1]!);
+  });
+
+  test("fill-first advances through the sorted roster, not the eligible subset", async () => {
+    const ids = await seed(3);
+    const sorted = [...ids].sort((left, right) => left.localeCompare(right));
+    const active = sorted[0]!;
+    await setActiveAccount("xai", active);
+    const cfg = kernelConfig("fill-first", { autoSwitchThreshold: 80 });
+    setCachedProviderAccountQuotaForTests("xai", active, { weeklyPercent: 95, updatedAt: Date.now() });
+
+    // The successor is out of service, so the walk has to step OVER it and land on the third
+    // account. Walking the eligible subset instead would wrap from a shorter list and pick a
+    // different account -- the bug the shared kernel carries a stableAll argument to avoid.
+    await markAccountNeedsReauth("xai", sorted[1]!, true);
+    expect(preferredInitialAccount(cfg, "xai")).toBe(sorted[2]!);
+  });
+
+  test("quota keeps its pre-kernel answer with the flag on", async () => {
+    const ids = await seed(2);
+    await setActiveAccount("xai", ids[0]!);
+    // 100, not 99: the quota path only leaves an active account once it is exhausted or
+    // cooled. A merely busy account keeps serving, and that is the pre-kernel rule this case
+    // is here to pin.
+    setCachedProviderAccountQuotaForTests("xai", ids[0]!, { weeklyPercent: 100, updatedAt: Date.now() });
+    setCachedProviderAccountQuotaForTests("xai", ids[1]!, { weeklyPercent: 10, updatedAt: Date.now() });
+
+    // An explicit "quota" and no strategy at all must answer identically: quota IS the
+    // pre-kernel path, so the flag must not change it.
+    expect(preferredInitialAccount(kernelConfig("quota"), "xai")).toBe(ids[1]!);
+    expect(preferredInitialAccount(kernelConfig(), "xai")).toBe(ids[1]!);
+  });
+
+  test("a 429 under round-robin rotates instead of ranking", async () => {
+    const ids = await seed(3);
+    await setActiveAccount("xai", ids[0]!);
+    // Quota evidence pointing SOMEWHERE ELSE is what makes this case mean anything. With no
+    // evidence the pre-kernel path hands the ring back untouched and lands on the same
+    // account round-robin would, so the test would pass whether or not the branch exists.
+    setCachedProviderAccountQuotaForTests("xai", ids[1]!, { weeklyPercent: 80, updatedAt: Date.now() });
+    setCachedProviderAccountQuotaForTests("xai", ids[2]!, { weeklyPercent: 5, updatedAt: Date.now() });
+    const next = rotateGenericOAuthAccountOn429(kernelConfig("round-robin"), "xai", ids[0]!, null);
+    expect(next).not.toBeNull();
+    expect(next).not.toBe(ids[0]!);
+    // Round-robin takes its turn. Quota would have chased the roomier third account.
+    expect(next).toBe(ids[1]!);
+  });
+
+  test("a 429 under fill-first leaves the cooled account rather than holding it", async () => {
+    const ids = await seed(3);
+    const sorted = [...ids].sort((left, right) => left.localeCompare(right));
+    await setActiveAccount("xai", sorted[0]!);
+    const cfg = kernelConfig("fill-first", { autoSwitchThreshold: 80 });
+    // Well under threshold: the initial-preference rule would keep this account. The 429 path
+    // must not, because the account it would hold is the one that just failed.
+    setCachedProviderAccountQuotaForTests("xai", sorted[0]!, { weeklyPercent: 10, updatedAt: Date.now() });
+    // The successor is the BUSIER of the two survivors, so quota ranking would skip past it.
+    // Fill-first still takes it: filling one account before opening the next is the point.
+    setCachedProviderAccountQuotaForTests("xai", sorted[1]!, { weeklyPercent: 70, updatedAt: Date.now() });
+    setCachedProviderAccountQuotaForTests("xai", sorted[2]!, { weeklyPercent: 5, updatedAt: Date.now() });
+
+    const next = rotateGenericOAuthAccountOn429(cfg, "xai", sorted[0]!, null);
+    expect(next).toBe(sorted[1]!);
+  });
+});
diff --git a/tests/oauth/oauth-callback-server.test.ts b/tests/oauth/oauth-callback-server.test.ts
index a327e1df0d..cd7a353a7f 100644
--- a/tests/oauth/oauth-callback-server.test.ts
+++ b/tests/oauth/oauth-callback-server.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { OAuthCallbackFlow } from "../../src/oauth/callback-server";
+import { OAuthCallbackFlow, type OAuthCallbackFlowOptions } from "../../src/oauth/callback-server";
 import type { OAuthController, OAuthCredentials } from "../../src/oauth/types";
 
 class TestFlow extends OAuthCallbackFlow {
@@ -117,3 +117,108 @@ describe("OAuth callback server defaults", () => {
     }
   });
 });
+
+
+/** A barrier-owned login: readiness follows callback registration, and cleanup always settles it. */
+function startCallbackLogin(options: OAuthCallbackFlowOptions, holdExchange?: Promise<void>) {
+  const controller = new AbortController();
+  const ready = Promise.withResolvers<void>();
+  let deadline: ReturnType<typeof setTimeout> | undefined;
+  class HeldFlow extends ManualFallbackFlow {
+    override async exchangeToken(code: string, state: string, redirectUri: string): Promise<OAuthCredentials> {
+      await holdExchange;
+      return super.exchangeToken(code, state, redirectUri);
+    }
+  }
+  const flow = new HeldFlow({
+    signal: controller.signal,
+    onAuth: () => queueMicrotask(() => {
+      deadline = setTimeout(() => controller.abort(new Error("callback test deadline")), 5_000);
+      ready.resolve();
+    }),
+  }, options);
+  const login = flow.login();
+  void login.catch(error => ready.reject(error));
+  return {
+    flow, login, ready: ready.promise, signal: controller.signal,
+    stop() {
+      if (deadline !== undefined) clearTimeout(deadline);
+      controller.abort(new Error("callback test cleanup"));
+    },
+  };
+}
+
+async function availableCallbackPort(): Promise<number> {
+  const server = Bun.serve({ hostname: "127.0.0.1", port: 0, reusePort: false, fetch: () => new Response("probe") });
+  const port = server.port;
+  await server.stop(true);
+  return port;
+}
+
+async function callbackResponse(port: number, path: string, signal: AbortSignal): Promise<Response> {
+  const response = await fetch(`http://127.0.0.1:${port}${path}`, { signal });
+  await response.text();
+  return response;
+}
+
+for (const favicon of [false, true]) {
+  test(favicon
+    ? "a non-callback request cannot pin the socket to the retiring flow"
+    : "a retired flow cannot serve the next login on the same callback port", async () => {
+    const port = await availableCallbackPort();
+    const options = { preferredPort: port, callbackPath: "/callback", callbackHostname: "127.0.0.1", callbackBindHostname: "127.0.0.1" };
+    const exchange = Promise.withResolvers<void>();
+    const started: ReturnType<typeof startCallbackLogin>[] = [];
+    try {
+      const first = startCallbackLogin(options, exchange.promise);
+      started.push(first);
+      await first.ready;
+      const firstState = first.flow.generated!.state;
+      const success = await callbackResponse(port, `/callback?code=first-code&state=${firstState}`, first.signal);
+      expect(success.status).toBe(200);
+      expect(success.headers.get("connection")).toBe("close");
+      if (favicon) {
+        const stray = await callbackResponse(port, "/favicon.ico", first.signal);
+        expect(stray.status).toBe(404);
+        expect(stray.headers.get("connection")).toBe("close");
+      }
+      exchange.resolve();
+      await first.login;
+      const second = startCallbackLogin(options);
+      started.push(second);
+      await second.ready;
+      const secondState = second.flow.generated!.state;
+      expect(secondState).not.toBe(firstState);
+      const retired = await callbackResponse(port, `/callback?code=old-code&state=${firstState}`, second.signal);
+      expect(retired.status).toBe(400);
+      expect(retired.headers.get("connection")).toBe("close");
+      const malformed = await callbackResponse(port, "/callback", second.signal);
+      expect(malformed.status).toBe(400);
+      expect(malformed.headers.get("connection")).toBe("close");
+      const live = await callbackResponse(port, `/callback?code=second-code&state=${secondState}`, second.signal);
+      expect(live.status).toBe(200);
+      expect(live.headers.get("connection")).toBe("close");
+      await second.login;
+      expect(second.flow.exchanged?.state).toBe(secondState);
+    } finally {
+      exchange.resolve();
+      for (const flow of started) flow.stop();
+      await Promise.allSettled(started.map(flow => flow.login));
+    }
+  }, 15_000);
+}
+
+test("provider errors close the callback response without retaining the socket", async () => {
+  const port = await availableCallbackPort();
+  const flow = startCallbackLogin({ preferredPort: port, callbackHostname: "127.0.0.1", callbackBindHostname: "127.0.0.1" });
+  try {
+    await flow.ready;
+    const response = await callbackResponse(port, `/callback?error=access_denied&state=${flow.flow.generated!.state}`, flow.signal);
+    expect(response.status).toBe(500);
+    expect(response.headers.get("connection")).toBe("close");
+    await expect(flow.login).rejects.toThrow("Authorization failed");
+  } finally {
+    flow.stop();
+    await Promise.allSettled([flow.login]);
+  }
+});
diff --git a/tests/oauth/pool-kernel-generic-sweep.test.ts b/tests/oauth/pool-kernel-generic-sweep.test.ts
new file mode 100644
index 0000000000..400fc6af25
--- /dev/null
+++ b/tests/oauth/pool-kernel-generic-sweep.test.ts
@@ -0,0 +1,76 @@
+import { describe, expect, test } from "bun:test";
+import {
+  clearPoolRotationState,
+  genericPoolKey,
+  peekRoundRobinAccount,
+  reconcilePoolRotationState,
+  seedPoolRotationAccount,
+} from "../../src/oauth/pool-kernel";
+import type { GenerationContext } from "../../src/lib/state-store-sweeper";
+
+/**
+ * The rotation primitives moved out of src/codex/pool-rotation.ts so every credential
+ * kind can share them. Before the move, reconcilePoolRotationState recognised only the
+ * two dedicated pool keys and skipped everything else, so a generic OAuth provider's
+ * rotation state would have survived the removal of the very account it points at.
+ */
+function generation(n: number, oauthAccountKeys: string[]): GenerationContext {
+  return {
+    generation: n,
+    providerNames: new Set<string>(),
+    comboIds: new Set<string>(),
+    comboTargets: new Set<string>(),
+    codexAccountIds: new Set<string>(),
+    oauthAccountKeys: new Set(oauthAccountKeys),
+    configRoots: new Set<string>(),
+  } as GenerationContext;
+}
+
+describe("generic pool keys are swept", () => {
+  test("genericPoolKey namespaces a provider so it cannot collide with the dedicated kinds", () => {
+    expect(genericPoolKey("cursor")).toBe("generic:cursor");
+    expect(genericPoolKey("cursor")).not.toBe("codex");
+    expect(genericPoolKey("anthropic")).not.toBe("anthropic");
+  });
+
+  test("a generic entry survives while its account is still live", () => {
+    const key = genericPoolKey("cursor");
+    clearPoolRotationState(key);
+    seedPoolRotationAccount(key, "acct-1");
+    // Seeding pins the sticky account, so a peek over both candidates returns it.
+    expect(peekRoundRobinAccount(key, ["acct-1", "acct-2"], 5)).toBe("acct-1");
+
+    // Nothing was removed, so the sweep must report no change and leave the pin.
+    expect(reconcilePoolRotationState(generation(9001, ["cursor\u0000acct-1"]))).toBe(0);
+    expect(peekRoundRobinAccount(key, ["acct-1", "acct-2"], 5)).toBe("acct-1");
+    clearPoolRotationState(key);
+  });
+
+  test("a generic entry is dropped once its account leaves the roster", () => {
+    const key = genericPoolKey("kimi");
+    clearPoolRotationState(key);
+    seedPoolRotationAccount(key, "gone");
+    expect(peekRoundRobinAccount(key, ["gone", "still-here"], 5)).toBe("gone");
+
+    // The account is absent from this generation. Before the generic branch existed
+    // this key fell through as unknown and the stale pin survived forever.
+    expect(reconcilePoolRotationState(generation(9002, ["kimi\u0000still-here"]))).toBeGreaterThan(0);
+    expect(peekRoundRobinAccount(key, ["still-here"], 5)).toBe("still-here");
+    clearPoolRotationState(key);
+  });
+
+  test("one provider's roster does not sweep another provider's entry", () => {
+    const cursor = genericPoolKey("cursor");
+    const kimi = genericPoolKey("kimi");
+    clearPoolRotationState(cursor);
+    clearPoolRotationState(kimi);
+    seedPoolRotationAccount(cursor, "c1");
+    seedPoolRotationAccount(kimi, "k1");
+
+    expect(reconcilePoolRotationState(generation(9003, ["cursor\u0000c1", "kimi\u0000k1"]))).toBe(0);
+    expect(peekRoundRobinAccount(cursor, ["c1", "c2"], 5)).toBe("c1");
+    expect(peekRoundRobinAccount(kimi, ["k1", "k2"], 5)).toBe("k1");
+    clearPoolRotationState(cursor);
+    clearPoolRotationState(kimi);
+  });
+});
diff --git a/tests/providers/baseten-provider.test.ts b/tests/providers/baseten-provider.test.ts
index 8f3da5ed25..721b569894 100644
--- a/tests/providers/baseten-provider.test.ts
+++ b/tests/providers/baseten-provider.test.ts
@@ -79,7 +79,6 @@ describe("Baseten Model APIs provider", () => {
       },
     });
     expect(basetenEntry().modelReasoningEfforts).toEqual({
-      "deepseek-ai/DeepSeek-V4-Pro": ["low", "medium", "high", "xhigh", "max"],
       "thinkingmachines/inkling": ["low", "medium", "high", "xhigh", "max"],
       "openai/gpt-oss-120b": ["low", "medium", "high", "xhigh", "max"],
       "moonshotai/Kimi-K3": ["low", "high", "max"],
@@ -89,7 +88,6 @@ describe("Baseten Model APIs provider", () => {
       "zai-org/GLM-5.2-Fast": ["high", "max"],
     });
     expect(basetenEntry().modelReasoningEffortMap).toEqual({
-      "deepseek-ai/DeepSeek-V4-Pro": { none: "none", minimal: "minimal" },
       "thinkingmachines/inkling": { none: "none", minimal: "minimal" },
       "openai/gpt-oss-120b": { none: "none", minimal: "minimal" },
       "moonshotai/Kimi-K3": { none: "none" },
@@ -99,7 +97,6 @@ describe("Baseten Model APIs provider", () => {
       "zai-org/GLM-5.2-Fast": { none: "none" },
     });
     expect(basetenEntry().modelDefaultReasoningEfforts).toEqual({
-      "deepseek-ai/DeepSeek-V4-Pro": "medium",
       "thinkingmachines/inkling": "high",
       "openai/gpt-oss-120b": "medium",
       "moonshotai/Kimi-K3": "max",
@@ -137,7 +134,7 @@ describe("Baseten Model APIs provider", () => {
       parallelToolCalls: true,
       reasoningEfforts: [],
     });
-    expect(seed.modelReasoningEfforts?.["deepseek-ai/DeepSeek-V4-Pro"])
+    expect(seed.modelReasoningEfforts?.["thinkingmachines/inkling"])
       .toEqual(["low", "medium", "high", "xhigh", "max"]);
     expect(seed.modelInputModalities?.["moonshotai/Kimi-K2.6"])
       .toEqual(["text", "image"]);
@@ -178,10 +175,10 @@ describe("Baseten Model APIs provider", () => {
   test("routes chat completions to the shared inference host with documented tool parallelism", () => {
     const route = routeModel(
       basetenConfig(),
-      "baseten/deepseek-ai/DeepSeek-V4-Pro",
+      "baseten/thinkingmachines/inkling",
     );
     expect(route.provider.parallelToolCalls).toBe(true);
-    expect(route.modelId).toBe("deepseek-ai/DeepSeek-V4-Pro");
+    expect(route.modelId).toBe("thinkingmachines/inkling");
 
     const request = createOpenAIChatAdapter(route.provider).buildRequest({
       modelId: route.modelId,
@@ -196,12 +193,12 @@ describe("Baseten Model APIs provider", () => {
 
     expect(request.url).toBe("https://inference.baseten.co/v1/chat/completions");
     expect(request.headers.Authorization).toBe("Bearer bt-test-key");
-    expect(body.model).toBe("deepseek-ai/DeepSeek-V4-Pro");
+    expect(body.model).toBe("thinkingmachines/inkling");
     expect(body.parallel_tool_calls).toBe(true);
   });
 
   test("forwards only the documented per-model reasoning effort ladders", () => {
-    const deepseekRoute = routeModel(basetenConfig(), "baseten/deepseek-ai/DeepSeek-V4-Pro");
+    const deepseekRoute = routeModel(basetenConfig(), "baseten/thinkingmachines/inkling");
     const deepseekBody = JSON.parse(String(createOpenAIChatAdapter(deepseekRoute.provider).buildRequest({
       modelId: deepseekRoute.modelId,
       context: { messages: [{ role: "user", content: "ping", timestamp: 0 }] },
@@ -245,25 +242,25 @@ describe("Baseten Model APIs provider", () => {
     const config = withStubbedProviderFetch(basetenConfig());
     const models = (await gatherRoutedModels(config)).filter(row => row.provider === "baseten");
     expect(models.map(row => row.id)).toEqual([
-      "deepseek-ai/DeepSeek-V4-Pro",
       "moonshotai/Kimi-K2.6",
+      "thinkingmachines/inkling",
     ]);
     expect(models[0]).toMatchObject({
-      reasoningEfforts: ["low", "medium", "high", "xhigh", "max"],
-      defaultReasoningEffort: "medium",
+      inputModalities: ["text", "image"],
+      reasoningEfforts: [],
       parallelToolCalls: true,
     });
     expect(models[1]).toMatchObject({
-      inputModalities: ["text", "image"],
-      reasoningEfforts: [],
+      reasoningEfforts: ["low", "medium", "high", "xhigh", "max"],
+      defaultReasoningEffort: "high",
       parallelToolCalls: true,
     });
-    expect(routedSlug("baseten", models[0]!.id)).toBe("baseten/deepseek-ai-DeepSeek-V4-Pro");
+    expect(routedSlug("baseten", models[1]!.id)).toBe("baseten/thinkingmachines-inkling");
 
-    expect(routeModel(config, "baseten/deepseek-ai/DeepSeek-V4-Pro").modelId)
-      .toBe("deepseek-ai/DeepSeek-V4-Pro");
-    expect(routeModel(config, "baseten/deepseek-ai-DeepSeek-V4-Pro").modelId)
-      .toBe("deepseek-ai/DeepSeek-V4-Pro");
+    expect(routeModel(config, "baseten/thinkingmachines/inkling").modelId)
+      .toBe("thinkingmachines/inkling");
+    expect(routeModel(config, "baseten/thinkingmachines-inkling").modelId)
+      .toBe("thinkingmachines/inkling");
   });
 
   test("does not retarget an older same-named custom provider", () => {
diff --git a/tests/providers/cline-pass-deepseek-v4-tool-replay.test.ts b/tests/providers/cline-pass-deepseek-v4-tool-replay.test.ts
index 0cba245597..6aa7af0880 100644
--- a/tests/providers/cline-pass-deepseek-v4-tool-replay.test.ts
+++ b/tests/providers/cline-pass-deepseek-v4-tool-replay.test.ts
@@ -9,7 +9,6 @@ import { createTestTranslatorBudget } from "../helpers/translator-budget";
 
 const TARGET_MODELS = [
   "cline-pass/deepseek-v4-flash",
-  "cline-pass/deepseek-v4-pro",
 ] as const;
 
 const provider = {
diff --git a/tests/providers/cline-pass-provider.test.ts b/tests/providers/cline-pass-provider.test.ts
index 3db66eccd6..81a56923e9 100644
--- a/tests/providers/cline-pass-provider.test.ts
+++ b/tests/providers/cline-pass-provider.test.ts
@@ -14,7 +14,6 @@ const OFFICIAL_CLINE_PASS_MODELS = [
   "cline-pass/kimi-k3",
   "cline-pass/kimi-k2.7-code",
   "cline-pass/kimi-k2.6",
-  "cline-pass/deepseek-v4-pro",
   "cline-pass/deepseek-v4-flash",
   "cline-pass/mimo-v2.5",
   "cline-pass/mimo-v2.5-pro",
@@ -73,7 +72,6 @@ describe("ClinePass provider", () => {
     expect(entry?.noVisionModels).toEqual([
       "cline-pass/glm-5.3",
       "cline-pass/glm-5.2",
-      "cline-pass/deepseek-v4-pro",
       "cline-pass/deepseek-v4-flash",
       "cline-pass/mimo-v2.5-pro",
       "cline-pass/qwen3.7-max",
diff --git a/tests/providers/cline-pass-reasoning-efforts.test.ts b/tests/providers/cline-pass-reasoning-efforts.test.ts
index a0acff6078..cf45551060 100644
--- a/tests/providers/cline-pass-reasoning-efforts.test.ts
+++ b/tests/providers/cline-pass-reasoning-efforts.test.ts
@@ -9,7 +9,6 @@ const CLINE_PASS_MODELS = [
   "cline-pass/kimi-k3",
   "cline-pass/kimi-k2.7-code",
   "cline-pass/kimi-k2.6",
-  "cline-pass/deepseek-v4-pro",
   "cline-pass/deepseek-v4-flash",
   "cline-pass/mimo-v2.5",
   "cline-pass/mimo-v2.5-pro",
diff --git a/tests/providers/command-code-provider.test.ts b/tests/providers/command-code-provider.test.ts
index a3b81e408d..d588c550ee 100644
--- a/tests/providers/command-code-provider.test.ts
+++ b/tests/providers/command-code-provider.test.ts
@@ -79,7 +79,6 @@ describe("Command Code provider", () => {
     // rejected with `unsupported_model`.
     expect(apiKey?.modelReasoningEfforts).toEqual(oauth?.modelReasoningEfforts);
     expect(apiKey?.modelReasoningEfforts).toMatchObject({
-      "deepseek/deepseek-v4-pro": ["high", "max"],
       "zai-org/GLM-5": ["high", "max"],
       "zai-org/GLM-5.1": ["high", "max"],
       "zai-org/GLM-5.2-Fast": ["high", "max"],
@@ -112,6 +111,39 @@ describe("Command Code provider", () => {
     expect(commandCodeReasoningEfforts("z-ai/glm-5.3-flash-vision")).toBeUndefined();
   });
 
+  /*
+   * deepseek/deepseek-v4.1-flash and Qwen/Qwen3.8-Flash are live routes that had
+   * no row in the official table, so `supportedCommandCodeEffort` dropped the
+   * field — a client's `max` reached /alpha/generate as no reasoning parameter
+   * at all. The two presets are constructed separately and must each carry the
+   * rows; the request assertions pin that the effort survives construction.
+   */
+  test("the live v4.1-flash and Qwen3.8-Flash routes forward their own ladder", async () => {
+    const oauth = PROVIDER_REGISTRY.find(row => row.id === "command-code");
+    const apiKey = PROVIDER_REGISTRY.find(row => row.id === "commandcode");
+    for (const [label, entry] of [["oauth", oauth], ["api-key", apiKey]] as const) {
+      expect(entry?.modelReasoningEfforts?.["deepseek/deepseek-v4.1-flash"], `${label} preset ladder`)
+        .toEqual(["high", "max"]);
+      expect(entry?.modelReasoningEfforts?.["Qwen/Qwen3.8-Flash"], `${label} preset ladder`)
+        .toEqual(["low", "medium", "high", "max"]);
+    }
+    expect(commandCodeReasoningEfforts("deepseek/deepseek-v4.1-flash")).toEqual(["high", "max"]);
+    expect(commandCodeReasoningEfforts("Qwen/Qwen3.8-Flash")).toEqual(["low", "medium", "high", "max"]);
+    // The live-discovered id may arrive in any case; the lookup folds it.
+    expect(commandCodeReasoningEfforts("qwen/qwen3.8-flash")).toEqual(["low", "medium", "high", "max"]);
+
+    const deepseekMax = await builtRequest({
+      ...parsed("deepseek/deepseek-v4.1-flash"),
+      options: { reasoning: "max", maxOutputTokens: 100 },
+    });
+    expect(JSON.parse(deepseekMax.body).params.reasoning_effort).toBe("max");
+    const qwenMax = await builtRequest({
+      ...parsed("Qwen/Qwen3.8-Flash"),
+      options: { reasoning: "max", maxOutputTokens: 100 },
+    });
+    expect(JSON.parse(qwenMax.body).params.reasoning_effort).toBe("max");
+  });
+
   test("OAuth and API-key presets share only verified image capabilities", () => {
     const oauth = PROVIDER_REGISTRY.find(row => row.id === "command-code");
     const apiKey = PROVIDER_REGISTRY.find(row => row.id === "commandcode");
@@ -128,7 +160,6 @@ describe("Command Code provider", () => {
     ];
     const verifiedTextOnlyModels = [
       "deepseek/deepseek-v4-flash",
-      "deepseek/deepseek-v4-pro",
       "zai-org/GLM-5.2",
       "zai-org/GLM-5.3",
       "xai/grok-4.6",
diff --git a/tests/providers/context-window-seed-repair.test.ts b/tests/providers/context-window-seed-repair.test.ts
new file mode 100644
index 0000000000..55063afa4e
--- /dev/null
+++ b/tests/providers/context-window-seed-repair.test.ts
@@ -0,0 +1,59 @@
+import { describe, expect, test } from "bun:test";
+import { projectStaleContextWindows, STALE_CONTEXT_WINDOWS } from "../../src/providers/stale-context-window-migration";
+import type { OcxConfig } from "../../src/types";
+
+function devinConfig(windows: Record<string, number>, adapter = "devin"): OcxConfig {
+  return {
+    providers: {
+      devin: { adapter, baseUrl: "https://server.codeium.com", modelContextWindows: { ...windows } },
+    },
+  } as unknown as OcxConfig;
+}
+
+describe("stale context window migration", () => {
+  test("repairs a window the config inherited from the wrong registry seed", () => {
+    // `enrichProviderFromRegistry` is fill-only, so a config saved while the
+    // registry shipped 256k for Grok keeps reporting 256k forever. Correcting
+    // the registry fixes new installs only; this is what reaches the old ones.
+    const config = devinConfig({ "grok-4-5": 256_000, "claude-sonnet-5": 200_000 });
+    const projection = projectStaleContextWindows(config);
+    expect(projection.changed).toBe(true);
+    expect(projection.config.providers!.devin!.modelContextWindows).toMatchObject({
+      "grok-4-5": 500_000,
+      "claude-sonnet-5": 1_000_000,
+    });
+    expect(projection.warnings.join(" ")).toContain("grok-4-5 256000 -> 500000");
+  });
+
+  test("leaves a value the user chose alone", () => {
+    // The guard is an exact match on the wrong number. Anything else is a
+    // deliberate override and outranks this migration.
+    const config = devinConfig({ "grok-4-5": 300_000 });
+    const projection = projectStaleContextWindows(config);
+    expect(projection.changed).toBe(false);
+    expect(projection.config.providers!.devin!.modelContextWindows!["grok-4-5"]).toBe(300_000);
+  });
+
+  test("skips a row that no longer carries the registry adapter", () => {
+    // A `devin` row retargeted at another transport is not the provider these
+    // numbers describe, so rewriting its windows would be a guess.
+    const projection = projectStaleContextWindows(devinConfig({ "grok-4-5": 256_000 }, "openai-chat"));
+    expect(projection.changed).toBe(false);
+  });
+
+  test("is a no-op on a config with no such provider", () => {
+    const projection = projectStaleContextWindows({ providers: {} } as unknown as OcxConfig);
+    expect(projection.changed).toBe(false);
+    expect(projection.warnings).toEqual([]);
+  });
+
+  test("every entry names a real correction", () => {
+    // A from/to pair that is equal would make the migration claim a change it
+    // never performs, and an entry for another provider would silently do nothing.
+    for (const entry of STALE_CONTEXT_WINDOWS) {
+      expect(entry.from).not.toBe(entry.to);
+      expect(entry.provider).toBe("devin");
+    }
+  });
+});
+
diff --git a/tests/providers/cursor/cursor-tool-finalize-race.test.ts b/tests/providers/cursor/cursor-tool-finalize-race.test.ts
index e16a6c28f8..e44fb7c5df 100644
--- a/tests/providers/cursor/cursor-tool-finalize-race.test.ts
+++ b/tests/providers/cursor/cursor-tool-finalize-race.test.ts
@@ -1,12 +1,17 @@
 import { describe, expect, test } from "bun:test";
 import { create, toBinary } from "@bufbuild/protobuf";
-import { clientToolFinalizeGraceMsForRequest, createLiveCursorTransport } from "../../../src/adapters/cursor/live-transport";
+import {
+  clientToolFinalizeGraceMsForRequest,
+  createLiveCursorTransport,
+  shouldExtendForCheckpointCapture,
+} from "../../../src/adapters/cursor/live-transport";
 import { createTestTranslatorBudget } from "../../helpers/translator-budget";
 import { createCursorProtobufEventState } from "../../../src/adapters/cursor/protobuf-events";
 import type { CursorRunRequest, CursorServerMessage } from "../../../src/adapters/cursor/types";
 import {
   AgentServerMessageSchema,
   ExecServerMessageSchema,
+  ConversationStateStructureSchema,
   McpArgsSchema,
   McpToolCallSchema,
   ToolCallSchema,
@@ -95,18 +100,27 @@ function completedByCallIdFrame(callId: string) {
 }
 
 interface Harness {
-  feed(
-    frame: ReturnType<typeof startedFrame> | ReturnType<typeof completedFrame> | ReturnType<typeof completedByCallIdFrame>,
-  ): Promise<void>;
+  feed(frame: unknown): Promise<void>;
   events: CursorServerMessage[];
   closeCodes: number[];
   cancelled(): boolean;
 }
 
+/** A conversation checkpoint frame: the only thing that sets `capturedCheckpointBytes`. */
+function checkpointFrame() {
+  return create(AgentServerMessageSchema, {
+    message: {
+      case: "conversationCheckpointUpdate",
+      value: create(ConversationStateStructureSchema, { pendingToolCalls: ["suspended-fixture"] }),
+    },
+  });
+}
+
 function makeHarness(
   graceMs: number,
   clientToolNames: string[],
   freeformToolNames: string[] = [],
+  wantsCheckpointCapture = false,
 ): Harness {
   const transport = createLiveCursorTransport({
     provider: { adapter: "cursor", baseUrl: "https://api2.cursor.sh", apiKey: "test-token" },
@@ -115,8 +129,11 @@ function makeHarness(
     clientToolFinalizeGraceMs: graceMs,
   }) as unknown as {
     stream: unknown;
+    wantsCheckpointCapture: boolean;
     handleServerMessage: (m: unknown, s: unknown, p: (e: CursorServerMessage) => void) => Promise<void>;
   };
+  // Normally set from the run request; the harness drives handleServerMessage directly.
+  transport.wantsCheckpointCapture = wantsCheckpointCapture;
   const events: CursorServerMessage[] = [];
   const closeCodes: number[] = [];
   // Fake h2 stream: records RST_STREAM close codes; never touches the network.
@@ -255,3 +272,62 @@ describe("transport finalize race (hidden parallel sibling)", () => {
     expect(h.closeCodes).toEqual([NGHTTP2_CANCEL]);
   });
 });
+
+describe("checkpoint capture grace (#4245)", () => {
+  test("extends only when a checkpoint is wanted, absent, and not already extended", () => {
+    const base = {
+      terminated: false,
+      openToolCallCount: 0,
+      wantsCheckpointCapture: true,
+      hasCapturedCheckpoint: false,
+      alreadyExtended: false,
+    };
+    expect(shouldExtendForCheckpointCapture(base)).toBe(true);
+    // Mirrors finalizeAfterDrain's guards: a terminated state or a reopened sibling set
+    // must fall through to the normal path rather than spend the one extension.
+    expect(shouldExtendForCheckpointCapture({ ...base, terminated: true })).toBe(false);
+    expect(shouldExtendForCheckpointCapture({ ...base, terminated: undefined })).toBe(true);
+    expect(shouldExtendForCheckpointCapture({ ...base, openToolCallCount: 1 })).toBe(false);
+    // Nothing to wait for, or already waited once.
+    expect(shouldExtendForCheckpointCapture({ ...base, wantsCheckpointCapture: false })).toBe(false);
+    expect(shouldExtendForCheckpointCapture({ ...base, hasCapturedCheckpoint: true })).toBe(false);
+    expect(shouldExtendForCheckpointCapture({ ...base, alreadyExtended: true })).toBe(false);
+  });
+
+  test("a turn that never sends a checkpoint waits once, then still finalizes and cancels", async () => {
+    const h = makeHarness(20, ["echo_a"], [], true);
+    await h.feed(startedFrame("call_a", "echo_a"));
+    await h.feed(execFrame(1, "call_a", "echo_a", "A"));
+    // Past the 20 ms base grace the turn is deliberately still open: the extension is running.
+    await sleep(200);
+    expect(h.events.map(e => e.type)).not.toContain("done");
+    expect(h.cancelled()).toBe(false);
+    // The extension is bounded, so the stream still dies at a known deadline.
+    await sleep(1_600);
+    expect(h.events.map(e => e.type).filter(t => t === "done")).toHaveLength(1);
+    expect(h.closeCodes).toEqual([NGHTTP2_CANCEL]);
+  }, 10_000);
+
+  test("a checkpoint arriving during the extension finalizes early instead of waiting it out", async () => {
+    const h = makeHarness(20, ["echo_a"], [], true);
+    await h.feed(startedFrame("call_a", "echo_a"));
+    await h.feed(execFrame(1, "call_a", "echo_a", "A"));
+    await sleep(120);
+    expect(h.events.map(e => e.type)).not.toContain("done");
+
+    await h.feed(checkpointFrame());
+    // Early fire is deferred one tick so the checkpoint frame finishes being processed first.
+    await sleep(120);
+    expect(h.events.map(e => e.type).filter(t => t === "done")).toHaveLength(1);
+    expect(h.closeCodes).toEqual([NGHTTP2_CANCEL]);
+  }, 10_000);
+
+  test("without checkpoint capture wanted, the base grace is unchanged", async () => {
+    const h = makeHarness(20, ["echo_a"], [], false);
+    await h.feed(startedFrame("call_a", "echo_a"));
+    await h.feed(execFrame(1, "call_a", "echo_a", "A"));
+    await sleep(200);
+    expect(h.events.map(e => e.type).filter(t => t === "done")).toHaveLength(1);
+    expect(h.closeCodes).toEqual([NGHTTP2_CANCEL]);
+  });
+});
diff --git a/tests/providers/cursor/cursor-tool-suspended-checkpoint.test.ts b/tests/providers/cursor/cursor-tool-suspended-checkpoint.test.ts
index 4ce1152173..a365327a06 100644
--- a/tests/providers/cursor/cursor-tool-suspended-checkpoint.test.ts
+++ b/tests/providers/cursor/cursor-tool-suspended-checkpoint.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { createCursorAdapter as createCursorAdapterProduction } from "../../../src/adapters/cursor";
-import { clearCursorCheckpointsForTests, getCursorCheckpoint } from "../../../src/adapters/cursor/checkpoint-store";
+import { clearCursorCheckpointsForTests, cursorCheckpointShape, getCursorCheckpoint } from "../../../src/adapters/cursor/checkpoint-store";
 import { create, toBinary } from "@bufbuild/protobuf";
 import { ConversationStateStructureSchema } from "../../../src/adapters/cursor/gen/agent_pb";
 import type { AdapterEvent, OcxParsedRequest, OcxProviderConfig } from "../../../src/types";
@@ -94,3 +94,36 @@ describe("tool-suspended checkpoint commit (devlog 260826 050)", () => {
     clearCursorCheckpointsForTests();
   });
 });
+
+describe("checkpoint shape (#4245 coverage question)", () => {
+  test("reports counts, and pendingToolCalls is what distinguishes coverage from arrival", () => {
+    // A snapshot that knows about a suspended call.
+    expect(cursorCheckpointShape(checkpointBytes)).toEqual({
+      turns: 0,
+      turnsOld: 0,
+      rootPromptMessages: 0,
+      todos: 0,
+      pendingToolCalls: 1,
+    });
+
+    // The same structure with nothing pending: byte length alone cannot tell these apart,
+    // which is exactly why capturedBytes was not enough to settle the native-gate question.
+    const noPending = toBinary(ConversationStateStructureSchema, create(ConversationStateStructureSchema, {
+      turns: [new Uint8Array([1, 2, 3])],
+    }));
+    expect(cursorCheckpointShape(noPending)).toEqual({
+      turns: 1,
+      turnsOld: 0,
+      rootPromptMessages: 0,
+      todos: 0,
+      pendingToolCalls: 0,
+    });
+  });
+
+  test("fails closed on absent, empty, and undecodable bytes", () => {
+    expect(cursorCheckpointShape(undefined)).toBeUndefined();
+    expect(cursorCheckpointShape(new Uint8Array())).toBeUndefined();
+    // Protobuf cannot parse this; a diagnostic must never throw into the request path.
+    expect(cursorCheckpointShape(new Uint8Array([0xff, 0xff, 0xff, 0xff]))).toBeUndefined();
+  });
+});
diff --git a/tests/providers/cyber-policy-error-fidelity.test.ts b/tests/providers/cyber-policy-error-fidelity.test.ts
index f949634b3c..bff86a295a 100644
--- a/tests/providers/cyber-policy-error-fidelity.test.ts
+++ b/tests/providers/cyber-policy-error-fidelity.test.ts
@@ -273,7 +273,7 @@ describe("cyber_policy error fidelity", () => {
     });
 
     expect(events.find(e => e.type === "error")).toMatchObject({ errorType: "invalid_request" });
-    const frames = await collectSse(bridgeToResponsesSSE(replay(events), "openai/gpt-5.4"));
+    const frames = await collectSse(bridgeToResponsesSSE(replay(events), "openai/gpt-5.6-luna"));
     const failed = frames.find(frame => frame.event === "response.failed")?.data.response as Record<string, unknown>;
     expect(failed.error).toMatchObject({
       type: "invalid_request",
@@ -287,7 +287,7 @@ describe("cyber_policy error fidelity", () => {
   test("message-only cyber adapter error still classifies (no silent 502)", async () => {
     const frames = await collectSse(bridgeToResponsesSSE(replay([
       { type: "error", message: SECRET_CYBER_MESSAGE, retryable: true },
-    ]), "openai/gpt-5.4"));
+    ]), "openai/gpt-5.6-luna"));
     const failed = frames.find(frame => frame.event === "response.failed")?.data.response as Record<string, unknown>;
     expect(failed.error).toMatchObject({
       type: CYBER_POLICY_ERROR_CODE,
@@ -299,7 +299,7 @@ describe("cyber_policy error fidelity", () => {
 
     const buffered = buildResponseJSON([
       { type: "error", message: SECRET_CYBER_MESSAGE, retryable: true },
-    ], "openai/gpt-5.4");
+    ], "openai/gpt-5.6-luna");
     expect(buffered).toMatchObject({
       status: "failed",
       retryable: false,
@@ -311,7 +311,7 @@ describe("cyber_policy error fidelity", () => {
     async function* throwingEvents(): AsyncGenerator<AdapterEvent> {
       throw new Error(SECRET_CYBER_MESSAGE);
     }
-    const frames = await collectSse(bridgeToResponsesSSE(throwingEvents(), "openai/gpt-5.4"));
+    const frames = await collectSse(bridgeToResponsesSSE(throwingEvents(), "openai/gpt-5.6-luna"));
     const failed = frames.find(frame => frame.event === "response.failed")?.data.response as Record<string, unknown>;
     expect(failed).toMatchObject({
       status: "failed",
@@ -386,7 +386,7 @@ describe("cyber_policy error fidelity", () => {
           controller.close();
         },
       }),
-      "gpt-5.4",
+      "gpt-5.6-luna",
     );
     const frames = await collectSse(chatSse);
     const errorFrame = frames.find(frame => frame.data.error);
diff --git a/tests/providers/devin-adapter.test.ts b/tests/providers/devin-adapter.test.ts
new file mode 100644
index 0000000000..c31e9dda4d
--- /dev/null
+++ b/tests/providers/devin-adapter.test.ts
@@ -0,0 +1,162 @@
+import { describe, expect, test } from "bun:test";
+import { createDevinAdapter, mapOcxMessagesToDevin, mapOcxToolsToDevin } from "../../src/adapters/devin";
+import { sanitizeToolDescriptionForCognitionForTests } from "../../src/adapters/devin/cloud-direct/chat";
+import { DEVIN_MODEL_CONTEXT_WINDOWS, DEVIN_STATIC_MODELS, collapseDevinModelUid } from "../../src/adapters/devin/live-models";
+import { parseCatalogBuffer } from "../../src/adapters/devin/cloud-direct/catalog";
+import { encodeMessage, encodeString, encodeVarintField } from "../../src/adapters/devin/cloud-direct/wire";
+import { OAUTH_PROVIDERS } from "../../src/oauth";
+import { PROVIDER_REGISTRY } from "../../src/providers/registry";
+import type { OcxParsedRequest } from "../../src/types";
+
+describe("devin adapter", () => {
+  test("is registered as an oauth provider and adapter", () => {
+    expect(OAUTH_PROVIDERS.devin.defaultModel).toBe("swe-1-7");
+    const entry = PROVIDER_REGISTRY.find((row) => row.id === "devin");
+    expect(entry?.adapter).toBe("devin");
+    expect(entry?.authKind).toBe("oauth");
+    expect(entry?.liveModels).toBe(true);
+    expect(createDevinAdapter({ adapter: "devin", baseUrl: "https://server.codeium.com" }).name).toBe("devin");
+  });
+
+  test("maps user/assistant/tool history and tools", () => {
+    const parsed: OcxParsedRequest = {
+      modelId: "swe-1-7",
+      stream: true,
+      context: {
+        systemPrompt: ["be brief"],
+        messages: [
+          { role: "user", content: "hi", timestamp: 1 },
+          {
+            role: "assistant",
+            content: [
+              { type: "text", text: "calling" },
+              { type: "toolCall", id: "c1", name: "lookup", arguments: { q: "x" } },
+            ],
+            timestamp: 2,
+          },
+          { role: "toolResult", toolCallId: "c1", toolName: "lookup", content: "ok", isError: false, timestamp: 3 },
+        ],
+        tools: [{ name: "lookup", description: "lookup", parameters: { type: "object" } }],
+      },
+      options: {},
+    };
+    const history = mapOcxMessagesToDevin(parsed);
+    expect(history[0]).toEqual({ role: "system", content: "be brief" });
+    expect(history[1]).toEqual({ role: "user", content: "hi" });
+    expect(history[2]?.role).toBe("assistant");
+    expect(history[2]?.tool_calls?.[0]?.id).toBe("c1");
+    expect(history[3]).toEqual({ role: "tool", content: "ok", tool_call_id: "c1" });
+    expect(mapOcxToolsToDevin(parsed.context.tools)?.[0]?.name).toBe("lookup");
+  });
+
+  test("collapseDevinModelUid strips effort suffixes to base ids", () => {
+    expect(collapseDevinModelUid("swe-1-7")).toBe("swe-1-7");
+    expect(collapseDevinModelUid("swe-1-7-medium")).toBe("swe-1-7");
+    expect(collapseDevinModelUid("swe-1-7-lightning")).toBe("swe-1-7-lightning");
+    expect(collapseDevinModelUid("swe-1-7-lightning-medium")).toBe("swe-1-7-lightning");
+    expect(collapseDevinModelUid("gpt-5-6-sol-high")).toBe("gpt-5-6-sol");
+    expect(collapseDevinModelUid("gpt-5-6-sol-high-priority")).toBe("gpt-5-6-sol");
+    expect(collapseDevinModelUid("glm-5-2-max-1m")).toBe("glm-5-2");
+    expect(collapseDevinModelUid("claude-opus-4-8-high-fast")).toBe("claude-opus-4-8");
+    expect(collapseDevinModelUid("claude-fable-5-1-high")).toBe("claude-fable-5-1");
+    expect(collapseDevinModelUid("grok-4-5-medium")).toBe("grok-4-5");
+  });
+
+  test("loginDevin is browser-only (no local import option)", () => {
+    // The devin OAuth entry must not accept importLocal/forceLogin opts —
+    // login is always the Auth0 browser flow.
+    const entry = OAUTH_PROVIDERS.devin;
+    expect(entry.login.length).toBeLessThanOrEqual(1);
+  });
+
+  test("rewrites the Cognition blocklist trigger phrase in tool descriptions", () => {
+    // The exact 7-word phrase (capital T, single spaces) triggers Cognition's
+    // permission_denied content filter. The rewrite must break the exact match
+    // while preserving meaning.
+    const trigger = "Takes a task_id parameter identifying the task";
+    expect(sanitizeToolDescriptionForCognitionForTests(trigger)).toBe("Accepts a task_id parameter identifying the task");
+    // Case-sensitive: lowercase first letter is NOT rewritten (it doesn't trigger)
+    expect(sanitizeToolDescriptionForCognitionForTests("takes a task_id parameter identifying the task"))
+      .toBe("takes a task_id parameter identifying the task");
+    // Substring match: the phrase embedded in a larger description is rewritten
+    const full = "- Retrieves output from a running or completed task\n- Takes a task_id parameter identifying the task\n- Returns the task output";
+    const rewritten = sanitizeToolDescriptionForCognitionForTests(full);
+    expect(rewritten).not.toContain("Takes a task_id parameter identifying the task");
+    expect(rewritten).toContain("Accepts a task_id parameter identifying the task");
+    // Surrounding text is preserved
+    expect(rewritten).toContain("- Retrieves output from a running or completed task");
+    expect(rewritten).toContain("- Returns the task output");
+    // Descriptions without the trigger pass through unchanged
+    expect(sanitizeToolDescriptionForCognitionForTests("A benign description.")).toBe("A benign description.");
+  });
+
+  test("rewrites the Codex built-in tool descriptions Cognition refuses", () => {
+    // These two are Codex's own exec_command and write_stdin descriptions,
+    // verbatim. Every Codex turn carries them, so leaving them intact made the
+    // cloud refuse every request from a Codex client, a bare "hi" included.
+    // Measured against a live account: the sentences below were refused, and
+    // the rewritten forms were accepted.
+    const execCommand = "Runs a command in a PTY, returning output or a session ID for ongoing interaction.";
+    expect(sanitizeToolDescriptionForCognitionForTests(execCommand))
+      .toBe("Executes a command in a PTY, returning output or a session ID for ongoing interaction.");
+
+    const writeStdin = "Writes characters to an existing unified exec session and returns recent output.";
+    expect(sanitizeToolDescriptionForCognitionForTests(writeStdin))
+      .toBe("Sends characters to an existing unified exec session and returns recent output.");
+
+    // Cognition matches these two case-insensitively and tolerates both a
+    // doubled interior space and a missing comma, so the rewrite has to reach
+    // every variant that still gets refused rather than only the exact bytes.
+    expect(sanitizeToolDescriptionForCognitionForTests(execCommand.toLowerCase()))
+      .toContain("Executes a command in a PTY");
+    expect(sanitizeToolDescriptionForCognitionForTests(
+      "Runs a command in a PTY  returning output or a session  ID for ongoing interaction.",
+    )).toContain("Executes a command in a PTY");
+
+    // Changing any single word already clears the filter, so a description that
+    // merely resembles these must survive untouched.
+    const nearMiss = "Runs a command in a terminal, returning output or a session ID for ongoing interaction.";
+    expect(sanitizeToolDescriptionForCognitionForTests(nearMiss)).toBe(nearMiss);
+  });
+
+  test("the catalog parser reads the per-account context window", () => {
+    // ClientModelConfig #18 is the max input tokens, and it is the only
+    // first-party context-window figure Cognition exposes: the Devin CLI and
+    // Desktop model pages, the SWE-2 announcement and the Windsurf model
+    // reference all list these models without a window.
+    const withWindow = Buffer.concat([
+      encodeString(1, "SWE-2 High"),
+      encodeVarintField(18, 262_000),
+      encodeString(22, "swe-2-high"),
+    ]);
+    const withoutWindow = Buffer.concat([
+      encodeString(1, "Mystery"),
+      encodeString(22, "mystery-model"),
+    ]);
+    const catalog = parseCatalogBuffer(
+      Buffer.concat([encodeMessage(1, withWindow), encodeMessage(1, withoutWindow)]),
+      "key",
+      "https://server.codeium.com",
+    );
+    expect(catalog.byUid.get("swe-2-high")?.contextWindow).toBe(262_000);
+    // Absent rather than zero, so a caller can tell "not reported" from
+    // "reported as nothing" and keep its fallback.
+    expect(catalog.byUid.get("mystery-model")?.contextWindow).toBeUndefined();
+  });
+
+  test("the degraded-mode windows match what Cognition serves", () => {
+    // This table was wrong for nine of its eleven rows because it had been
+    // copied from each model's ORIGINAL vendor rather than measured against
+    // Cognition's catalog. The spot-checks are the three shapes of that error:
+    // a Claude row five times too small, a Grok row about half its real size,
+    // and a GPT row rounded up past what the service accepts.
+    expect(DEVIN_MODEL_CONTEXT_WINDOWS["claude-sonnet-5"]).toBe(1_000_000);
+    expect(DEVIN_MODEL_CONTEXT_WINDOWS["grok-4-5"]).toBe(500_000);
+    expect(DEVIN_MODEL_CONTEXT_WINDOWS["gpt-5-6-sol"]).toBe(1_000_000);
+    expect(DEVIN_MODEL_CONTEXT_WINDOWS["swe-2"]).toBe(262_000);
+    // Every statically advertised model needs one, or the picker reports 128k.
+    for (const model of DEVIN_STATIC_MODELS) {
+      expect(DEVIN_MODEL_CONTEXT_WINDOWS[model]).toBeGreaterThan(0);
+    }
+  });
+});
diff --git a/tests/providers/devin-cli-adapter.test.ts b/tests/providers/devin-cli-adapter.test.ts
new file mode 100644
index 0000000000..565cd08478
--- /dev/null
+++ b/tests/providers/devin-cli-adapter.test.ts
@@ -0,0 +1,342 @@
+import { join } from "node:path";
+import { describe, expect, test } from "bun:test";
+import {
+  ACP_SESSION_NEW_ID,
+  acpUpdateToEvents,
+  buildAcpPrompt,
+  initializeFrame,
+  mapAcpStopReason,
+  mapAcpUsage,
+  permissionResponseFrame,
+  sessionNewFrame,
+  sessionPromptFrame,
+} from "../../src/adapters/devin-cli/acp";
+import { DEVIN_CLI_BIN_ENV, resolveDevinCliBinary } from "../../src/adapters/devin-cli/binary";
+import { createDevinCliAdapter } from "../../src/adapters/devin-cli/adapter";
+import { PROVIDER_REGISTRY } from "../../src/providers/registry";
+import { DEVIN_CLI_MODELS, DEVIN_CLI_MODEL_CONTEXT_WINDOWS, DEVIN_CLI_DEFAULT_MODEL } from "../../src/adapters/devin-cli/models";
+import { DEVIN_MODEL_CONTEXT_WINDOWS } from "../../src/adapters/devin/live-models";
+import { formatProviderDisplayName, providerIconSrc } from "../../gui/src/provider-icons";
+import type { AdapterEvent, OcxParsedRequest } from "../../src/types";
+import { EventEmitter } from "node:events";
+import { PassThrough } from "node:stream";
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+
+describe("devin-cli registration", () => {
+  test("is an account provider sourced from the installed CLI", () => {
+    const entry = PROVIDER_REGISTRY.find((row) => row.id === "devin-cli");
+    // The preset streams over Cognition's api-server now: the CLI's own
+    // credentials.toml holds an ordinary devin-session-token, so there is no
+    // reason to spawn a child to reach the same models.
+    expect(entry?.adapter).toBe("devin");
+    // `oauth` classifies the ACCOUNT, not the transport, and is what puts the row
+    // in the dashboard Accounts tab beside `devin`.
+    expect(entry?.authKind).toBe("oauth");
+    // Off, or the row is drawn twice: an Accounts login row and a preset tile.
+    expect(entry?.dashboardPreset).toBe(false);
+    // The ACP adapter is still registered and still constructible — it is simply
+    // no longer what this provider id resolves to.
+    expect(createDevinCliAdapter({ adapter: "devin-cli", baseUrl: "https://cli.devin.ai" }).name).toBe("devin-cli");
+  });
+
+  test("both Devin providers render the Devin mark and a readable name", () => {
+    // Neither id had an icon alias, so the dashboard drew a coloured initial
+    // tile for both, and the title-cased fallback turned the local one into
+    // "Devin Cli".
+    expect(providerIconSrc("devin")).toBe("/provider-icons/devin.svg");
+    expect(providerIconSrc("devin-cli")).toBe("/provider-icons/devin.svg");
+    const englishT = ((_key: string, fallback?: string) => fallback ?? "") as Parameters<typeof formatProviderDisplayName>[1];
+    expect(formatProviderDisplayName("devin", englishT)).toBe("Devin");
+    expect(formatProviderDisplayName("devin-cli", englishT)).toBe("Devin CLI");
+  });
+
+  test("every CLI model carries its context window", () => {
+    // The provider shipped without a window table at all, so the picker used the
+    // 128k default for the whole roster — including `swe-2`, the default model,
+    // whose real window is 262k. A model added to the roster without a window
+    // silently reintroduces that, so the table is checked against the roster
+    // rather than by spot-checking one id.
+    for (const model of DEVIN_CLI_MODELS) {
+      expect(DEVIN_CLI_MODEL_CONTEXT_WINDOWS[model]).toBeGreaterThan(0);
+    }
+    expect(Object.keys(DEVIN_CLI_MODEL_CONTEXT_WINDOWS).sort()).toEqual([...DEVIN_CLI_MODELS].sort());
+    expect(DEVIN_CLI_MODEL_CONTEXT_WINDOWS[DEVIN_CLI_DEFAULT_MODEL]).toBe(262_000);
+
+    // The PRESET no longer uses this table: it streams over the cloud transport,
+    // so its windows come from the shared Devin table and, at runtime, from the
+    // account's own catalog through live discovery. The table above still governs
+    // the ACP roster for a custom-named row that selects that adapter.
+    const entry = PROVIDER_REGISTRY.find((row) => row.id === "devin-cli");
+    expect(entry?.modelContextWindows).toBe(DEVIN_MODEL_CONTEXT_WINDOWS);
+    expect(entry?.liveModels).toBe(true);
+  });
+});
+
+describe("acp handshake frames", () => {
+  test("initialize declares protocol 1 and session/new carries cwd", () => {
+    expect(initializeFrame("1.2.3")).toMatchObject({
+      jsonrpc: "2.0",
+      method: "initialize",
+      params: { protocolVersion: 1, clientInfo: { name: "opencodex", version: "1.2.3" } },
+    });
+    const withModel = sessionNewFrame("/repo", "swe-2") as { id: number; params: Record<string, unknown> };
+    expect(withModel.id).toBe(ACP_SESSION_NEW_ID);
+    expect(withModel.params).toEqual({ cwd: "/repo", mcpServers: [], model: "swe-2" });
+    // No model named means the CLI picks its own default, so the key is absent
+    // rather than present and empty.
+    expect((sessionNewFrame("/repo") as { params: Record<string, unknown> }).params).toEqual({ cwd: "/repo", mcpServers: [] });
+    expect(sessionPromptFrame("s1", "hi")).toMatchObject({
+      method: "session/prompt",
+      params: { sessionId: "s1", prompt: [{ type: "text", text: "hi" }] },
+    });
+  });
+
+  test("a permission request is refused unless the operator opted in", () => {
+    // This provider runs an agent in the operator's own tree. Auto-approving
+    // whatever a prompt asks for would make the proxy a remote shell.
+    const options = [
+      { optionId: "no", name: "Reject", kind: "reject_once" },
+      { optionId: "yes", name: "Approve", kind: "allow_once" },
+    ];
+    expect(permissionResponseFrame(9, options)).toMatchObject({ result: { outcome: { outcome: "cancelled" } } });
+    const allowed = permissionResponseFrame(9, options, true) as { result: { outcome: { optionId: string } } };
+    // Positional guessing would have taken the reject here.
+    expect(allowed.result.outcome.optionId).toBe("yes");
+    expect(
+      (permissionResponseFrame(9, [{ optionId: "accept-all", name: "Accept" }], true) as { result: { outcome: { optionId: string } } })
+        .result.outcome.optionId,
+    ).toBe("accept-all");
+    // Nothing on offer says allow, so approving would mean selecting a
+    // rejection and calling it approval.
+    expect(permissionResponseFrame(9, [{ optionId: "no", kind: "reject_once" }], true)).toMatchObject({
+      result: { outcome: { outcome: "cancelled" } },
+    });
+    expect(permissionResponseFrame(9, undefined, true)).toMatchObject({ result: { outcome: { outcome: "cancelled" } } });
+  });
+});
+
+describe("acp prompt projection", () => {
+  test("system, tool calls and tool results all survive the flattening", () => {
+    const parsed = {
+      modelId: "swe-2",
+      stream: true,
+      context: {
+        systemPrompt: ["be brief"],
+        messages: [
+          { role: "user", content: "hi", timestamp: 1 },
+          {
+            role: "assistant",
+            content: [
+              { type: "text", text: "looking" },
+              { type: "toolCall", id: "c1", name: "lookup", arguments: { q: "x" } },
+            ],
+            timestamp: 2,
+          },
+          { role: "toolResult", toolCallId: "c1", toolName: "lookup", content: "ok", isError: false, timestamp: 3 },
+        ],
+        tools: [],
+      },
+      options: {},
+    } as unknown as OcxParsedRequest;
+    const prompt = buildAcpPrompt(parsed);
+    expect(prompt).toContain("[System]\nbe brief");
+    expect(prompt).toContain("[User]\nhi");
+    // ACP takes one string, so a dropped tool loop would lose the thread.
+    expect(prompt).toContain("[call lookup id=c1]");
+    expect(prompt).toContain('{"q":"x"}');
+    expect(prompt).toContain("[result id=c1]");
+    expect(buildAcpPrompt({ ...parsed, context: { ...parsed.context, systemPrompt: [], messages: [] } })).toBe("(empty)");
+  });
+});
+
+describe("acp update mapping", () => {
+  test("message and thought chunks map to their own channels", () => {
+    expect(acpUpdateToEvents({ sessionUpdate: "agent_message_chunk", content: { type: "text", text: "a" } })).toEqual([
+      { type: "text_delta", text: "a" },
+    ]);
+    expect(acpUpdateToEvents({ sessionUpdate: "agent_thought_chunk", content: "why" })).toEqual([
+      { type: "thinking_delta", thinking: "why" },
+    ]);
+    expect(acpUpdateToEvents({ sessionUpdate: "agent_message_chunk", content: { type: "text", text: "" } })).toEqual([]);
+  });
+
+  test("the CLI's own tool calls become heartbeats, never Codex client tools", () => {
+    // Devin executes these itself inside its session. Emitting tool_call_start
+    // would either fail the turn, because the bridge rejects a tool Codex never
+    // declared, or ask Codex to run something the agent already ran. Dropping
+    // them outright is not right either: a long internal tool operation would
+    // read as upstream silence and get the working turn stall-aborted.
+    expect(acpUpdateToEvents({ sessionUpdate: "tool_call", toolCallId: "t1", title: "read", rawInput: { path: "a" } })).toEqual([
+      { type: "heartbeat" },
+    ]);
+    expect(acpUpdateToEvents({ sessionUpdate: "tool_call_update", toolCallId: "t1", status: "completed" })).toEqual([
+      { type: "heartbeat" },
+    ]);
+    expect(acpUpdateToEvents({ sessionUpdate: "plan", entries: [] })).toEqual([{ type: "heartbeat" }]);
+    expect(acpUpdateToEvents({ sessionUpdate: "something_new" })).toEqual([]);
+  });
+
+});
+
+describe("acp turn outcome", () => {
+  test("a natural end carries no stopReason", () => {
+    // The bridge reads any truthy stopReason as "this turn did not finish", so
+    // reporting end_turn would cost every clean turn its final_answer phase.
+    expect(mapAcpStopReason("end_turn")).toBeUndefined();
+    expect(mapAcpStopReason(undefined)).toBeUndefined();
+    expect(mapAcpStopReason("max_tokens")).toBe("max_tokens");
+    expect(mapAcpStopReason("refusal")).toBe("refusal");
+  });
+
+  test("usage is reported only when the agent actually counted something", () => {
+    expect(mapAcpUsage({ inputTokens: 10, outputTokens: 4 })).toEqual({ inputTokens: 10, outputTokens: 4, totalTokens: 14 });
+    expect(mapAcpUsage({ inputTokens: 1, outputTokens: 2, totalTokens: 9 })).toEqual({
+      inputTokens: 1,
+      outputTokens: 2,
+      totalTokens: 9,
+    });
+    expect(mapAcpUsage({ inputTokens: 0, outputTokens: 0 })).toBeUndefined();
+    expect(mapAcpUsage(undefined)).toBeUndefined();
+  });
+});
+
+describe("devin cli discovery", () => {
+  test("the environment override wins over every install path", () => {
+    const previous = process.env[DEVIN_CLI_BIN_ENV];
+    process.env[DEVIN_CLI_BIN_ENV] = "/custom/devin";
+    try {
+      expect(resolveDevinCliBinary({ exists: () => true, home: "/home/u", useCache: false })).toBe("/custom/devin");
+    } finally {
+      if (previous === undefined) delete process.env[DEVIN_CLI_BIN_ENV];
+      else process.env[DEVIN_CLI_BIN_ENV] = previous;
+    }
+  });
+
+  test("known install paths are preferred over a shadowed PATH entry, and absence is undefined", () => {
+    const previous = process.env[DEVIN_CLI_BIN_ENV];
+    const previousPath = process.env.PATH;
+    delete process.env[DEVIN_CLI_BIN_ENV];
+    process.env.PATH = join("/shadow", "bin");
+    try {
+      const expected = join("/home/u", ".local", "bin", "devin");
+      const shadowed = join("/shadow", "bin", "devin");
+      const exists = (p: string) => p === expected || p === shadowed;
+      expect(resolveDevinCliBinary({ exists, home: "/home/u", useCache: false })).toBe(expected);
+      expect(resolveDevinCliBinary({ exists: p => p === shadowed, home: "/home/u", useCache: false })).toBe(shadowed);
+      expect(resolveDevinCliBinary({ exists: () => false, home: "/home/u", useCache: false })).toBeUndefined();
+    } finally {
+      if (previous !== undefined) process.env[DEVIN_CLI_BIN_ENV] = previous;
+      if (previousPath === undefined) delete process.env.PATH;
+      else process.env.PATH = previousPath;
+    }
+  });
+});
+
+describe("devin-cli runTurn", () => {
+  // A fake ACP child: stdin collects the frames the adapter sends, stdout is a
+  // script the test pushes. This is the seam the coding-agent family uses, and
+  // without it the abort, crash and post-terminal paths cannot fail CI.
+  function fakeChild() {
+    const stdinWrites: string[] = [];
+    const stdout = new PassThrough();
+    const stderr = new PassThrough();
+    const child = new EventEmitter() as unknown as ChildProcessWithoutNullStreams & { exitCode: number | null; signalCode: string | null; killed: boolean };
+    Object.assign(child, {
+      stdout,
+      stderr,
+      stdin: Object.assign(new PassThrough(), {
+        write: (chunk: string) => { stdinWrites.push(String(chunk)); return true; },
+        destroyed: false,
+      }),
+      exitCode: null,
+      signalCode: null,
+      killed: false,
+      // A real child emits close after being signalled; the adapter waits for
+      // that rather than trusting `killed`, so the fake has to as well.
+      kill: () => {
+        (child as { killed: boolean }).killed = true;
+        queueMicrotask(() => child.emit("close", null));
+        return true;
+      },
+    });
+    return { child, stdout, stdinWrites };
+  }
+
+  const parsed = {
+    modelId: "swe-2",
+    stream: true,
+    context: { systemPrompt: [], messages: [{ role: "user", content: "hi", timestamp: 1 }], tools: [] },
+    options: {},
+  } as unknown as OcxParsedRequest;
+
+  async function run(script: (stdout: PassThrough, child: EventEmitter) => void) {
+    const { child, stdout, stdinWrites } = fakeChild();
+    const events: AdapterEvent[] = [];
+    process.env[DEVIN_CLI_BIN_ENV] = "/fake/devin";
+    const adapter = createDevinCliAdapter({ adapter: "devin-cli", baseUrl: "https://cli.devin.ai" }, {
+      spawn: () => { queueMicrotask(() => script(stdout, child as unknown as EventEmitter)); return child; },
+    });
+    await adapter.runTurn!(parsed, {} as never, (e) => events.push(e));
+    delete process.env[DEVIN_CLI_BIN_ENV];
+    return { events, stdinWrites };
+  }
+
+  test("a complete handshake produces exactly one terminal event, carrying usage", async () => {
+    const { events, stdinWrites } = await run((stdout) => {
+      stdout.write('{"jsonrpc":"2.0","id":1,"result":{}}\n');
+      queueMicrotask(() => {
+        stdout.write('{"jsonrpc":"2.0","id":2,"result":{"sessionId":"s1"}}\n');
+        queueMicrotask(() => {
+          stdout.write('{"jsonrpc":"2.0","method":"session/update","params":{"update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"PONG"}}}}\n');
+          // The prompt reply arrives WITHOUT a trailing newline, and more
+          // output follows it. Both used to break this adapter.
+          stdout.write('{"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn","usage":{"inputTokens":3,"outputTokens":1}}}');
+          stdout.end();
+        });
+      });
+    });
+    const terminals = events.filter((e) => e.type === "done" || e.type === "error");
+    expect(terminals).toHaveLength(1);
+    expect(terminals[0]).toMatchObject({ type: "done", usage: { inputTokens: 3, outputTokens: 1, totalTokens: 4 } });
+    // A natural end reports no stopReason.
+    expect((terminals[0] as { stopReason?: string }).stopReason).toBeUndefined();
+    expect(events.filter((e) => e.type === "text_delta")).toEqual([{ type: "text_delta", text: "PONG" }]);
+    expect(stdinWrites.join("")).toContain('"method":"session/prompt"');
+  });
+
+  test("a crash before the prompt reply is an error, not an empty success", async () => {
+    const { events } = await run((stdout, child) => {
+      stdout.write('{"jsonrpc":"2.0","id":1,"result":{}}\n');
+      queueMicrotask(() => {
+        child.emit("close", 1);
+      });
+    });
+    expect(events).toHaveLength(1);
+    expect(events[0]!.type).toBe("error");
+    expect((events[0] as { message: string }).message).toMatch(/exited \(code 1\) before answering/);
+  });
+
+  test("a session/new failure reports the CLI's reason", async () => {
+    const { events } = await run((stdout) => {
+      stdout.write('{"jsonrpc":"2.0","id":1,"result":{}}\n');
+      queueMicrotask(() => {
+        stdout.write('{"jsonrpc":"2.0","id":2,"error":{"message":"not authenticated"}}\n');
+      });
+    });
+    expect(events).toHaveLength(1);
+    expect((events[0] as { message: string }).message).toMatch(/session\/new failed: not authenticated/);
+  });
+
+  test("a malformed frame after the protocol starts fails the turn instead of vanishing", async () => {
+    // A banner line before the first frame is expected noise. A broken frame
+    // afterwards is corruption: swallowing it loses output, or waits out the
+    // ten-minute timeout for a reply that already arrived damaged.
+    const { events } = await run((stdout) => {
+      stdout.write("Devin CLI v3000.10.21\n");
+      stdout.write('{"jsonrpc":"2.0","id":1,"result":{}}\n');
+      queueMicrotask(() => stdout.write('{"jsonrpc":"2.0","id":2,"result":{"sessionId"\n'));
+    });
+    expect(events).toHaveLength(1);
+    expect((events[0] as { message: string }).message).toMatch(/malformed ACP frame/);
+  });
+});
diff --git a/tests/providers/devin-cli-authmode-migration.test.ts b/tests/providers/devin-cli-authmode-migration.test.ts
new file mode 100644
index 0000000000..2b7e2edee9
--- /dev/null
+++ b/tests/providers/devin-cli-authmode-migration.test.ts
@@ -0,0 +1,49 @@
+import { describe, expect, test } from "bun:test";
+import { projectDevinCliAuthMode } from "../../src/providers/devin-cli-authmode-migration";
+import { projectStartupConfigRepairs } from "../../src/providers/model-rename-startup";
+import type { OcxConfig } from "../../src/types";
+
+function cfg(row: Record<string, unknown> | undefined): OcxConfig {
+  return { providers: row ? { "devin-cli": row } : {} } as unknown as OcxConfig;
+}
+
+describe("devin-cli authMode migration", () => {
+  test("rewrites the seeded local authMode the registry no longer allows", () => {
+    // derive.ts seeds authMode from authKind, so every config saved while the
+    // provider was local carries "local", and auth-cors fails closed on it.
+    const p = projectDevinCliAuthMode(cfg({ adapter: "devin", baseUrl: "https://server.codeium.com", authMode: "local" }));
+    expect(p.changed).toBe(true);
+    expect(p.config.providers!["devin-cli"]!.authMode).toBe("oauth");
+    expect(p.warnings.join(" ")).toContain("local -> oauth");
+  });
+
+  test("leaves an already-migrated row alone", () => {
+    const p = projectDevinCliAuthMode(cfg({ adapter: "devin", baseUrl: "https://server.codeium.com", authMode: "oauth" }));
+    expect(p.changed).toBe(false);
+    expect(p.warnings).toEqual([]);
+  });
+
+  test("warns without mutating when the saved row still names the ACP adapter", () => {
+    // The saved adapter no longer chooses the transport — routing pins it from
+    // the registry — so an operator who chose ACP must be told, not silently moved.
+    const p = projectDevinCliAuthMode(cfg({ adapter: "devin-cli", baseUrl: "https://cli.devin.ai", authMode: "oauth" }));
+    expect(p.changed).toBe(false);
+    expect(p.config.providers!["devin-cli"]!.adapter).toBe("devin-cli");
+    expect(p.warnings.join(" ")).toContain("devin-acp");
+  });
+
+  test("is a no-op when the provider is not configured", () => {
+    const p = projectDevinCliAuthMode(cfg(undefined));
+    expect(p.changed).toBe(false);
+    expect(p.warnings).toEqual([]);
+  });
+
+  test("runs inside the shared startup repair pass", () => {
+    // One boot step owns persistence, adopt and failure handling for all three
+    // repairs; a second pass would have to reimplement them.
+    const p = projectStartupConfigRepairs(cfg({ adapter: "devin", baseUrl: "https://server.codeium.com", authMode: "local" }));
+    expect(p.changed).toBe(true);
+    expect(p.config.providers!["devin-cli"]!.authMode).toBe("oauth");
+  });
+});
+
diff --git a/tests/providers/devin-cli-login.test.ts b/tests/providers/devin-cli-login.test.ts
new file mode 100644
index 0000000000..ba82c033f1
--- /dev/null
+++ b/tests/providers/devin-cli-login.test.ts
@@ -0,0 +1,137 @@
+import { describe, expect, test } from "bun:test";
+import {
+  DEVIN_CLI_CREDENTIALS_ENV,
+  devinCliCredentialsPath,
+  devinCliSignedIn,
+  loginDevinCli,
+  readDevinCliCredentialFile,
+  refreshDevinCliToken,
+} from "../../src/oauth/devin-cli";
+import { resolveDevinApiServer } from "../../src/oauth/devin";
+import type { OAuthController } from "../../src/oauth/types";
+
+/**
+ * The measured shape of a signed-in CLI's credentials.toml. Quoted values, flat
+ * keys, LF. Fixtures use the real form on purpose: an unquoted matcher passes an
+ * unquoted fixture and then fails on the live file.
+ */
+const REAL_FILE = [
+  'windsurf_api_key = "devin-session-token$eyJhbGciOiJIUzI1NiJ9.eyJzZXNzaW9uX2lkIjoid2luZHN1cmYtc2Vzc2lvbi1hYmMifQ.sig"',
+  'api_server_url = "https://server.codeium.com"',
+  'devin_webapp_host = "https://app.devin.ai"',
+  'devin_api_url = "https://api.devin.ai"',
+  "",
+].join("\n");
+
+const KEY = 'devin-session-token$eyJhbGciOiJIUzI1NiJ9.eyJzZXNzaW9uX2lkIjoid2luZHN1cmYtc2Vzc2lvbi1hYmMifQ.sig';
+
+function depsFor(contents: string | undefined, env: NodeJS.ProcessEnv = {}) {
+  return {
+    env: { HOME: "/home/u", XDG_DATA_HOME: "/home/u/.local/share", ...env },
+    platform: "linux" as NodeJS.Platform,
+    exists: () => contents !== undefined,
+    read: () => contents ?? "",
+  };
+}
+
+function silentController(): OAuthController & { progress: string[] } {
+  const progress: string[] = [];
+  return { progress, onProgress: (m: string) => { progress.push(m); } };
+}
+
+describe("devin-cli credentials path", () => {
+  test("uses the data dir the CLI actually prints, not the config dir", () => {
+    expect(devinCliCredentialsPath({ XDG_DATA_HOME: "/d" }, "linux")).toBe("/d/devin/credentials.toml");
+  });
+
+  test("Windows uses APPDATA", () => {
+    expect(devinCliCredentialsPath({ APPDATA: "C:\\Users\\u\\AppData\\Roaming" }, "win32"))
+      .toBe("C:\\Users\\u\\AppData\\Roaming\\devin\\credentials.toml");
+  });
+
+  test("the override must be absolute", () => {
+    // A relative override would resolve against whatever directory the proxy
+    // happens to run in, which is not a location a user can mean.
+    const abs = devinCliCredentialsPath({ [DEVIN_CLI_CREDENTIALS_ENV]: "/tmp/creds.toml", XDG_DATA_HOME: "/d" }, "linux");
+    expect(abs).toBe("/tmp/creds.toml");
+    const rel = devinCliCredentialsPath({ [DEVIN_CLI_CREDENTIALS_ENV]: "creds.toml", XDG_DATA_HOME: "/d" }, "linux");
+    expect(rel).toBe("/d/devin/credentials.toml");
+  });
+});
+
+describe("devin-cli credential file", () => {
+  test("reads the two keys it needs and ignores the session-product ones", () => {
+    const file = readDevinCliCredentialFile(depsFor(REAL_FILE));
+    expect(file).toEqual({ apiKey: KEY, apiServerUrl: "https://server.codeium.com" });
+  });
+
+  test("absent file is undefined, not a throw", () => {
+    expect(readDevinCliCredentialFile(depsFor(undefined))).toBeUndefined();
+    expect(devinCliSignedIn(depsFor(undefined))).toBe(false);
+  });
+
+  test("either key missing is a refusal, not a half credential", () => {
+    expect(readDevinCliCredentialFile(depsFor('api_server_url = "https://server.codeium.com"\n'))).toBeUndefined();
+    expect(readDevinCliCredentialFile(depsFor(`windsurf_api_key = "${KEY}"\n`))).toBeUndefined();
+  });
+
+  test("an unquoted value is refused rather than guessed at", () => {
+    // The measured file quotes every value. Accepting an unquoted form would be
+    // inventing a parser for a shape the vendor does not write.
+    expect(readDevinCliCredentialFile(depsFor("windsurf_api_key = abc\napi_server_url = def\n"))).toBeUndefined();
+  });
+});
+
+describe("devin-cli login", () => {
+  test("imports the signed-in session without a browser", async () => {
+    const ctrl = silentController();
+    const cred = await loginDevinCli(ctrl, undefined, depsFor(REAL_FILE));
+    expect(cred.access).toBe(KEY);
+    // Durable-key pattern: refresh carries the key too, or detectOAuthWarning
+    // reports stale_credentials from the moment of login.
+    expect(cred.refresh).toBe(KEY);
+    expect(cred.expires).toBe(Number.MAX_SAFE_INTEGER);
+    expect(cred.source).toBe("local-cli");
+    expect(cred.apiBaseUrl).toBe("https://server.codeium.com");
+    // onAuth is never called: there is nothing for opencodex to authorize.
+    expect(ctrl.progress.join(" ")).not.toContain(KEY);
+  });
+
+  test("an off-allowlist api_server_url never becomes the request origin", async () => {
+    const hostile = REAL_FILE.replace("https://server.codeium.com", "https://evil.example.com");
+    const cred = await loginDevinCli(silentController(), undefined, depsFor(hostile));
+    expect(cred.apiBaseUrl).toBe("https://server.codeium.com");
+    expect(cred.apiBaseUrl).not.toContain("evil");
+  });
+
+  test("the failure names the install hint and never the secret", async () => {
+    // redactSecretString does not recognise a bare JWT or a devin-session-token,
+    // and login errors reach terminal output, so nothing parsed may be thrown.
+    const err = await loginDevinCli(silentController(), undefined, depsFor(undefined)).catch((e: Error) => e);
+    expect(err).toBeInstanceOf(Error);
+    expect((err as Error).message).toContain("devin auth login");
+    expect((err as Error).message).not.toContain(KEY);
+    const badErr = await loginDevinCli(silentController(), undefined, depsFor('windsurf_api_key = "' + KEY + '"\n'))
+      .catch((e: Error) => e);
+    expect((badErr as Error).message).not.toContain(KEY);
+  });
+
+  test("refresh is terminal", async () => {
+    await expect(refreshDevinCliToken("x")).rejects.toThrow(/invalid_grant/);
+  });
+});
+
+describe("devin tenant selection is provider-scoped", () => {
+  test("the default still reads the devin slot", () => {
+    // Every existing one-argument caller must keep its behaviour.
+    expect(resolveDevinApiServer("https://server.codeium.com")).toBe("https://server.codeium.com");
+    expect(resolveDevinApiServer(undefined)).toBe("https://server.codeium.com");
+  });
+
+  test("an unknown provider id falls back rather than borrowing another slot", () => {
+    // The regression this parameter exists for: reading a fixed "devin" slot sent
+    // one provider's key to the other provider's tenant.
+    expect(resolveDevinApiServer(undefined, "devin-cli")).toBe("https://server.codeium.com");
+  });
+});
+
diff --git a/tests/providers/devin-hardening.test.ts b/tests/providers/devin-hardening.test.ts
new file mode 100644
index 0000000000..07a5302ce7
--- /dev/null
+++ b/tests/providers/devin-hardening.test.ts
@@ -0,0 +1,249 @@
+import { describe, expect, test } from "bun:test";
+import { normalizeDevinModelId } from "../../src/adapters/devin";
+import { parseDevinAuthPaste, refreshDevinToken } from "../../src/oauth/devin";
+import { DEVIN_DEFAULT_API_SERVER, resolveDevinApiBaseUrl, validateDevinApiBaseUrl } from "../../src/oauth/devin/api-base";
+import { registerUser } from "../../src/oauth/devin/register-user";
+import { anySignal } from "../../src/lib/abort";
+import { buildGetChatMessageRequestForTests } from "../../src/adapters/devin/cloud-direct/chat";
+import { iterFields } from "../../src/adapters/devin/cloud-direct/wire";
+
+const FAKE_TOKEN = "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ1c2VyLTEifQ.c2lnbmF0dXJl";
+
+describe("devin api-server allowlist", () => {
+  test("accepts the default host and a tenant path, keeping the path", () => {
+    expect(validateDevinApiBaseUrl("https://server.codeium.com")).toBe("https://server.codeium.com");
+    expect(validateDevinApiBaseUrl("https://server.codeium.com/")).toBe("https://server.codeium.com");
+    // EU and FedStart tenants live under a path prefix, so normalizing to the
+    // origin the way the Copilot validator does would point them at the wrong
+    // service rather than merely losing decoration.
+    expect(validateDevinApiBaseUrl("https://eu.windsurf.com/_route/api_server")).toBe(
+      "https://eu.windsurf.com/_route/api_server",
+    );
+    expect(validateDevinApiBaseUrl("https://windsurf.fedstart.com/_route/api_server")).toBe(
+      "https://windsurf.fedstart.com/_route/api_server",
+    );
+  });
+
+  test("rejects every shape that would redirect a credential-bearing POST", () => {
+    for (const hostile of [
+      "http://server.codeium.com",
+      "https://attacker.example.com",
+      "https://server.codeium.com.attacker.example",
+      // Assembled rather than written out: a literal userinfo URL reads as an
+      // email address to the privacy scanner.
+      `https://user:secret${"@"}server.codeium.com`,
+      "https://server.codeium.com:8443",
+      "https://127.0.0.1",
+      "https://localhost",
+      "https://10.0.0.5",
+      "https://server.codeium.com/path?next=https://evil.example",
+      "https://server.codeium.com/path#frag",
+      "not a url",
+      "",
+    ]) {
+      expect(validateDevinApiBaseUrl(hostile)).toBeUndefined();
+    }
+    expect(resolveDevinApiBaseUrl("https://attacker.example.com")).toBe(DEVIN_DEFAULT_API_SERVER);
+  });
+});
+
+describe("devin auth paste", () => {
+  test("accepts a bare token and pulls one out of a callback URL", () => {
+    expect(parseDevinAuthPaste(` ${FAKE_TOKEN} `)).toBe(FAKE_TOKEN);
+    expect(parseDevinAuthPaste(`https://windsurf.com/callback#access_token=${FAKE_TOKEN}&state=abc`)).toBe(FAKE_TOKEN);
+    expect(parseDevinAuthPaste(`https://windsurf.com/cb?firebase_id_token=${FAKE_TOKEN}`)).toBe(FAKE_TOKEN);
+  });
+
+  test("accepts the one-time token shape a live sign-in actually returns", () => {
+    // Measured, not assumed: a free-tier sign-in on 2026-09-12 returned a
+    // 47-character `ott$…` value, and RegisterUser exchanged it successfully.
+    // A JWT-only check here would reject every real login.
+    const oneTime = "ott$lLA_RUkVq3nB7xYz0aQpMdT4sWgEhJcK-TjATkAk";
+    expect(parseDevinAuthPaste(oneTime)).toBe(oneTime);
+    expect(parseDevinAuthPaste(` ${oneTime}\n`)).toBe(oneTime);
+  });
+
+  test("refuses a paste with no token instead of posting it as the token", () => {
+    expect(() => parseDevinAuthPaste("https://windsurf.com/windsurf/signin?prompt=login")).toThrow(/no auth token/i);
+    expect(() => parseDevinAuthPaste("this is not a token")).toThrow(/not a Devin auth token/i);
+    expect(() => parseDevinAuthPaste("short")).toThrow(/not a Devin auth token/i);
+    expect(() => parseDevinAuthPaste("   ")).toThrow(/No auth token pasted/i);
+  });
+});
+
+describe("devin credential lifecycle", () => {
+  test("refresh fails closed rather than extending a possibly revoked key", async () => {
+    // The carried implementation returned an extended expiry, which made a
+    // revoked key look valid forever. Throwing is what marks needsReauth.
+    await expect(refreshDevinToken("whatever")).rejects.toThrow(/invalid_grant/);
+  });
+});
+
+describe("devin model ids", () => {
+  test("dotted version numbers collapse to the hyphenated catalog spelling", () => {
+    expect(normalizeDevinModelId("swe-1.6")).toBe("swe-1-6");
+    expect(normalizeDevinModelId("claude-opus-4.7-max")).toBe("claude-opus-4-7-max");
+    expect(normalizeDevinModelId("swe-1-7")).toBe("swe-1-7");
+  });
+});
+
+describe("registerUser error reporting", () => {
+  const withFetch = async (impl: typeof fetch, run: () => Promise<void>) => {
+    const original = globalThis.fetch;
+    globalThis.fetch = impl;
+    try {
+      await run();
+    } finally {
+      globalThis.fetch = original;
+    }
+  };
+  const region = {
+    website: "https://windsurf.com",
+    registerApiServerUrl: "https://register.windsurf.com",
+    oauthClientId: "test-client",
+  };
+
+  test("an error body that echoes the token never reaches the message", async () => {
+    await withFetch(
+      (async () =>
+        new Response(JSON.stringify({ code: "invalid_argument", message: `bad firebase_id_token ${FAKE_TOKEN}` }), {
+          status: 400,
+        })) as typeof fetch,
+      async () => {
+        const error = await registerUser(FAKE_TOKEN, region).catch((e: Error) => e);
+        expect(error).toBeInstanceOf(Error);
+        const message = (error as Error).message;
+        expect(message).not.toContain(FAKE_TOKEN);
+        expect(message).toContain("HTTP 400");
+        expect(message).toContain("invalid_argument");
+      },
+    );
+  });
+
+  test("a 200 with an unparseable body reports its size, not its contents", async () => {
+    await withFetch(
+      (async () => new Response(`<html>${FAKE_TOKEN}</html>`, { status: 200 })) as typeof fetch,
+      async () => {
+        const error = await registerUser(FAKE_TOKEN, region).catch((e: Error) => e);
+        expect((error as Error).message).not.toContain(FAKE_TOKEN);
+        expect((error as Error).message).toMatch(/not JSON/i);
+      },
+    );
+  });
+
+  test("a register host outside the allowlist is refused before the token is sent", async () => {
+    let called = false;
+    await withFetch(
+      (async () => {
+        called = true;
+        return new Response("{}", { status: 200 });
+      }) as typeof fetch,
+      async () => {
+        const error = await registerUser(FAKE_TOKEN, { ...region, registerApiServerUrl: "https://evil.example" }).catch(
+          (e: Error) => e,
+        );
+        expect((error as Error).message).toMatch(/non-Cognition register host/i);
+        expect(called).toBe(false);
+      },
+    );
+  });
+});
+
+describe("anySignal", () => {
+  test("cleanup detaches from a parent signal that never aborts", () => {
+    const parent = new AbortController();
+    let added = 0;
+    let removed = 0;
+    const realAdd = parent.signal.addEventListener.bind(parent.signal);
+    const realRemove = parent.signal.removeEventListener.bind(parent.signal);
+    // Exercise the polyfill branch explicitly: on Bun the builtin
+    // AbortSignal.any is used and owns its own teardown.
+    const builtin = (AbortSignal as unknown as { any?: unknown }).any;
+    (AbortSignal as unknown as { any?: unknown }).any = undefined;
+    parent.signal.addEventListener = ((...args: Parameters<typeof realAdd>) => {
+      added += 1;
+      return realAdd(...args);
+    }) as typeof realAdd;
+    parent.signal.removeEventListener = ((...args: Parameters<typeof realRemove>) => {
+      removed += 1;
+      return realRemove(...args);
+    }) as typeof realRemove;
+    try {
+      const composed = anySignal([parent.signal, AbortSignal.timeout(60_000)]);
+      expect(composed.signal.aborted).toBe(false);
+      composed.cleanup();
+      expect(added).toBe(1);
+      expect(removed).toBe(1);
+    } finally {
+      (AbortSignal as unknown as { any?: unknown }).any = builtin;
+    }
+  });
+
+  test("aborts as soon as any input aborts", () => {
+    const a = new AbortController();
+    const b = new AbortController();
+    const composed = anySignal([a.signal, b.signal]);
+    expect(composed.signal.aborted).toBe(false);
+    b.abort(new Error("stop"));
+    expect(composed.signal.aborted).toBe(true);
+    composed.cleanup();
+  });
+});
+
+describe("devin cloud request shape", () => {
+  // The bug this guards: #2 and #3 were swapped, so a caller asking for 32
+  // output tokens wrote 32 into the context-window field and Cognition answered
+  // every single turn with an opaque "an internal error occurred" - on free and
+  // paid accounts alike. Verified on 2026-09-12 by building the same turn with a
+  // working client and diffing the encoded messages field by field.
+  function fields(buf: Buffer) {
+    const out: Record<number, { wire: number; value: unknown }> = {};
+    for (const f of iterFields(buf)) out[f.num] = { wire: f.wire, value: f.value };
+    return out;
+  }
+  const build = (completionOpts?: Record<string, number>) =>
+    buildGetChatMessageRequestForTests({
+      apiKey: "devin-session-token$test",
+      sessionId: "11111111-1111-1111-1111-111111111111",
+      requestId: 1n,
+      triggerId: "22222222-2222-2222-2222-222222222222",
+      cascadeId: "33333333-3333-3333-3333-333333333333",
+      modelUid: "swe-2-high",
+      messages: [{ role: "user", content: "hi" }],
+      ...(completionOpts ? { completionOpts } : {}),
+    });
+
+  test("the output cap lands in #2 and the context window in #3", () => {
+    const outer = fields(build({ maxOutputTokens: 64, maxInputTokens: 200_000 }));
+    const completion = outer[8]?.value as Buffer;
+    const inner = fields(completion);
+    expect(inner[2]).toEqual({ wire: 0, value: 64n });
+    expect(inner[3]).toEqual({ wire: 0, value: 200_000n });
+    // #6 and #11 are not part of the message the service accepts.
+    expect(inner[6]).toBeUndefined();
+    expect(inner[11]).toBeUndefined();
+  });
+
+  test("temperature zero is clamped, because the service refuses exactly zero", () => {
+    const inner = fields(fields(build({ temperature: 0 }))[8]?.value as Buffer);
+    const raw = inner[5]?.value as Buffer;
+    const temperature = Buffer.from(raw).readDoubleLE(0);
+    expect(temperature).toBeGreaterThan(0);
+    expect(temperature).toBeLessThan(0.01);
+  });
+
+  test("the outer request carries the verified tag set", () => {
+    const outer = fields(build());
+    // Present: metadata, system prompt, one prompt, request type, completion
+    // config, session model config, session id, the #20 marker and the model.
+    for (const tag of [1, 2, 3, 7, 8, 15, 16, 20, 21]) expect(outer[tag], `#${tag}`).toBeDefined();
+    // #22 only appears from the second turn onward and is reused across that
+    // turn's tool loop, so a fresh per-request uuid matches neither shape.
+    expect(outer[22]).toBeUndefined();
+  });
+
+  test("metadata carries the fingerprint the service checks the length of", () => {
+    const metadata = fields(fields(build())[1]?.value as Buffer);
+    expect((metadata[31]?.value as Buffer).length).toBe(732);
+  });
+});
diff --git a/tests/providers/digitalocean-scaleway-provider.test.ts b/tests/providers/digitalocean-scaleway-provider.test.ts
index 34464c65aa..edee14a87c 100644
--- a/tests/providers/digitalocean-scaleway-provider.test.ts
+++ b/tests/providers/digitalocean-scaleway-provider.test.ts
@@ -111,7 +111,7 @@ describe("DigitalOcean and Scaleway providers", () => {
     // the id to both the DigitalOcean and Scaleway lists and moved neither length
     // assertion; Scaleway's happened to still match, so only this one went red - and it
     // stayed red on dev, which is how a broken shard reached the branch that noticed it.
-    expect(digitaloceanModels).toHaveLength(28);
+    expect(digitaloceanModels).toHaveLength(27);
     expect(digitaloceanModels).toContain("glm-5.3-flash");
     expect(digitaloceanModels).toContain("openai-gpt-5.6-sol");
     expect(digitaloceanModels).toContain("meta-llama/Meta-Llama-3.1-8B-Instruct");
@@ -264,12 +264,11 @@ describe("DigitalOcean and Scaleway providers", () => {
     const scalewayModels = models.filter(row => row.provider === "scaleway");
 
     expect(digitaloceanModels.map(row => row.id)).toEqual([
-      "deepseek-v4-pro",
       "meta-llama/Meta-Llama-3.1-8B-Instruct",
       "openai-gpt-5.6-sol",
     ]);
     expect(digitaloceanModels[1]).toMatchObject({
-      owned_by: "digitalocean",
+      owned_by: "openai",
       reasoningEfforts: [],
     });
     expect(scalewayModels.map(row => row.id)).toEqual([
diff --git a/tests/providers/opencode-cli.test.ts b/tests/providers/opencode-cli.test.ts
index 4483e5ea99..bf3552d8c0 100644
--- a/tests/providers/opencode-cli.test.ts
+++ b/tests/providers/opencode-cli.test.ts
@@ -127,9 +127,9 @@ describe("ocx opencode provider block", () => {
   });
 
   test("native slugs pick up authoritative context windows from the resolver", () => {
-    const block = buildOpencodeProviderBlock(10100, ["gpt-5.4", "unknown-native"], [], slug =>
-      slug === "gpt-5.4" ? 1_000_000 : undefined);
-    expect(block.models["gpt-5.4"]?.limit).toEqual({ context: 1_000_000, output: SCHEMA_REQUIRED_OUTPUT_BUDGET });
+    const block = buildOpencodeProviderBlock(10100, ["gpt-5.6-luna", "unknown-native"], [], slug =>
+      slug === "gpt-5.6-luna" ? 1_000_000 : undefined);
+    expect(block.models["gpt-5.6-luna"]?.limit).toEqual({ context: 1_000_000, output: SCHEMA_REQUIRED_OUTPUT_BUDGET });
     expect(block.models["unknown-native"]?.limit).toBeUndefined();
   });
 
@@ -421,6 +421,38 @@ describe("ocx opencode proxy model catalog", () => {
     expect(Object.keys(blocks.v1.models)).not.toContain("opencode-go/hidden");
   });
 
+  test("carries /api/models modalities into the blocks the launcher injects", () => {
+    // Same failure mode as the ladder above, one field over: the management API reports
+    // image input for these rows and opencode gates attachments client-side, so dropping the
+    // field here leaves the image blocked before any request reaches the proxy (#4286).
+    const rows = [
+      { namespaced: "gpt-5.6-luna", native: true, provider: "openai", id: "gpt-5.6-luna", inputModalities: ["text", "image"] },
+      { namespaced: "opencode-go/glm-5.3", provider: "opencode-go", id: "glm-5.3", inputModalities: ["text", "image"] },
+      { namespaced: "opencode-go/text-only", provider: "opencode-go", id: "text-only", inputModalities: ["text"] },
+      { namespaced: "opencode-go/undeclared", provider: "opencode-go", id: "undeclared" },
+      { namespaced: "opencode-go/hidden", provider: "opencode-go", id: "hidden", disabled: true, inputModalities: ["text", "image"] },
+    ];
+    const catalog = opencodeCatalogFromProxyRows(rows, cfg());
+    const blocks = buildOpencodeProviderBlocksFromCatalog(10100, catalog, undefined, cfg());
+
+    for (const block of [blocks.v1, blocks.v2]) {
+      expect(block.models["gpt-5.6-luna"]).toMatchObject({
+        attachment: true, modalities: { input: ["text", "image"], output: ["text"] },
+      });
+      expect(block.models["opencode-go/glm-5.3"]).toMatchObject({
+        attachment: true, modalities: { input: ["text", "image"], output: ["text"] },
+      });
+      expect(block.models["opencode-go/text-only"]).toMatchObject({
+        attachment: false, modalities: { input: ["text"], output: ["text"] },
+      });
+      // A row that declares nothing keeps the exact entry shape opencode already reads as
+      // text-only — the pre-#4286 bytes, not a synthesized capability list.
+      expect(block.models["opencode-go/undeclared"]).not.toHaveProperty("attachment");
+      expect(block.models["opencode-go/undeclared"]).not.toHaveProperty("modalities");
+      expect(Object.keys(block.models)).not.toContain("opencode-go/hidden");
+    }
+  });
+
   test("the launcher's V1 and V2 blocks share one connection", () => {
     const blocks = buildOpencodeProviderBlocksFromCatalog(
       10100,
diff --git a/tests/providers/opencode-go-deepseek.test.ts b/tests/providers/opencode-go-deepseek.test.ts
index edf42a4815..eead3f2c32 100644
--- a/tests/providers/opencode-go-deepseek.test.ts
+++ b/tests/providers/opencode-go-deepseek.test.ts
@@ -54,7 +54,7 @@ function buildToolCallBody(modelId: string, reasoning: string): {
 
 describe("opencode-go DeepSeek V4 thinking mode", () => {
   test("normalizes Desktop-style root composition schemas for Console Go", () => {
-    const route = routeModel(configFor("deepseek-v4-pro"), "opencode-go/deepseek-v4-pro");
+    const route = routeModel(configFor("deepseek-v4.1-flash"), "opencode-go/deepseek-v4.1-flash");
     const req = createOpenAIChatAdapter(route.provider).buildRequest({
       modelId: route.modelId,
       context: {
@@ -99,7 +99,7 @@ describe("opencode-go DeepSeek V4 thinking mode", () => {
     });
   });
 
-  test.each(["deepseek-v4-flash", "deepseek-v4-pro"])(
+  test.each(["deepseek-v4-flash", "deepseek-v4.1-flash"])(
     "%s replays tool-call reasoning and maps Codex efforts",
     modelId => {
       const xhighBody = buildToolCallBody(modelId, "xhigh");
@@ -130,3 +130,60 @@ describe("opencode-go DeepSeek V4 thinking mode", () => {
     expect(body.messages[1]).toHaveProperty("tool_calls");
   });
 });
+
+/*
+ * Issues #1338 / #1415: the Zen Go upstream answers a `json_schema` response_format with
+ * HTTP 400 "This response_format type is unavailable now" on its DeepSeek routes, which
+ * kills every Codex auto-review turn there. The preset now carries that fact, so the
+ * request is downgraded to `json_object` instead of the operator having to disable
+ * structured output by hand.
+ */
+describe("opencode-go DeepSeek json_schema downgrade", () => {
+  const buildWith = (modelId: string, extra: Record<string, unknown> = {}) => {
+    const config = configFor(modelId);
+    Object.assign(config.providers["opencode-go"], extra);
+    const route = routeModel(config, `opencode-go/${modelId}`);
+    const req = createOpenAIChatAdapter(route.provider).buildRequest({
+      modelId: route.modelId,
+      context: { messages: [{ role: "user", content: "hi", timestamp: 0 }] },
+      options: { textFormat: { type: "json_schema", name: "review", schema: { type: "object" }, strict: true } },
+      stream: false,
+    });
+    return {
+      provider: route.provider,
+      body: JSON.parse(req.body as string) as { response_format?: { type?: string } },
+    };
+  };
+
+  test("the preset reaches the routed provider", () => {
+    expect(buildWith("deepseek-v4-flash").provider.noJsonSchemaModels)
+      .toEqual(["deepseek-v4.1-flash", "deepseek-v4-flash"]);
+  });
+
+  test("a listed DeepSeek route is downgraded to json_object", () => {
+    expect(buildWith("deepseek-v4-flash").body.response_format).toEqual({ type: "json_object" });
+    expect(buildWith("deepseek-v4.1-flash").body.response_format).toEqual({ type: "json_object" });
+  });
+
+  test("an unlisted sibling on the same gateway keeps its schema", () => {
+    expect(buildWith("glm-5.3").body.response_format?.type).toBe("json_schema");
+  });
+
+  test("the operator kill switch still wins over the downgrade", () => {
+    const { body } = buildWith("deepseek-v4-flash", { noStructuredOutputModels: ["deepseek-v4-flash"] });
+    expect(body.response_format).toBeUndefined();
+  });
+
+  test("a json_object request is left alone on a listed route", () => {
+    const config = configFor("deepseek-v4-flash");
+    const route = routeModel(config, "opencode-go/deepseek-v4-flash");
+    const req = createOpenAIChatAdapter(route.provider).buildRequest({
+      modelId: route.modelId,
+      context: { messages: [{ role: "user", content: "hi", timestamp: 0 }] },
+      options: { textFormat: { type: "json_object" } },
+      stream: false,
+    });
+    expect((JSON.parse(req.body as string) as { response_format?: unknown }).response_format)
+      .toEqual({ type: "json_object" });
+  });
+});
diff --git a/tests/providers/opencode-go-session-header.test.ts b/tests/providers/opencode-go-session-header.test.ts
index 9b326e294c..be63d32d9d 100644
--- a/tests/providers/opencode-go-session-header.test.ts
+++ b/tests/providers/opencode-go-session-header.test.ts
@@ -1,4 +1,5 @@
-import { afterEach, describe, expect, test } from "bun:test";
+import { afterEach, describe, expect, spyOn, test } from "bun:test";
+import { clearComboSelectionState, clearComboTargetCooldowns } from "../../src/combos";
 import { providerConfigSeed } from "../../src/providers/derive";
 import { resolveOpenCodeGoTransport } from "../../src/providers/opencode-go-transport";
 import { getProviderRegistryEntry } from "../../src/providers/registry";
@@ -122,6 +123,127 @@ describe("OpenCode Go session affinity (#3344)", () => {
   const originalFetch = globalThis.fetch;
   afterEach(() => { globalThis.fetch = originalFetch; });
 
+  for (const model of [CHAT_MODEL, MUSE_MODEL]) {
+    for (const preliminaryAdapter of ["openai-chat", "openai-responses"] as const) {
+    for (const strategy of ["random", "failover"] as const) {
+      for (const identity of [
+        { name: "metadata", headers: {}, metadata: "user_test_account__session_conversation-a", expected: "ocx_a89540229ef781fd5f7adf92a711b436" },
+        { name: "explicit Go header", headers: { [SESSION_HEADER]: "client-session-a" }, metadata: "other-session", expected: "ocx_516d593899f34b7baca2db37c7b0c8c5" },
+        { name: "explicit lane", headers: { session_id: "native-client-session", [SESSION_HEADER]: "client-session-a" }, metadata: "other-session", expected: "ocx_a197dbb87311c29a5fbe51140e3845ce" },
+        { name: "operator override", headers: {}, metadata: "user_test_account__session_conversation-a", operator: true, expected: "operator-session" },
+        { name: "invalid explicit lane", headers: { session_id: "invalid\tidentity", [SESSION_HEADER]: "invalid\tidentity" }, metadata: "user_test_account__session_conversation-a", expected: "ocx_a89540229ef781fd5f7adf92a711b436" },
+        { name: "invalid metadata", headers: {}, metadata: "invalid\u0000identity", expected: "isolated" },
+        { name: "shared system only", headers: {}, metadata: undefined, expected: "isolated" },
+      ]) {
+      test(`Claude ${strategy} ${preliminaryAdapter} to Go uses ${identity.name} on ${model}`, async () => {
+        // Without valid identity the final Go destination still receives a
+        // request-scoped lane (#4172): well-formed, never the shared-system or
+        // metadata-derived value, and distinct across independent requests.
+        const observed: string[] = [];
+        for (const round of [1, 2]) {
+        clearComboSelectionState();
+        clearComboTargetCooldowns();
+        const requests: Array<{ url: string; headers: Headers }> = [];
+        globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+          const url = String(input);
+          requests.push({ url, headers: new Headers(init?.headers) });
+          if (url.startsWith("https://other.example")) {
+            return Response.json({ error: { message: "model retired", code: "model_not_found" } }, { status: 404 });
+          }
+          return upstreamResponse(url, true);
+        }) as typeof fetch;
+        const config = {
+          providers: {
+            other: { adapter: preliminaryAdapter, authMode: "key", baseUrl: "https://other.example/v1", apiKey: "test-key", models: ["other"] },
+            "renamed-go": opencodeGo(identity.operator ? { headers: { "X-OpenCode-Session": "operator-session" } } : {}),
+          },
+          combos: { affinity: { strategy, targets: [
+            { provider: "other", model: "other" }, { provider: "renamed-go", model },
+          ] } },
+        } as unknown as OcxConfig;
+        const entropy = spyOn(Math, "random").mockReturnValue(0.9);
+        // Preliminary route checks the first target; dispatch independently picks Go.
+        entropy.mockReturnValueOnce(0);
+        try {
+          const response = await handleClaudeMessages(new Request("http://localhost/v1/messages", {
+            method: "POST", headers: { "content-type": "application/json", ...identity.headers } as Record<string, string>,
+            body: JSON.stringify({ model: "combo/affinity", max_tokens: 64, stream: false,
+              messages: [{ role: "user", content: "ping" }],
+              system: "Shared system prompt is not a session.",
+              metadata: { user_id: identity.metadata } }),
+          }), config, { model: "", provider: "" });
+          await response.text();
+          expect(response.status).toBe(200);
+          expect(requests.at(-1)?.url).toStartWith("https://opencode.ai/zen/go/v1/");
+          const lane = requests.at(-1)?.headers.get(SESSION_HEADER);
+          if (identity.expected === "isolated") {
+            expect(lane).toMatch(/^ocx_[0-9a-f]{32}$/);
+            expect(lane).not.toBe("ocx_a89540229ef781fd5f7adf92a711b436");
+            observed.push(lane!);
+          } else {
+            expect(lane).toBe(identity.expected);
+          }
+          if (strategy === "failover") {
+            expect(requests).toHaveLength(2);
+            expect(requests[0]?.headers.has(SESSION_HEADER)).toBe(false);
+          } else {
+            expect(requests).toHaveLength(1);
+          }
+        } finally {
+          entropy.mockRestore();
+          clearComboSelectionState();
+          clearComboTargetCooldowns();
+        }
+        if (identity.expected !== "isolated" && round === 1) break;
+        }
+        if (identity.expected === "isolated") {
+          expect(observed).toHaveLength(2);
+          expect(observed[0]).not.toBe(observed[1]);
+        }
+      });
+      }
+    }
+    }
+
+    test(`Claude random Go preflight does not leak affinity to a final non-Go Responses target (${model})`, async () => {
+      clearComboSelectionState();
+      clearComboTargetCooldowns();
+      const requests: Headers[] = [];
+      globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+        expect(String(input)).toBe("https://other.example/v1/responses");
+        requests.push(new Headers(init?.headers));
+        return upstreamResponse(String(input));
+      }) as typeof fetch;
+      const config = {
+        providers: {
+          other: { adapter: "openai-responses", authMode: "key", baseUrl: "https://other.example/v1", apiKey: "test-key", models: ["other"] },
+          "renamed-go": opencodeGo(),
+        },
+        combos: { affinity: { strategy: "random", targets: [
+          { provider: "renamed-go", model }, { provider: "other", model: "other" },
+        ] } },
+      } as unknown as OcxConfig;
+      const entropy = spyOn(Math, "random").mockReturnValue(0.9).mockReturnValueOnce(0);
+      try {
+        const response = await handleClaudeMessages(new Request("http://localhost/v1/messages", {
+          method: "POST", headers: { "content-type": "application/json", [SESSION_HEADER]: "client-session-a" },
+          body: JSON.stringify({ model: "combo/affinity", max_tokens: 64, stream: false,
+            messages: [{ role: "user", content: "ping" }],
+            metadata: { user_id: "user_test_account__session_conversation-a" } }),
+        }), config, { model: "", provider: "" });
+        await response.text();
+        expect(response.status).toBe(200);
+        expect(requests).toHaveLength(1);
+        expect(requests[0]?.has(SESSION_HEADER)).toBe(false);
+        expect(requests[0]?.has("session_id")).toBe(false);
+      } finally {
+        entropy.mockRestore();
+        clearComboSelectionState();
+        clearComboTargetCooldowns();
+      }
+    });
+  }
+
   test("Claude metadata gives stable Go affinity across turns and distinct conversations", async () => {
     const input = { claude: true, model: CHAT_MODEL, metadataUserId: "user_test_account__session_conversation-a" };
     const first = await captureRequest(input);
diff --git a/tests/providers/opencode-zen-deepseek-reasoning.test.ts b/tests/providers/opencode-zen-deepseek-reasoning.test.ts
index 5074a510f1..9bfc0ac369 100644
--- a/tests/providers/opencode-zen-deepseek-reasoning.test.ts
+++ b/tests/providers/opencode-zen-deepseek-reasoning.test.ts
@@ -53,7 +53,7 @@ function buildToolCallBody(modelId: string, reasoning?: string): {
 }
 
 describe("opencode-zen DeepSeek thinking mode", () => {
-  test.each(["deepseek-v4-flash-free", "deepseek-v4-flash", "deepseek-v4-pro"])(
+  test.each(["deepseek-v4-flash-free", "deepseek-v4-flash", "deepseek-v4.1-flash"])(
     "%s replays tool-call reasoning_content and maps Codex efforts (issue #950/#994)",
     modelId => {
       const body = buildToolCallBody(modelId, "xhigh");
@@ -81,7 +81,7 @@ describe("opencode-zen DeepSeek thinking mode", () => {
     expect(body.messages[1]).toHaveProperty("tool_calls");
   });
 
-  test.each(["deepseek-v4-flash-free", "deepseek-v4-flash", "deepseek-v4-pro"])(
+  test.each(["deepseek-v4-flash-free", "deepseek-v4-flash", "deepseek-v4.1-flash"])(
     "%s is listed in opencode-zen noVisionModels for the vision sidecar",
     modelId => {
       const route = routeModel(configFor(modelId), `opencode-zen/${modelId}`);
diff --git a/tests/providers/orcarouter-provider.test.ts b/tests/providers/orcarouter-provider.test.ts
index 2b8cb02a54..a45ffde24a 100644
--- a/tests/providers/orcarouter-provider.test.ts
+++ b/tests/providers/orcarouter-provider.test.ts
@@ -136,7 +136,7 @@ describe("OrcaRouter dual authentication", () => {
       expect(entry.models).toContain("orcarouter/auto");
       expect(entry.modelReasoningEfforts?.["openai/gpt-5.5"])
         .toEqual(["low", "medium", "high", "xhigh"]);
-      expect(entry.modelReasoningEfforts?.["deepseek/deepseek-v4-pro"]).toBeArray();
+      expect(entry.modelReasoningEfforts?.["openai/gpt-5.5"]).toBeArray();
     }
     expect(KEY_LOGIN_PROVIDERS.orcarouter).toBeDefined();
     expect(OAUTH_PROVIDERS["orcarouter-oauth"]).toBeDefined();
diff --git a/tests/providers/provider-config-batch-management.test.ts b/tests/providers/provider-config-batch-management.test.ts
index c0646c98f9..8c594fd8c3 100644
--- a/tests/providers/provider-config-batch-management.test.ts
+++ b/tests/providers/provider-config-batch-management.test.ts
@@ -9,6 +9,8 @@ import { safeConfigDTO } from "../../src/server/auth-cors";
 import { handleManagementAPI } from "../../src/server/management-api";
 import type { OcxConfig } from "../../src/types";
 import { catalogConvergenceFactory } from "../helpers/catalog-convergence";
+import { clearKeyCooldowns, forgetApiKeyRotationCursor, rotateKeyOn429, selectProactiveApiKey } from "../../src/providers/key-failover";
+import { setActiveProviderApiKey } from "../../src/providers/api-keys";
 import { installIsolatedCodexHome, type IsolatedCodexHome } from "../helpers/isolated-codex-home";
 import { ManagementRequest as Request } from "../helpers/management-auth";
 import { removeTreeWithRetry } from "../helpers/remove-tree";
@@ -360,4 +362,61 @@ describe("atomic provider editor batch", () => {
       error: "Full config PUT is disabled. Use /api/providers POST for provider changes.",
     });
   });
+
+  /**
+   * The batch PUT rewrites the whole roster, which is why it already clears every key cooldown
+   * without naming a provider. The rotation cursor is the other half of that state and was
+   * being left behind, so round-robin resumed after the pre-edit position instead of at the
+   * head of the roster the operator had just saved.
+   *
+   * Red control: drop `forgetApiKeyRotationCursor()` from the PUT success path and the pick
+   * below returns `sk-alpha-three`, continuing after the stale cursor instead of taking the
+   * first eligible key.
+   */
+  test("a batch PUT forgets the rotation cursor along with the cooldowns", async () => {
+    const liveConfig = seededConfig();
+    liveConfig.providers.alpha!.apiKeyPoolStrategy = "round-robin";
+    liveConfig.providers.alpha!.apiKeyPool = [
+      { id: "one", key: "sk-alpha-one" },
+      { id: "two", key: "sk-alpha-two" },
+      { id: "three", key: "sk-alpha-three" },
+    ];
+    liveConfig.providers.alpha!.apiKey = "sk-alpha-one";
+    saveConfig(liveConfig);
+    clearKeyCooldowns();
+    forgetApiKeyRotationCursor();
+
+    // Establish a cursor the honest way: cool the committed key, point the stored selection
+    // back at it -- which is the state a restart or a config reload leaves -- and let the pool
+    // advance. Cooling alone is not enough, because rotateKeyOn429 already commits the next
+    // key and the picker refuses to second-guess a healthy committed one.
+    const t0 = Date.now();
+    rotateKeyOn429(loadConfig(), "alpha", null, t0, "sk-alpha-one");
+    setActiveProviderApiKey(loadConfig(), "alpha", "one");
+    const first = selectProactiveApiKey(loadConfig(), "alpha", t0);
+    expect(first?.apiKey).toBe("sk-alpha-two");
+
+    const baseline = editorBaseline(loadConfig());
+    // apiKeyPoolStrategy is a public editor field, so it has to appear in the baseline or the
+    // deep-equal staleness check rejects the PUT.
+    baseline.providers.alpha!.apiKeyPoolStrategy = "round-robin";
+    const next = structuredClone(baseline);
+    next.providers.alpha!.defaultModel = "alpha-new";
+    // Same seam the other successful-PUT cases use: the destination check would otherwise do a
+    // real DNS lookup for alpha.example.test on the commit path.
+    const destinationSpy = spyOn(destinationPolicy, "providerDestinationResolvedError").mockResolvedValue(null);
+    try {
+      const response = await putBatch(loadConfig(), { baseline, next });
+      expect(response?.status).toBe(200);
+    } finally {
+      destinationSpy.mockRestore();
+    }
+
+    // The PUT cleared the cooldowns, so key one is eligible again. Cool only the committed key
+    // and point the selection back at it, the same way as above.
+    rotateKeyOn429(loadConfig(), "alpha", null, t0, "sk-alpha-two");
+    setActiveProviderApiKey(loadConfig(), "alpha", "two");
+    const second = selectProactiveApiKey(loadConfig(), "alpha", t0);
+    expect(second?.apiKey).toBe("sk-alpha-one");
+  });
 });
diff --git a/tests/providers/provider-model-discovery-contract.test.ts b/tests/providers/provider-model-discovery-contract.test.ts
index 4687594379..89cfef37b7 100644
--- a/tests/providers/provider-model-discovery-contract.test.ts
+++ b/tests/providers/provider-model-discovery-contract.test.ts
@@ -641,6 +641,47 @@ describe("registry-owned provider model discovery", () => {
     }
   });
 
+  // #4261: Antigravity is the one live-discovery row that never declared its own
+  // discovery spec, so the loop above did not cover it and the proof returned
+  // false for Antigravity's OWN canonical URL. Under a Clash/Surge/Mihomo TUN the
+  // benchmark fake-IP answer was then rejected and the model list came back empty.
+  // Pin all three halves: the declared spec is valid, the URL the adapter already
+  // sends is unchanged, and a custom base still fails the proof.
+  test("google-antigravity proves its own canonical CCA discovery RPC (#4261)", () => {
+    const entry = PROVIDER_REGISTRY.find(row => row.id === "google-antigravity");
+    if (!entry?.modelDiscovery) throw new Error("google-antigravity must declare modelDiscovery");
+    expect(providerModelDiscoverySpecError(entry.modelDiscovery)).toBeNull();
+
+    const seed = providerConfigSeed(entry);
+    const canonical = "https://daily-cloudcode-pa.googleapis.com/v1internal:fetchAvailableModels";
+    expect(resolveProviderModelDiscoveryUrl(entry.id, seed, entry.baseUrl, canonical)).toBe(canonical);
+    expect(isRegistryModelDiscoveryUrl(entry.id, canonical)).toBe(true);
+    // Declaring the spec must not move the request the adapter already made.
+    expect(buildModelsRequest(seed, "agy-access-token", entry.id)).toMatchObject({
+      method: "POST",
+      url: canonical,
+    });
+
+    // allowBaseUrlOverride is set on this row, so a custom base must stay custom
+    // and must NOT inherit the fake-IP exception.
+    const custom = resolveProviderModelDiscoveryUrl(
+      entry.id,
+      { ...seed, baseUrl: "https://custom.example/proxy" },
+      "https://custom.example/proxy",
+      "https://custom.example/proxy/v1internal:fetchAvailableModels",
+    );
+    expect(custom).toBe("https://custom.example/proxy/v1internal:fetchAvailableModels");
+    expect(isRegistryModelDiscoveryUrl(entry.id, custom)).toBe(false);
+
+    for (const url of [
+      "https://evil.example/v1internal:fetchAvailableModels",
+      `${canonical}?token=1`,
+      `${canonical}#frag`,
+      canonical.replace("https:", "http:"),
+      "https://daily-cloudcode-pa.googleapis.com/v1internal:other",
+    ]) expect(isRegistryModelDiscoveryUrl(entry.id, url)).toBe(false);
+  });
+
   // The resolver accepts an effective (possibly custom) baseUrl while the proof
   // must stay registry-owned: a custom destination that merely resembles the
   // registry shape must NOT gain the benchmark-address exception. Nebius opts
diff --git a/tests/providers/provider-quota.test.ts b/tests/providers/provider-quota.test.ts
index a8d4bef728..788c0dff11 100644
--- a/tests/providers/provider-quota.test.ts
+++ b/tests/providers/provider-quota.test.ts
@@ -18,10 +18,14 @@ import {
   parseXaiCreditsResponse,
   QUOTA_RESPONSE_MAX_BYTES,
   readProviderQuotaJsonForTests,
+  publishKeyReportForTests,
   setAntigravityAccountQuotaTransportForTests,
   setProviderQuotaBeforePublishForTests,
 } from "../../src/providers/quota";
 import type { OcxConfig } from "../../src/types";
+import { clearComboTargetCooldowns, coolComboTarget, pickComboTarget, pickComboTargetWithWait } from "../../src/combos";
+import { routedProviderConfig } from "../../src/router";
+import { buildOpenAIChatPassthroughRequest } from "../../src/adapters/openai-chat";
 import { PROXY_ENV_KEYS } from "../../src/lib/proxy-env";
 import { repoPath } from "../helpers/repo-root";
 const proxyKeys = PROXY_ENV_KEYS.flatMap(key => [key, key.toLowerCase()]);
@@ -95,6 +99,7 @@ beforeEach(() => {
 });
 
 afterEach(() => {
+  clearComboTargetCooldowns();
   for (const key of proxyKeys) {
     if (originalProxyEnv[key] === undefined) delete process.env[key];
     else process.env[key] = originalProxyEnv[key];
@@ -703,6 +708,241 @@ describe("fetchProviderQuotaReports", () => {
     } as OcxConfig;
   }
 
+  function quotaCombo(config: OcxConfig): OcxConfig {
+    const provider = config.defaultProvider;
+    return {
+      ...config,
+      providers: {
+        ...config.providers,
+        fallback: { adapter: "openai-chat", baseUrl: "https://fallback.example/v1", apiKey: "fallback-key" },
+      },
+      combos: { "quota-scope": { strategy: "failover", targets: [
+        { provider, model: "primary-model" }, { provider: "fallback", model: "fallback-model" },
+      ] } },
+    };
+  }
+
+  test("routing quota scope keeps Synthetic search exhaustion out of model selection", async () => {
+    globalThis.fetch = (async () => Response.json({
+      data: { rollingFiveHourLimit: 20, weeklyTokenLimit: 30, search: { hourly: 100 } },
+    })) as typeof fetch;
+    const config = quotaCombo(keyQuotaConfig("synthetic", "https://api.synthetic.new/v2"));
+    const reports = await fetchProviderQuotaReports(config, true);
+    expect(reports.reports[0]?.quota.customWindows?.[0]?.percent).toBe(100);
+    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("synthetic");
+  });
+
+  test("routing quota scope keeps ZAI legacy MCP exhaustion out of model selection", async () => {
+    globalThis.fetch = (async () => Response.json({
+      success: true, data: { fiveHourPercent: 20, weeklyPercent: 30, monthlyMCPUsage: 100 },
+    })) as typeof fetch;
+    const config = quotaCombo(keyQuotaConfig("zai", "https://api.z.ai/api/coding/paas/v4"));
+    const reports = await fetchProviderQuotaReports(config, true);
+    expect(reports.reports[0]?.quota.monthlyPercent).toBe(100);
+    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("zai");
+  });
+
+  test("routing quota scope keeps a key-bound display-only report out of model selection", async () => {
+    // MiniMax publishes its Token Plan countdown through the display-only path. The provider
+    // is single-key `key` auth, so ownership alone would resolve a routing binding; without
+    // an inference projection the exhausted row must still not rank or veto the target.
+    globalThis.fetch = (async () => Response.json({
+      success: true, data: { remains_time: 0, total_time: 1_000_000_000 },
+    })) as typeof fetch;
+    const config = quotaCombo(keyQuotaConfig("minimax", "https://api.minimax.io/v1"));
+    const reports = await fetchProviderQuotaReports(config, true);
+    expect(reports.reports[0]?.quota.customWindows?.[0]?.percent).toBe(100);
+    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("minimax");
+  });
+
+  test("routing quota scope retains the OpenRouter single-key spending cap", async () => {
+    globalThis.fetch = (async () => Response.json({ data: { limit: 20, limit_remaining: 0 } })) as typeof fetch;
+    const config = quotaCombo(keyQuotaConfig("openrouter", "https://openrouter.ai/api/v1"));
+    await fetchProviderQuotaReports(config, true);
+    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("fallback");
+  });
+
+  test("keyReport publishes routing evidence only for an explicit inference projection", () => {
+    // The MiniMax case above rides the display-only `report()` path, so it would still pass if
+    // `keyReport`'s projection were quietly defaulted back to the display quota. This drives the
+    // credential-bound helper directly: the binding resolves for BOTH calls (same single-key
+    // provider and probed credential), so the only variable left is the projection itself.
+    const provider = keyQuotaConfig("openrouter", "https://openrouter.ai/api/v1").providers.openrouter!;
+    const exhausted = { monthlyPercent: 100, updatedAt: Date.now() };
+
+    const omitted = publishKeyReportForTests("openrouter", "openrouter:key-info", exhausted, provider, "openrouter-secret");
+    expect(omitted.report?.quota.monthlyPercent).toBe(100);
+    expect(omitted.routing).toBeUndefined();
+
+    const projected = { monthlyPercent: 100, updatedAt: Date.now() };
+    const explicit = publishKeyReportForTests(
+      "openrouter", "openrouter:key-info", exhausted, provider, "openrouter-secret", projected,
+    );
+    expect(explicit.routing?.quota).toBe(projected);
+    expect(typeof explicit.routing?.binding).toBe("string");
+  });
+
+  test("routing quota scope does not apply a probed key cap to an Authorization override", async () => {
+    const probeAuth: Array<string | null> = [];
+    globalThis.fetch = (async (_input, init) => {
+      probeAuth.push(new Headers(init?.headers).get("authorization"));
+      return Response.json({ data: { limit: 20, limit_remaining: 0 } });
+    }) as typeof fetch;
+    const config = quotaCombo(keyQuotaConfig("openrouter", "https://openrouter.ai/api/v1", "spent-A"));
+    config.providers.openrouter!.headers = { Authorization: "Bearer live-B" };
+    await fetchProviderQuotaReports(config, true);
+    const request = buildOpenAIChatPassthroughRequest(routedProviderConfig("openrouter", config.providers.openrouter!), {
+      messages: [{ role: "user", content: "synthetic" }],
+    }, "primary-model", false);
+    expect(probeAuth).toEqual(["Bearer spent-A"]);
+    expect(new Headers(request.headers).get("authorization")).toBe("Bearer live-B");
+    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("openrouter");
+
+    delete config.providers.openrouter!.headers;
+    await fetchProviderQuotaReports(config, true);
+    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("fallback");
+  });
+
+  test("routing quota scope rechecks an Authorization override added after publication", async () => {
+    globalThis.fetch = (async () => Response.json({ data: { limit: 20, limit_remaining: 0 } })) as typeof fetch;
+    const config = quotaCombo(keyQuotaConfig("openrouter", "https://openrouter.ai/api/v1", "spent-A"));
+    await fetchProviderQuotaReports(config, true);
+    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("fallback");
+    config.providers.openrouter!.headers = { aUtHoRiZaTiOn: "Bearer live-B" };
+    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("openrouter");
+    delete config.providers.openrouter!.headers;
+    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("fallback");
+  });
+
+  test("routing quota scope does not apply a probed key cap to an Anthropic x-api-key override", async () => {
+    const probeAuth: Array<string | null> = [];
+    globalThis.fetch = (async (_input, init) => {
+      probeAuth.push(new Headers(init?.headers).get("authorization"));
+      return Response.json({ usage: { limit: "100", used: "100" } });
+    }) as typeof fetch;
+    const config = quotaCombo(keyQuotaConfig("kimi-code", "https://api.kimi.com/coding/v1", "spent-A"));
+    config.providers["kimi-code"]!.adapter = "anthropic";
+    config.providers["kimi-code"]!.headers = { "x-api-key": "live-B" };
+    await fetchProviderQuotaReports(config, true);
+    expect(probeAuth).toEqual(["Bearer spent-A"]);
+    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("kimi-code");
+    delete config.providers["kimi-code"]!.headers;
+    await fetchProviderQuotaReports(config, true);
+    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("fallback");
+  });
+
+  test.each(["key", "omitted", "custom-key"])("routing quota scope follows effective Kimi authentication: %s", async mode => {
+    globalThis.fetch = (async () => Response.json({ usage: { limit: "100", used: "100" } })) as typeof fetch;
+    const name = mode === "custom-key" ? "kimi-code" : "kimi";
+    const config = quotaCombo(keyQuotaConfig(name, "https://api.kimi.com/coding/v1", "spent-A"));
+    if (mode === "omitted") delete config.providers[name]!.authMode;
+    expect(routedProviderConfig(name, config.providers[name]!).authMode).toBe(mode === "custom-key" ? "key" : "oauth");
+    const report = await fetchProviderQuotaReports(config, true);
+    expect(report.reports[0]?.quota.weeklyPercent).toBe(100);
+    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe(mode === "custom-key" ? "fallback" : "kimi");
+  });
+
+  test("routing quota scope keeps an exhausted Gemini group from vetoing an Antigravity Claude target", async () => {
+    await saveCredential("google-antigravity", {
+      access: "synthetic-agy-access", refresh: "synthetic-agy-refresh",
+      expires: Date.now() + 3600_000, projectId: "synthetic-project",
+    });
+    const resetTime = new Date(Date.now() + 3600_000).toISOString();
+    setAntigravityAccountQuotaTransportForTests({
+      resolveAddresses: async () => ({ hostname: "daily-cloudcode-pa.googleapis.com", addresses: [{ address: "142.250.0.1", family: 4 }], privateNetwork: false }),
+      pinnedPost: async url => {
+        expect(url.endsWith("retrieveUserQuotaSummary")).toBe(true);
+        return Response.json({ groups: [
+          { displayName: "Gemini Models", buckets: [{ window: "5h", remainingFraction: 0, resetTime }] },
+          { displayName: "Claude and GPT models", buckets: [{ window: "5h", remainingFraction: 1, resetTime }] },
+        ] });
+      },
+    });
+    const config = quotaCombo({ defaultProvider: "google-antigravity", providers: {
+      "google-antigravity": { adapter: "google", authMode: "oauth", baseUrl: "https://daily-cloudcode-pa.googleapis.com" },
+    } } as OcxConfig);
+    config.combos!["quota-scope"]!.targets[0]!.model = "claude-sonnet-4.6";
+    const report = await fetchProviderQuotaReports(config, true);
+    expect(report.reports[0]?.quota.customWindows).toEqual([
+      { label: "Gem", percent: 100, resetAt: Date.parse(resetTime) },
+      { label: "Cla", percent: 0, resetAt: Date.parse(resetTime) },
+    ]);
+    expect(pickComboTarget(config, "quota-scope")?.target).toMatchObject({ provider: "google-antigravity", model: "claude-sonnet-4.6" });
+  });
+
+  test("routing quota scope keeps an active Anthropic account report out of whole-provider selection", async () => {
+    await saveCredential("anthropic", {
+      access: "synthetic-claude-access", refresh: "synthetic-claude-refresh", expires: Date.now() + 3600_000,
+    });
+    globalThis.fetch = (async input => {
+      expect(String(input)).toBe("https://api.anthropic.com/api/oauth/usage");
+      return Response.json({ five_hour: { utilization: 100, resets_at: new Date(Date.now() + 3600_000).toISOString() } });
+    }) as typeof fetch;
+    const config = quotaCombo({ defaultProvider: "anthropic", providers: {
+      anthropic: { adapter: "anthropic", authMode: "oauth", baseUrl: "https://api.anthropic.com/v1" },
+    } } as OcxConfig);
+    const report = await fetchProviderQuotaReports(config, true);
+    expect(report.reports[0]?.quota.fiveHourPercent).toBe(100);
+    // Account selection and its exhaustion rules still decide whether this route can dispatch.
+    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("anthropic");
+    config.providers.fallback!.disabled = true;
+    const now = Date.now();
+    const waits: number[] = [];
+    coolComboTarget("quota-scope", config.combos!["quota-scope"]!.targets[0]!, { now, cooldownMs: 1_000 });
+    const afterWait = await pickComboTargetWithWait(config, "quota-scope", {
+      now, waitForCooldownMs: 1_000, sleep: async ms => { waits.push(ms); },
+    });
+    expect(waits).toEqual([1_000]);
+    expect(afterWait?.target.provider).toBe("anthropic");
+  });
+
+  test("routing quota scope retains a verified cap through a transient refresh failure", async () => {
+    let transient = false;
+    globalThis.fetch = (async () => transient
+      ? new Response("unavailable", { status: 503 })
+      : Response.json({ data: { limit: 20, limit_remaining: 0 } })) as typeof fetch;
+    const config = quotaCombo(keyQuotaConfig("openrouter", "https://openrouter.ai/api/v1"));
+    await fetchProviderQuotaReports(config, true);
+    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("fallback");
+    transient = true;
+    await fetchProviderQuotaReports(config, true);
+    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("fallback");
+  });
+
+  test("routing quota scope stops vetoing the provider when a second key is added", async () => {
+    globalThis.fetch = (async () => Response.json({ data: { limit: 20, limit_remaining: 0 } })) as typeof fetch;
+    const config = quotaCombo(keyQuotaConfig("openrouter", "https://openrouter.ai/api/v1"));
+    await fetchProviderQuotaReports(config, true);
+    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("fallback");
+    config.providers.openrouter!.apiKeyPool = [
+      { id: "old", key: "openrouter-secret" }, { id: "new", key: "second-key" },
+    ];
+    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("openrouter");
+  });
+
+  test("routing quota scope rejects a cached cap after the active key changes", async () => {
+    globalThis.fetch = (async () => Response.json({ data: { limit: 20, limit_remaining: 0 } })) as typeof fetch;
+    const config = quotaCombo(keyQuotaConfig("openrouter", "https://openrouter.ai/api/v1"));
+    await fetchProviderQuotaReports(config, true);
+    config.providers.openrouter!.apiKey = "replacement-key";
+    expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("openrouter");
+  });
+
+  test("routing quota scope rejects a cached cap after an env key resolves differently", async () => {
+    const previous = process.env.OCX_TEST_ROUTING_QUOTA_KEY;
+    try {
+      process.env.OCX_TEST_ROUTING_QUOTA_KEY = "first-key";
+      globalThis.fetch = (async () => Response.json({ data: { limit: 20, limit_remaining: 0 } })) as typeof fetch;
+      const config = quotaCombo(keyQuotaConfig("openrouter", "https://openrouter.ai/api/v1", "$OCX_TEST_ROUTING_QUOTA_KEY"));
+      await fetchProviderQuotaReports(config, true);
+      process.env.OCX_TEST_ROUTING_QUOTA_KEY = "replacement-key";
+      expect(pickComboTarget(config, "quota-scope")?.target.provider).toBe("openrouter");
+    } finally {
+      if (previous === undefined) delete process.env.OCX_TEST_ROUTING_QUOTA_KEY;
+      else process.env.OCX_TEST_ROUTING_QUOTA_KEY = previous;
+    }
+  });
+
   test("OpenRouter quota renders a credit window against the per-key cap", async () => {
     const seen: Array<{ url: string; authorization?: string; redirect?: RequestRedirect }> = [];
     globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
@@ -1014,6 +1254,70 @@ describe("fetchProviderQuotaReports", () => {
     expect(seen[0]?.redirect).toBe("error");
   });
 
+  test.each([
+    ["https://api.z.ai/api/anthropic", "anthropic"],
+    ["https://api.z.ai/api/v1", "openai-responses"],
+    ["https://API.Z.AI/api/anthropic/", "anthropic"],
+    ["https://api.z.ai/api/v1/", "openai-responses"],
+  ] as const)("Z.AI quota uses the international monitor for %s (%s)", async (baseUrl, adapter) => {
+    const seen: Array<{ url: string; authorization: string | null; redirect?: RequestRedirect }> = [];
+    globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+      seen.push({ url: String(input), authorization: new Headers(init?.headers).get("authorization"), redirect: init?.redirect });
+      return Response.json({ success: true, data: { limits: [
+        { type: "TOKENS_LIMIT", unit: 3, number: 5, percentage: 25 },
+      ] } });
+    }) as typeof fetch;
+    const config = keyQuotaConfig("zai", baseUrl);
+    config.providers.zai!.adapter = adapter;
+
+    const result = await fetchProviderQuotaReports(config, true);
+
+    expect(result.reports).toHaveLength(1);
+    expect(result.reports[0]?.source).toBe("zai:quota-limit");
+    expect(result.reports[0]?.quota.fiveHourPercent).toBe(25);
+    expect(seen).toEqual([{
+      url: "https://api.z.ai/api/monitor/usage/quota/limit",
+      authorization: "Bearer zai-secret",
+      redirect: "error",
+    }]);
+  });
+
+  test.each([
+    "https://api.z.ai.example/api/anthropic",
+    "http://api.z.ai/api/anthropic",
+    "https://api.z.ai:8443/api/v1",
+    "https://api.z.ai/api/anthropic?region=cn",
+    "https://api.z.ai/api/v1#fragment",
+    "https://api.z.ai/api/anthropic/v1/messages",
+    "https://api.z.ai/api/v1/responses",
+    "https://api.z.ai/api/paas/v4",
+    "https://open.bigmodel.cn/api/anthropic",
+  ])("Z.AI quota does not probe unsupported base %s", async baseUrl => {
+    let calls = 0;
+    globalThis.fetch = (async () => {
+      calls += 1;
+      return new Response("unexpected", { status: 500 });
+    }) as typeof fetch;
+
+    expect((await fetchProviderQuotaReports(keyQuotaConfig("zai", baseUrl), true)).reports).toEqual([]);
+    expect(calls).toBe(0);
+  });
+
+  test.each(["username", "password"] as const)("Z.AI quota rejects URL %s before probing", async field => {
+    // Construct dummy userinfo instead of embedding an email-shaped fixture in source.
+    // Keep this distinct from host/path rejection: the monitor host would otherwise match.
+    const url = new URL("https://api.z.ai/api/anthropic");
+    url[field] = "fixture";
+    let calls = 0;
+    globalThis.fetch = (async () => {
+      calls += 1;
+      return new Response("unexpected", { status: 500 });
+    }) as typeof fetch;
+
+    expect((await fetchProviderQuotaReports(keyQuotaConfig("zai", url.href), true)).reports).toEqual([]);
+    expect(calls).toBe(0);
+  });
+
   test("Z.AI quota probes the BigModel region from the provider's own host", async () => {
     const seen: Array<{ url: string; authorization?: string; redirect?: RequestRedirect }> = [];
     globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
diff --git a/tests/providers/provider-registry-parity.test.ts b/tests/providers/provider-registry-parity.test.ts
index 1dcc89ca1f..bfe4532edb 100644
--- a/tests/providers/provider-registry-parity.test.ts
+++ b/tests/providers/provider-registry-parity.test.ts
@@ -14,7 +14,7 @@ import {
   enrichProviderFromRegistry,
   providerConfigSeed,
 } from "../../src/providers/derive";
-import { PROVIDER_REGISTRY } from "../../src/providers/registry";
+import { PROVIDER_REGISTRY, registryEntryForProviderDestination } from "../../src/providers/registry";
 import { FREE_PROVIDER_DIRECTORY } from "../../src/providers/free-directory";
 import { applyProviderConfigHints } from "../../src/codex/catalog";
 import { routeModel } from "../../src/router";
@@ -73,12 +73,87 @@ describe("provider registry parity", () => {
     expect(KEY_LOGIN_PROVIDERS["opencode-go"].noVisionModels).toEqual([
       "glm-5.3",
       "glm-5.2", "glm-5", "glm-5.1",
-      "deepseek-v4-flash", "deepseek-v4-pro",
+      "deepseek-v4.1-flash", "deepseek-v4-flash",
       "mimo-v2-pro", "mimo-v2.5-pro",
       "minimax-m2.5", "minimax-m2.7",
       "qwen3.7-max",
     ]);
     expect(KEY_LOGIN_PROVIDERS["opencode-go"].noVisionModels).not.toContain("kimi-k2.7-code");
+    // #1338 / #1415: the Zen gateway rejects json_schema on its DeepSeek routes. The three
+    // presets that share that gateway carry the narrow opt-out as a registry-only seed, so
+    // an operator no longer has to disable structured output by hand. Registry-only means
+    // it is asserted here against the raw entry, not the derived key-login map.
+    const zenDeepseekJsonSchema: Record<string, string[]> = {
+      "opencode-go": ["deepseek-v4.1-flash", "deepseek-v4-flash"],
+      "opencode-zen": ["deepseek-v4.1-flash", "deepseek-v4-flash", "deepseek-v4-flash-free"],
+      "opencode-free": ["deepseek-v4.1-flash", "deepseek-v4-flash", "deepseek-v4-flash-free"],
+    };
+    for (const [id, expected] of Object.entries(zenDeepseekJsonSchema)) {
+      expect(PROVIDER_REGISTRY.find(entry => entry.id === id)?.noJsonSchemaModels).toEqual(expected);
+    }
+    /*
+     * DeepSeek's V4.1 transition (2026-09-10) split the spelling by who serves the route:
+     * the first-party API answers to `deepseek-flash`, the Zen gateway exposes
+     * `deepseek-v4.1-flash`. A single shared list cannot express that, and the earlier
+     * draft that tried it would have leaked the gateway spelling into the native preset.
+     * Pin both directions, including the negatives — a future edit that collapses the two
+     * constants back together fails here rather than in a user's request.
+     */
+    const nativeDeepseek = PROVIDER_REGISTRY.find(entry => entry.id === "deepseek");
+    expect(nativeDeepseek?.defaultModel).toBe("deepseek-flash");
+    expect(nativeDeepseek?.models).toContain("deepseek-flash");
+    for (const map of [
+      nativeDeepseek?.modelReasoningEfforts,
+      nativeDeepseek?.modelReasoningEffortMap,
+      nativeDeepseek?.modelSupportsReasoningSummaries,
+      nativeDeepseek?.modelContextWindows,
+    ]) {
+      expect(Object.keys(map ?? {})).toContain("deepseek-flash");
+    }
+    expect(nativeDeepseek?.preserveReasoningContentModels).toContain("deepseek-flash");
+    expect(nativeDeepseek?.noVisionModels).toContain("deepseek-flash");
+    // The new id keeps the Flash ladder, not the Pro one, through isDeepseekFlashModel.
+    expect(nativeDeepseek?.modelReasoningEfforts?.["deepseek-flash"])
+      .toEqual(nativeDeepseek?.modelReasoningEfforts?.["deepseek-v4-flash"]);
+
+    const zenGo = PROVIDER_REGISTRY.find(entry => entry.id === "opencode-go");
+    expect(zenGo?.preserveReasoningContentModels).toContain("deepseek-v4.1-flash");
+    expect(zenGo?.noVisionModels).toContain("deepseek-v4.1-flash");
+    expect(Object.keys(zenGo?.modelReasoningEfforts ?? {})).toContain("deepseek-v4.1-flash");
+
+    // Negatives: neither spelling crosses into the other side.
+    expect(JSON.stringify(nativeDeepseek)).not.toContain("deepseek-v4.1-flash");
+    for (const id of ["opencode-go", "opencode-zen", "opencode-free"]) {
+      expect(JSON.stringify(PROVIDER_REGISTRY.find(entry => entry.id === id)))
+        .not.toContain("\"deepseek-flash\"");
+    }
+    // Vendor-hosted rosters publish on their own schedule and keep the legacy set.
+    expect(PROVIDER_REGISTRY.find(entry => entry.id === "volcengine-coding-plan")?.preserveReasoningContentModels)
+      .toEqual(["deepseek-v4-flash"]);
+    // A model can only be gated onto the thinking-budget or thinking-toggle wire if the same
+    // preset also gives it an effort ladder — otherwise the adapter translates effort into a
+    // wire field for a model whose picker is empty. opencode-go carried the shared budget list
+    // while seeding only its own four ladders, so a live roster serving qwen3.5-397b armed the
+    // budget path with nothing to advertise.
+    for (const id of ["opencode-go", "opencode-zen", "opencode-free"]) {
+      const entry = PROVIDER_REGISTRY.find(candidate => candidate.id === id);
+      const ladders = Object.keys(entry?.modelReasoningEfforts ?? {});
+      const gated = [...entry?.thinkingBudgetModels ?? [], ...entry?.thinkingToggleModels ?? []];
+      expect({ id, ungated: gated.filter(model => !ladders.includes(model)) })
+        .toEqual({ id, ungated: [] });
+    }
+    // Issue #78 / #950: a DeepSeek route that advertises a thinking ladder must also replay
+    // reasoning_content on tool-call continuations, or the gateway answers 400 on the second
+    // turn. The three Zen presets seed those two tables by hand, so this pins the pairing
+    // instead of trusting that whoever adds the next route remembers both.
+    for (const id of ["opencode-go", "opencode-zen", "opencode-free"]) {
+      const entry = PROVIDER_REGISTRY.find(candidate => candidate.id === id);
+      const replayed = entry?.preserveReasoningContentModels ?? [];
+      const thinkingDeepseek = Object.keys(entry?.modelReasoningEfforts ?? {})
+        .filter(model => model.startsWith("deepseek-"));
+      expect({ id, unreplayed: thinkingDeepseek.filter(model => !replayed.includes(model)) })
+        .toEqual({ id, unreplayed: [] });
+    }
     expect(KEY_LOGIN_PROVIDERS.mimo.noVisionModels).toEqual(["mimo-v2.5-pro"]);
     expect(KEY_LOGIN_PROVIDERS.mimo.noVisionModels).not.toContain("mimo-v2.5");
     expect(KEY_LOGIN_PROVIDERS["opencode-go"]).toMatchObject({
@@ -145,23 +220,26 @@ describe("provider registry parity", () => {
     expect(KEY_LOGIN_PROVIDERS.openrouter.modelContextWindows?.["openai/gpt-5.6-sol"]).toBe(1_050_000);
     expect(KEY_LOGIN_PROVIDERS.openrouter.modelContextWindows?.["openai/gpt-5.6-terra"]).toBe(1_050_000);
     expect(KEY_LOGIN_PROVIDERS.openrouter.modelContextWindows?.["openai/gpt-5.6-luna"]).toBe(1_050_000);
-    expect(KEY_LOGIN_PROVIDERS.deepseek.models).toContain("deepseek-v4-pro");
+    // Retired from the first-party API on 2026-09-14; the vendor-hosted rosters keep it.
+    expect(KEY_LOGIN_PROVIDERS.deepseek.models).not.toContain("deepseek-v4-pro");
+    expect(KEY_LOGIN_PROVIDERS.deepseek.models).toContain("deepseek-flash");
     // #1057: DeepSeek's ladder is low/high/max and the two V4 models resolve it
     // differently (api-docs.deepseek.com/guides/thinking_mode, verified 2026-08-06).
     // `xhigh` is an alias, so it stays in the wire map but is not advertised. Pro
     // does not honor `low` (the vendor maps it to `high`), so Pro must not offer it.
-    expect(KEY_LOGIN_PROVIDERS.deepseek.modelReasoningEfforts?.["deepseek-v4-pro"]).toEqual(["low", "high", "max"]);
+    expect(KEY_LOGIN_PROVIDERS.deepseek.modelReasoningEfforts?.["deepseek-flash"]).toEqual(["low", "high", "max"]);
     expect(KEY_LOGIN_PROVIDERS.deepseek.modelReasoningEfforts?.["deepseek-v4-flash"]).toEqual(["low", "high", "max"]);
-    expect(KEY_LOGIN_PROVIDERS.deepseek.modelReasoningEffortMap?.["deepseek-v4-pro"]?.low).toBe("low");
-    expect(KEY_LOGIN_PROVIDERS.deepseek.modelReasoningEffortMap?.["deepseek-v4-pro"]?.xhigh).toBe("high");
-    expect(KEY_LOGIN_PROVIDERS.deepseek.modelReasoningEffortMap?.["deepseek-v4-pro"]?.max).toBe("max");
+    expect(KEY_LOGIN_PROVIDERS.deepseek.modelReasoningEffortMap?.["deepseek-flash"]?.low).toBe("low");
+    expect(KEY_LOGIN_PROVIDERS.deepseek.modelReasoningEffortMap?.["deepseek-flash"]?.xhigh).toBe("high");
+    expect(KEY_LOGIN_PROVIDERS.deepseek.modelReasoningEffortMap?.["deepseek-flash"]?.max).toBe("max");
     expect(KEY_LOGIN_PROVIDERS.deepseek.modelReasoningEffortMap?.["deepseek-v4-flash"]?.low).toBe("low");
     expect(KEY_LOGIN_PROVIDERS.deepseek.modelReasoningEffortMap?.["deepseek-v4-flash"]?.xhigh).toBe("high");
     expect(KEY_LOGIN_PROVIDERS.deepseek.modelReasoningEffortMap?.["deepseek-v4-flash"]?.max).toBe("max");
-    expect(KEY_LOGIN_PROVIDERS.deepseek.preserveReasoningContentModels).toEqual(["deepseek-v4-pro", "deepseek-v4-flash"]);
+    expect(KEY_LOGIN_PROVIDERS.deepseek.preserveReasoningContentModels)
+      .toEqual(["deepseek-flash", "deepseek-v4-flash"]);
     // Issue #88: every DeepSeek API model is text-only input — the vision sidecar covers them.
     expect(KEY_LOGIN_PROVIDERS.deepseek.noVisionModels).toEqual([
-      "deepseek-chat", "deepseek-reasoner", "deepseek-v4-pro", "deepseek-v4-flash",
+      "deepseek-chat", "deepseek-reasoner", "deepseek-flash", "deepseek-v4-flash",
     ]);
   });
 
@@ -270,10 +348,9 @@ describe("provider registry parity", () => {
     expect(deepseek).toMatchObject({
       adapter: "openai-chat",
       baseUrl: "https://api.deepseek.com",
-      defaultModel: "deepseek-v4-flash",
+      defaultModel: "deepseek-flash",
       modelContextWindows: {
         "deepseek-v4-flash": 1_048_576,
-        "deepseek-v4-pro": 1_048_576,
       },
     });
 
@@ -322,7 +399,7 @@ describe("provider registry parity", () => {
       liveModels: false,
       models: [
         "qwen3.8-max", "qwen3.7-max", "qwen3.7-plus", "qwen3.6-flash",
-        "glm-5.3", "glm-5.3-flash", "glm-5.2", "deepseek-v4-pro",
+        "glm-5.3", "glm-5.3-flash", "glm-5.2",
       ],
       modelInputModalities: {
         "qwen3.8-max": ["text", "image"],
@@ -335,9 +412,8 @@ describe("provider registry parity", () => {
       modelContextWindows: {
         "qwen3.8-max": 983_616,
         "qwen3.7-max": 1_000_000,
-        "deepseek-v4-pro": 1_000_000,
       },
-      noVisionModels: ["glm-5.3", "glm-5.2", "deepseek-v4-pro"],
+      noVisionModels: ["glm-5.3", "glm-5.2"],
       preserveReasoningContentModels: expect.arrayContaining(["qwen3.8-max", "qwen3.7-max", "qwen3.7-plus"]),
     });
     expect(PROVIDER_REGISTRY.find(entry => entry.id === "alibaba-token-plan")?.directReasoningEffortModels)
@@ -383,7 +459,9 @@ describe("provider registry parity", () => {
     const optedInProviders = PROVIDER_REGISTRY
       .filter(entry => entry.modelSuffixBracketStrip)
       .map(entry => entry.id);
-    expect(zai?.modelContextWindows).toEqual({ "glm-5.3": 1_000_000, "glm-5.3[1m]": 1_000_000, "glm-5.3-flash": 1_000_000, "glm-5.2": 1_000_000, "glm-5.2[1m]": 1_000_000 });
+    // The 5.3 family carries the number its own catalog reports, 1_048_576, which is what the
+    // domestic Responses row already used. 5.2 keeps the round figure it was seeded with.
+    expect(zai?.modelContextWindows).toEqual({ "glm-5.3": 1_048_576, "glm-5.3[1m]": 1_048_576, "glm-5.3-flash": 1_048_576, "glm-5.2": 1_000_000, "glm-5.2[1m]": 1_000_000 });
     // BUG-R5: glm-5.3-flash is a native VLM (docs.z.ai/guides/vlm/glm-5.3-flash), so it
     // must never sit in noVisionModels - that list routes a model's images through the
     // proxy's vision sidecar, which hands the model a text description of a picture it
@@ -406,6 +484,21 @@ describe("provider registry parity", () => {
     // The sibling it is most often confused with stays text-only, so the assertion above
     // cannot pass by making every GLM row a VLM.
     expect(zai?.noVisionModels ?? []).toContain("glm-5.3");
+    // The global loop above accepts an ABSENT declaration, which is exactly how the Chat
+    // rows shipped: Flash was kept out of the sidecar but never told the catalog it could
+    // read an image, so `configuredInputModalities` returned undefined and every client
+    // export listed a native VLM as text-only. Pin the positive declaration so the two
+    // Chat rows cannot drift back to describing Flash only by what it is not.
+    for (const id of ["zai", "zhipu-bigmodel-coding"] as const) {
+      const row = PROVIDER_REGISTRY.find(entry => entry.id === id);
+      expect(row?.modelInputModalities?.["glm-5.3-flash"]).toEqual(["text", "image"]);
+      expect(row?.modelInputModalities?.["glm-5.3"]).toEqual(["text"]);
+      // The bracketed aliases are looked up by their exact catalog id, not a stripped one,
+      // so they need their own text-only entries.
+      expect(row?.modelInputModalities?.["glm-5.3[1m]"]).toEqual(["text"]);
+      expect(row?.modelInputModalities?.["glm-5.2[1m]"]).toEqual(["text"]);
+      expect(row?.noVisionModels ?? []).not.toContain("glm-5.3-flash");
+    }
     // `glm-5.3-flash` belongs in all three maps. It was seeded into the model list
     // and the context map alone, so it advertised a 1M window with no effort ladder,
     // no default effort and no output cap - and this assertion pinned that gap in
@@ -421,6 +514,27 @@ describe("provider registry parity", () => {
       expect(zai?.modelMaxOutputTokens?.[id]).toBe(131_072);
     }
     expect(providerConfigSeed(zai!).modelSuffixBracketStrip).toBe(true);
+    // Responses is the default wire and Chat stays reachable per model. The two live under
+    // different prefixes on one host, so each carries its own relative send path; a wire
+    // override swaps the adapter and leaves baseUrl alone.
+    expect(zai?.adapter).toBe("openai-responses");
+    expect(zai?.baseUrl).toBe("https://api.z.ai");
+    expect(zai?.responsesPath).toBe("/api/v1/responses");
+    expect(zai?.chatCompletionsPath).toBe("/api/coding/paas/v4/chat/completions");
+    expect(providerConfigSeed(zai!).responsesPath).toBe("/api/v1/responses");
+    expect(providerConfigSeed(zai!).chatCompletionsPath).toBe("/api/coding/paas/v4/chat/completions");
+    // A config saved against the address this row used to occupy still resolves to it,
+    // so an existing custom provider does not quietly lose its metadata (#1100).
+    expect(registryEntryForProviderDestination({
+      adapter: "openai-chat",
+      baseUrl: "https://api.z.ai/api/coding/paas/v4",
+      authMode: "key",
+    })?.id).toBe("zai");
+    expect(registryEntryForProviderDestination({
+      adapter: "openai-responses",
+      baseUrl: "https://api.z.ai",
+      authMode: "key",
+    })?.id).toBe("zai");
     expect(providerConfigSeed(zai!).modelDefaultReasoningEfforts?.["glm-5.3"]).toBe("max");
     expect(deriveKeyLoginMap().zai.modelMaxOutputTokens?.["glm-5.3[1m]"]).toBe(131_072);
     // `zhipu-bigmodel-coding` opts in for the same reason `zai` does: it serves the same
@@ -782,7 +896,7 @@ describe("provider registry parity", () => {
     const ollamaCloud = PROVIDER_REGISTRY.find(entry => entry.id === "ollama-cloud");
 
     expect(ollamaCloud?.models).toEqual([
-      "glm-5.3", "glm-5.3-flash", "glm-5.2", "deepseek-v4-pro", "qwen3-coder:480b", "gpt-oss:120b",
+      "glm-5.3", "glm-5.3-flash", "glm-5.2", "qwen3-coder:480b", "gpt-oss:120b",
       "kimi-k2.6", "minimax-m3", "qwen3.5:397b", "gemma4:31b",
     ]);
     expect(ollamaCloud?.models).not.toContain("qwen3-coder");
@@ -1386,15 +1500,11 @@ describe("free-provider directory isolation", () => {
     const flashLadder = ["low", "high", "max"];
     const proLadder = ["low", "high", "max"];
     const cases: Array<{ provider: string; model: string; flash: boolean }> = [
-      { provider: "deepseek", model: "deepseek-v4-pro", flash: false },
+      { provider: "deepseek", model: "deepseek-flash", flash: true },
       { provider: "deepseek", model: "deepseek-v4-flash", flash: true },
-      { provider: "opencode-go", model: "deepseek-v4-pro", flash: false },
+      { provider: "opencode-go", model: "deepseek-v4.1-flash", flash: true },
       { provider: "opencode-go", model: "deepseek-v4-flash", flash: true },
-      { provider: "orcarouter", model: "deepseek/deepseek-v4-pro", flash: false },
-      { provider: "volcengine-coding-plan", model: "deepseek-v4-pro", flash: false },
       { provider: "volcengine-coding-plan", model: "deepseek-v4-flash", flash: true },
-      { provider: "alibaba-token-plan", model: "deepseek-v4-pro", flash: false },
-      { provider: "alibaba-token-plan-intl", model: "deepseek-v4-pro", flash: false },
       { provider: "alibaba-token-plan-intl", model: "deepseek-v4-flash", flash: true },
       { provider: "opencode-free", model: "deepseek-v4-flash-free", flash: true },
     ];
diff --git a/tests/providers/upstream-transient-retry.test.ts b/tests/providers/upstream-transient-retry.test.ts
index 58199ac55a..77a224eb36 100644
--- a/tests/providers/upstream-transient-retry.test.ts
+++ b/tests/providers/upstream-transient-retry.test.ts
@@ -1,5 +1,11 @@
 import { describe, expect, test } from "bun:test";
-import { fetchWithTransientRetry, isTransientUpstreamStatus } from "../../src/lib/upstream-retry";
+import {
+  fetchWithTransientRetry,
+  isNonReplayableResponse,
+  isNonReplayableUpstreamCode,
+  isTransientUpstreamStatus,
+  markResponseNonReplayable,
+} from "../../src/lib/upstream-retry";
 import { transientRetryPolicyFor } from "../../src/providers/key-failover";
 import type { OcxProviderConfig } from "../../src/types";
 
@@ -50,6 +56,40 @@ describe("transientRetryPolicyFor", () => {
 });
 
 describe("fetchWithTransientRetry", () => {
+  test("a non-replayable gateway status is returned after one send, body intact", async () => {
+    // The Codex WebSocket relay settles a 504 when the origin never acknowledged a frame it
+    // already sent. 504 is transient by status, but the origin may be executing that turn:
+    // the marker, not the status, decides that this layer must not send the body again.
+    let sends = 0;
+    const res = await fetchWithTransientRetry(async () => {
+      sends += 1;
+      const response = bodyResponse(504);
+      markResponseNonReplayable(response);
+      return response;
+    }, { attempts: 3, slowAttemptMs: 60_000 });
+    expect(sends).toBe(1);
+    expect(res.status).toBe(504);
+    expect(isNonReplayableResponse(res)).toBe(true);
+    expect((res as Response & { __wasCancelled: () => boolean }).__wasCancelled()).toBe(false);
+  });
+
+  test("an unmarked 504 keeps the transient retry", async () => {
+    let sends = 0;
+    const res = await fetchWithTransientRetry(async () => {
+      sends += 1;
+      return bodyResponse(504);
+    }, { attempts: 2, slowAttemptMs: 60_000 });
+    expect(sends).toBe(2);
+    expect(res.status).toBe(504);
+  });
+
+  test("the structured codes name exactly the two post-send verdicts", () => {
+    expect(isNonReplayableUpstreamCode("upstream_no_response")).toBe(true);
+    expect(isNonReplayableUpstreamCode("upstream_closed_before_response")).toBe(true);
+    expect(isNonReplayableUpstreamCode("upstream_error")).toBe(false);
+    expect(isNonReplayableUpstreamCode(undefined)).toBe(false);
+  });
+
   test("attempts is one total-send budget, not a per-layer multiplier", async () => {
     // The two layers used to multiply: attempts:3 meant 3 transient rounds each independently
     // retrying 3 connection resets, so a single call could emit up to 9 upstream sends. All
diff --git a/tests/providers/xai/grok-reset-coupon-cli.test.ts b/tests/providers/xai/grok-reset-coupon-cli.test.ts
new file mode 100644
index 0000000000..39ce3632cf
--- /dev/null
+++ b/tests/providers/xai/grok-reset-coupon-cli.test.ts
@@ -0,0 +1,97 @@
+// CLI surface for the Grok reset-coupon management endpoints. The management
+// routes have their own coverage; this file pins the account-auth subcommand
+// contract: local flag validation refuses before any fetch, and the read path
+// reaches the coupon listing endpoint and prints the tokens.
+import { describe, expect, test } from "bun:test";
+import { handleAccountAuthCommand } from "../../../src/cli/account-auth";
+import type { RuntimeApiDeps } from "../../../src/cli/runtime-api";
+
+interface Captured {
+  method: string;
+  path: string;
+  body: unknown;
+}
+
+function deps(respond: (captured: Captured) => unknown, calls: Captured[]): RuntimeApiDeps {
+  return {
+    baseUrl: "http://127.0.0.1:10100",
+    fetchImpl: (async (url: string | URL | Request, init?: RequestInit) => {
+      const parsed = new URL(String(url));
+      const captured: Captured = {
+        method: init?.method ?? "GET",
+        path: `${parsed.pathname}${parsed.search}`,
+        body: init?.body === undefined ? undefined : JSON.parse(String(init.body)),
+      };
+      calls.push(captured);
+      return new Response(JSON.stringify(respond(captured)), { status: 200 });
+    }) as unknown as typeof fetch,
+  };
+}
+
+function capture(): { lines: string[]; errors: string[]; restore: () => void } {
+  const lines: string[] = [];
+  const errors: string[] = [];
+  const log = console.log;
+  const err = console.error;
+  console.log = (...a: unknown[]) => { lines.push(a.map(String).join(" ")); };
+  console.error = (...a: unknown[]) => { errors.push(a.map(String).join(" ")); };
+  return { lines, errors, restore: () => { console.log = log; console.error = err; } };
+}
+
+describe("ocx account grok-reset-coupons", () => {
+  test("--consume without --yes refuses locally, before any fetch", async () => {
+    const calls: Captured[] = [];
+    const out = capture();
+    let code: number;
+    try {
+      code = await handleAccountAuthCommand("grok-reset-coupons", ["--consume"], deps(() => ({}), calls));
+    } finally {
+      out.restore();
+    }
+    expect(code).toBe(2);
+    expect(out.errors.join("\n")).toContain("--yes");
+    expect(calls).toHaveLength(0);
+  });
+
+  test("--operation-id that is not a UUIDv4 refuses before any fetch", async () => {
+    const calls: Captured[] = [];
+    const out = capture();
+    let code: number;
+    try {
+      code = await handleAccountAuthCommand(
+        "grok-reset-coupons",
+        ["main", "--consume", "--yes", "--operation-id", "nope"],
+        deps(() => ({}), calls),
+      );
+    } finally {
+      out.restore();
+    }
+    expect(code).toBe(2);
+    expect(out.errors.join("\n")).toContain("UUIDv4");
+    expect(calls).toHaveLength(0);
+  });
+
+  test("a read GETs the coupon list for the account and prints the tokens", async () => {
+    const calls: Captured[] = [];
+    const out = capture();
+    let code: number;
+    try {
+      code = await handleAccountAuthCommand(
+        "grok-reset-coupons",
+        ["main", "--json"],
+        deps(() => ({
+          accountId: "__main__",
+          tokens: [{ tokenId: "tok-1", validityStart: "2026-09-01", validityEnd: "2026-10-01" }],
+          remaining: 1,
+        }), calls),
+      );
+    } finally {
+      out.restore();
+    }
+    expect(code).toBe(0);
+    expect(calls).toHaveLength(1);
+    expect(calls[0]!.method).toBe("GET");
+    expect(calls[0]!.path).toBe("/api/grok/reset-coupons?accountId=__main__");
+    expect(out.lines.join("\n")).toContain("tok-1");
+  });
+});
diff --git a/tests/providers/xai/grok-reset-coupons.test.ts b/tests/providers/xai/grok-reset-coupons.test.ts
new file mode 100644
index 0000000000..6214356840
--- /dev/null
+++ b/tests/providers/xai/grok-reset-coupons.test.ts
@@ -0,0 +1,275 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  decodeGrpcWebResponse,
+  encodeGrpcWebEnvelope,
+  GrpcWebError,
+  parseGrpcWebTrailers,
+} from "../../../src/grok/grpc-web";
+import {
+  getGrokRemainingResets,
+  decodeGetRemainingResetsResponse,
+  encodeRedeemResetRequest,
+  encodeVarint,
+  GROK_GET_REMAINING_RESETS_ENDPOINT,
+  GROK_REDEEM_RESET_ENDPOINT,
+  redeemGrokResetCoupon,
+} from "../../../src/grok/reset-coupons";
+import {
+  grokCouponJournalPath,
+  openGrokResetCouponOperation,
+  recordGrokResetCouponSettlement,
+} from "../../../src/grok/reset-coupon-ledger";
+
+describe("grok reset coupons", () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "grok-coupons-test-"));
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("round-trips grpc-web data framing and parses trailers", () => {
+    const payload = new TextEncoder().encode("test-payload-bytes");
+    const dataEnvelope = encodeGrpcWebEnvelope(payload);
+
+    expect(dataEnvelope[0]).toBe(0x00);
+    const view = new DataView(dataEnvelope.buffer, dataEnvelope.byteOffset, 5);
+    expect(view.getUint32(1, false)).toBe(payload.length);
+
+    const trailerPayload = new TextEncoder().encode("grpc-status:0\r\ngrpc-message:ok\r\n");
+    const trailerEnvelope = new Uint8Array(5 + trailerPayload.length);
+    trailerEnvelope[0] = 0x80;
+    const trailerView = new DataView(trailerEnvelope.buffer, trailerEnvelope.byteOffset, 5);
+    trailerView.setUint32(1, trailerPayload.length, false);
+    trailerEnvelope.set(trailerPayload, 5);
+
+    const combined = new Uint8Array(dataEnvelope.length + trailerEnvelope.length);
+    combined.set(dataEnvelope, 0);
+    combined.set(trailerEnvelope, dataEnvelope.length);
+
+    const decoded = decodeGrpcWebResponse(combined);
+    expect(decoded.messages.length).toBe(1);
+    expect(new TextDecoder().decode(decoded.messages[0])).toBe("test-payload-bytes");
+    expect(decoded.status).toBe(0);
+    expect(decoded.statusMessage).toBe("ok");
+  });
+
+  it("decodes captured live-shape GetRemainingResetsResponse fixture", () => {
+    // Construct protobuf binary:
+    // Field 10 (tokens):
+    //   Field 10 (tokenId): "token_live_abc123"
+    //   Field 20 (validityStart): Field 1 (seconds): 1726110000
+    //   Field 30 (validityEnd): Field 1 (seconds): 1728788400
+    const buildTimestamp = (sec: number) => {
+      const secTag = (1 << 3) | 0; // field 1, varint
+      const secBytes = encodeVarint(sec);
+      const out = new Uint8Array(1 + secBytes.length);
+      out[0] = secTag;
+      out.set(secBytes, 1);
+      return out;
+    };
+
+    const buildToken = (tokenId: string, startSec: number, endSec: number) => {
+      const idBytes = new TextEncoder().encode(tokenId);
+      const idTag = (10 << 3) | 2;
+      const idLen = encodeVarint(idBytes.length);
+
+      const startBytes = buildTimestamp(startSec);
+      const startTag = (20 << 3) | 2;
+      const startLen = encodeVarint(startBytes.length);
+
+      const endBytes = buildTimestamp(endSec);
+      const endTag = (30 << 3) | 2;
+      const endLen = encodeVarint(endBytes.length);
+
+      const totalLen =
+        1 + idLen.length + idBytes.length +
+        encodeVarint(startTag).length + startLen.length + startBytes.length +
+        encodeVarint(endTag).length + endLen.length + endBytes.length;
+
+      const out = new Uint8Array(totalLen);
+      let offset = 0;
+      out[offset++] = idTag;
+      out.set(idLen, offset);
+      offset += idLen.length;
+      out.set(idBytes, offset);
+      offset += idBytes.length;
+
+      const startTagBytes = encodeVarint(startTag);
+      out.set(startTagBytes, offset);
+      offset += startTagBytes.length;
+      out.set(startLen, offset);
+      offset += startLen.length;
+      out.set(startBytes, offset);
+      offset += startBytes.length;
+
+      const endTagBytes = encodeVarint(endTag);
+      out.set(endTagBytes, offset);
+      offset += endTagBytes.length;
+      out.set(endLen, offset);
+      offset += endLen.length;
+      out.set(endBytes, offset);
+      offset += endBytes.length;
+
+      return out;
+    };
+
+    const tokenSub = buildToken("token_live_abc123", 1726110000, 1728788400);
+    const topTag = (10 << 3) | 2;
+    const topLen = encodeVarint(tokenSub.length);
+    const responsePayload = new Uint8Array(1 + topLen.length + tokenSub.length);
+    responsePayload[0] = topTag;
+    responsePayload.set(topLen, 1);
+    responsePayload.set(tokenSub, 1 + topLen.length);
+
+    const tokens = decodeGetRemainingResetsResponse(responsePayload);
+    expect(tokens.length).toBe(1);
+    expect(tokens[0].tokenId).toBe("token_live_abc123");
+    expect(tokens[0].validityStart).toBe(new Date(1726110000 * 1000).toISOString());
+    expect(tokens[0].validityEnd).toBe(new Date(1728788400 * 1000).toISOString());
+  });
+
+  it("asserts auth headers and tokenAuth compatibility header on request", async () => {
+    let capturedHeaders: Headers | undefined;
+    let capturedBody: Uint8Array | undefined;
+
+    const mockFetch: typeof globalThis.fetch = async (input, init) => {
+      capturedHeaders = new Headers(init?.headers);
+      if (init?.body instanceof Uint8Array) {
+        capturedBody = init.body;
+      }
+      const emptyTrailer = new TextEncoder().encode("grpc-status:0\r\ngrpc-message:\r\n");
+      const envelope = new Uint8Array(5 + emptyTrailer.length);
+      envelope[0] = 0x80;
+      new DataView(envelope.buffer).setUint32(1, emptyTrailer.length, false);
+      envelope.set(emptyTrailer, 5);
+
+      return new Response(envelope, {
+        status: 200,
+        headers: { "content-type": "application/grpc-web+proto" },
+      });
+    };
+
+    await getGrokRemainingResets({
+      accessToken: "mock-access-token-12345",
+      fetchFn: mockFetch,
+    });
+
+    expect(capturedHeaders?.get("authorization")).toBe("Bearer mock-access-token-12345");
+    expect(capturedHeaders?.get("x-xai-token-auth")).toBe("xai-grok-cli");
+    expect(capturedHeaders?.get("x-grpc-web")).toBe("1");
+    expect(capturedHeaders?.get("content-type")).toBe("application/grpc-web+proto");
+    expect(capturedBody).toBeDefined();
+    expect(capturedBody?.[0]).toBe(0x00); // gRPC-Web data frame prefix
+  });
+
+  it("surfaces grpc-status 3 error on invalid token redemption", async () => {
+    const mockFetch: typeof globalThis.fetch = async () => {
+      const trailer = new TextEncoder().encode("grpc-status:3\r\ngrpc-message:redeem_reset()%2C%20Invalid%20token_id\r\n");
+      const envelope = new Uint8Array(5 + trailer.length);
+      envelope[0] = 0x80;
+      new DataView(envelope.buffer).setUint32(1, trailer.length, false);
+      envelope.set(trailer, 5);
+
+      return new Response(envelope, {
+        status: 200,
+        headers: { "content-type": "application/grpc-web+proto" },
+      });
+    };
+
+    let thrown: unknown;
+    try {
+      await redeemGrokResetCoupon({
+        accessToken: "test-token",
+        tokenId: "invalid_id_999",
+        fetchFn: mockFetch,
+      });
+    } catch (err) {
+      thrown = err;
+    }
+
+    expect(thrown).toBeInstanceOf(GrpcWebError);
+    const grpcErr = thrown as GrpcWebError;
+    expect(grpcErr.status).toBe(3);
+    expect(grpcErr.statusMessage).toContain("Invalid token_id");
+  });
+
+  it("handles crash-safe ledger open and idempotent replay", () => {
+    const ledgerPath = grokCouponJournalPath(tempDir);
+
+    const first = openGrokResetCouponOperation({
+      accountId: "acc-123",
+      tokenId: "tok-456",
+      operationId: "op-uuid-1",
+    }, undefined, ledgerPath);
+    expect(first.kind).toBe("execute");
+
+    recordGrokResetCouponSettlement({
+      operationId: "op-uuid-1",
+      tokenId: "tok-456",
+      code: "redeemed",
+      status: "success",
+    }, undefined, ledgerPath);
+
+    // Re-opening the same settled operationId replays the durable outcome
+    const replay = openGrokResetCouponOperation({
+      accountId: "acc-123",
+      tokenId: "tok-456",
+      operationId: "op-uuid-1",
+    }, undefined, ledgerPath);
+    expect(replay.kind).toBe("replay");
+    expect(replay.code).toBe("redeemed");
+    expect(replay.settledAt).toBeDefined();
+  });
+
+  it("refreshes token on 401 when integrated with refresh provider stub", async () => {
+    let callCount = 0;
+    let tokenUsed = "";
+
+    const mockFetch: typeof globalThis.fetch = async (input, init) => {
+      callCount++;
+      const headers = new Headers(init?.headers);
+      tokenUsed = headers.get("authorization") || "";
+
+      if (callCount === 1) {
+        return new Response("Unauthorized", { status: 401 });
+      }
+
+      const emptyTrailer = new TextEncoder().encode("grpc-status:0\r\n");
+      const envelope = new Uint8Array(5 + emptyTrailer.length);
+      envelope[0] = 0x80;
+      new DataView(envelope.buffer).setUint32(1, emptyTrailer.length, false);
+      envelope.set(emptyTrailer, 5);
+
+      return new Response(envelope, {
+        status: 200,
+        headers: { "content-type": "application/grpc-web+proto" },
+      });
+    };
+
+    // Retry harness mimicking getValidAccessSnapshotForAccount wrapper
+    let activeToken = "expired-token";
+    const executeWithRetry = async () => {
+      try {
+        return await getGrokRemainingResets({ accessToken: activeToken, fetchFn: mockFetch });
+      } catch (err: any) {
+        if (err.message.includes("401")) {
+          activeToken = "refreshed-fresh-token";
+          return await getGrokRemainingResets({ accessToken: activeToken, fetchFn: mockFetch });
+        }
+        throw err;
+      }
+    };
+
+    const res = await executeWithRetry();
+    expect(res).toEqual({ tokens: [] });
+    expect(callCount).toBe(2);
+    expect(tokenUsed).toBe("Bearer refreshed-fresh-token");
+  });
+});
diff --git a/tests/providers/zcode-client.test.ts b/tests/providers/zcode-client.test.ts
index 92ff210627..3d4047f791 100644
--- a/tests/providers/zcode-client.test.ts
+++ b/tests/providers/zcode-client.test.ts
@@ -43,7 +43,7 @@ describe("ZCode client config", () => {
     expect(Object.keys(document)).toEqual(["provider"]);
     const provider = document.provider[OPENCODE_PROVIDER_ID]!;
     expect(provider.name).toBe("OpenCodex");
-    expect(provider.kind).toBe("openai-compatible");
+    expect(provider.kind).toBe("openai");
     expect(provider.enabled).toBe(true);
     expect(provider.source).toBe("custom");
     expect(provider.options).toEqual({
@@ -53,6 +53,17 @@ describe("ZCode client config", () => {
     });
   });
 
+  test("the exported kind resolves to the proxy's native Responses route", () => {
+    const document = buildClientConfig("zcode", context()) as ZcodeGeneratedConfig;
+    const provider = document.provider[OPENCODE_PROVIDER_ID]!;
+    // ZCode 3.11.2 getDefaultModelProviderEndpointPathForKind sends `openai` to
+    // `/responses` and normalizeModelProviderBaseUrlForKind strips only that suffix,
+    // so the `/v1` root we serialize survives and the turn lands on the route
+    // src/server/index.ts registers as POST /v1/responses.
+    expect(provider.kind).toBe("openai");
+    expect(`${provider.options.baseURL}/responses`).toBe("http://127.0.0.1:10100/v1/responses");
+  });
+
   test("models carry authoritative limits, text-floor modalities, and drop audio-only rows", () => {
     const document = buildClientConfig("zcode", context()) as ZcodeGeneratedConfig;
     const models = document.provider[OPENCODE_PROVIDER_ID]!.models;
diff --git a/tests/responses/chat-conversation-affinity.test.ts b/tests/responses/chat-conversation-affinity.test.ts
new file mode 100644
index 0000000000..97c599b308
--- /dev/null
+++ b/tests/responses/chat-conversation-affinity.test.ts
@@ -0,0 +1,99 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { handleChatCompletions } from "../../src/server/chat-completions";
+import type { OcxConfig } from "../../src/types";
+import { fakeChatGptJwt } from "../helpers/fake-chatgpt-jwt";
+import { installIsolatedCodexHome, type IsolatedCodexHome } from "../helpers/isolated-codex-home";
+import { removeTreeWithRetry } from "../helpers/remove-tree";
+
+// #3433 transport contract only: these client-assigned fixture IDs are not a capture of Hermes.
+const originalFetch = globalThis.fetch;
+const identityHeaders = ["session_id", "session-id", "thread-id", "x-codex-parent-thread-id"];
+let isolated: IsolatedCodexHome;
+let home: string;
+let previousHome: string | undefined;
+
+beforeEach(() => {
+  isolated = installIsolatedCodexHome("ocx-chat-identity-");
+  previousHome = process.env.OPENCODEX_HOME;
+  home = mkdtempSync(join(tmpdir(), "ocx-chat-identity-config-"));
+  process.env.OPENCODEX_HOME = home;
+});
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+  isolated.restore();
+  if (previousHome === undefined) delete process.env.OPENCODEX_HOME;
+  else process.env.OPENCODEX_HOME = previousHome;
+  removeTreeWithRetry(home);
+});
+
+interface Capture { headers: Headers; body: Record<string, unknown> }
+function mockNativeWire(): Capture[] {
+  const seen: Capture[] = [];
+  globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    expect(String(input)).toBe("https://chatgpt.com/backend-api/codex/responses");
+    seen.push({ headers: new Headers(init?.headers), body: JSON.parse(String(init?.body)) });
+    return Response.json({ id: "resp_chat_identity", object: "response", status: "completed",
+      output: [{ type: "message", role: "assistant", content: [{ type: "output_text", text: "ok" }] }],
+      usage: { input_tokens: 10, output_tokens: 1, total_tokens: 11, input_tokens_details: { cached_tokens: 0 } } });
+  }) as typeof fetch;
+  return seen;
+}
+
+async function chat(headers: Record<string, string>, cacheKey: string | undefined, continued: boolean) {
+  const token = fakeChatGptJwt({ chatgpt_account_id: "fixture-chat-caller", exp: Math.floor(Date.now() / 1000) + 86400 });
+  const config = { defaultProvider: "openai", openaiProviderTierVersion: 2, providers: {
+    openai: { adapter: "openai-responses", authMode: "forward", codexAccountMode: "direct",
+      baseUrl: "https://chatgpt.com/backend-api/codex", models: ["gpt-5.6-luna"] },
+  } } as OcxConfig;
+  const messages = [{ role: "system", content: "A shared prefix is not a conversation identity." },
+    { role: "user", content: "first turn" },
+    ...(continued ? [{ role: "assistant", content: "first answer" }, { role: "user", content: "next turn" }] : [])];
+  const req = new Request("http://localhost/v1/chat/completions", { method: "POST",
+    headers: { "content-type": "application/json", authorization: `Bearer ${token}`,
+      "chatgpt-account-id": "fixture-chat-caller", ...headers },
+    body: JSON.stringify({ model: "openai/gpt-5.6-luna", messages, stream: false, reasoning_effort: "medium",
+      ...(cacheKey === undefined ? {} : { prompt_cache_key: cacheKey }) }),
+  });
+  const response = await handleChatCompletions(req, config, { model: "", provider: "" });
+  await response.text();
+  expect(response.status).toBe(200);
+}
+
+describe("Chat conversation identity at canonical Responses outbound boundary", () => {
+  for (const keyPresent of [false, true]) {
+    for (const shape of ["underscore", "hyphen-pair"] as const) {
+      test(`${shape}, key=${keyPresent}: A/A/B retains caller identity and independent request IDs`, async () => {
+        const seen = mockNativeWire();
+        const key = keyPresent ? "shared-cache-cohort" : undefined;
+        for (const [index, conversation] of ["a", "a", "b"].entries()) {
+          const identity: Record<string, string> = shape === "underscore"
+            ? { session_id: `conversation-${conversation}` }
+            : { "session-id": `session-${conversation}`, "thread-id": `thread-${conversation}` };
+          await chat({ ...identity, "x-client-request-id": `request-${index}` }, key, index === 1);
+          expect(seen).toHaveLength(index + 1);
+          const wire = seen[index]!;
+          for (const name of identityHeaders) expect(wire.headers.get(name)).toBe(identity[name] ?? null);
+          expect(wire.headers.get("x-client-request-id")).toBe(`request-${index}`);
+          expect(wire.body.prompt_cache_key).toBe(key);
+          expect(Object.hasOwn(wire.body, "prompt_cache_key")).toBe(keyPresent);
+          expect(wire.body.reasoning).toMatchObject({ effort: "medium" });
+        }
+        expect(JSON.stringify(seen[1]!.body.input).length).toBeGreaterThan(JSON.stringify(seen[0]!.body.input).length);
+        expect(seen[0]!.body.input).toEqual(seen[2]!.body.input);
+      });
+    }
+
+    test(`identity absent, key=${keyPresent}: no session is synthesized`, async () => {
+      const seen = mockNativeWire();
+      for (const continued of [false, true]) await chat({}, keyPresent ? "shared-cache-cohort" : undefined, continued);
+      expect(seen).toHaveLength(2);
+      for (const wire of seen) {
+        for (const name of identityHeaders) expect(wire.headers.has(name)).toBe(false);
+        expect(wire.body.prompt_cache_key).toBe(keyPresent ? "shared-cache-cohort" : undefined);
+      }
+    });
+  }
+});
diff --git a/tests/responses/custom-tool-compat.test.ts b/tests/responses/custom-tool-compat.test.ts
index 530238c499..adfb2105c0 100644
--- a/tests/responses/custom-tool-compat.test.ts
+++ b/tests/responses/custom-tool-compat.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { rewriteRoutedCustomToolsForUpstream } from "../../src/responses/custom-tool-compat";
+import { hasUnmappedRoutedCustomToolOutput, rewriteRoutedCustomToolsForUpstream } from "../../src/responses/custom-tool-compat";
 
 function convertedInputDescription(name: string): string | undefined {
   const result = rewriteRoutedCustomToolsForUpstream({
@@ -14,6 +14,51 @@ function convertedInputDescription(name: string): string | undefined {
 }
 
 describe("routed custom-tool compatibility", () => {
+  test("requires replay for ambiguous delta results without guessing their native or lowered type", () => {
+    const exec = { type: "custom", name: "exec", description: "Run JavaScript" };
+    const patch = { type: "custom", name: "apply_patch", description: "Apply a patch" };
+    const result = { type: "custom_tool_call_output", call_id: "call_sample", output: "done" };
+    const body = { tools: [exec, patch], input: [result] };
+    expect(hasUnmappedRoutedCustomToolOutput(body)).toBe(true);
+    expect(body.input).toEqual([result]);
+    // A native patch result with its known call remains native, even with exec declared.
+    const knownPatch = { ...body, input: [
+      { type: "custom_tool_call", name: "apply_patch", call_id: "call_sample", input: "patch" }, result,
+    ] };
+    expect(hasUnmappedRoutedCustomToolOutput(knownPatch)).toBe(false);
+    expect((rewriteRoutedCustomToolsForUpstream(knownPatch).body as typeof knownPatch).input[1]).toEqual(result);
+    // A complete lowered call/result pair can use the existing lossless conversion.
+    const knownExec = { ...body, input: [
+      { type: "custom_tool_call", name: "exec", call_id: "call_sample", input: "text(1)" }, result,
+    ] };
+    expect(hasUnmappedRoutedCustomToolOutput(knownExec)).toBe(false);
+    expect((rewriteRoutedCustomToolsForUpstream(knownExec).body as typeof knownExec).input[1]!.type).toBe("function_call_output");
+  });
+
+  test("preserves native-only continuations and follows explicit custom-tool lowering", () => {
+    const result = { type: "custom_tool_call_output", call_id: "call_sample", output: "done" };
+    const patchOnly = { tools: [{ type: "custom", name: "apply_patch" }], input: [result] };
+    expect(hasUnmappedRoutedCustomToolOutput(patchOnly)).toBe(false);
+    expect(hasUnmappedRoutedCustomToolOutput(patchOnly, true)).toBe(false);
+    expect(hasUnmappedRoutedCustomToolOutput(patchOnly, false)).toBe(true);
+    expect(hasUnmappedRoutedCustomToolOutput({ input: [result] })).toBe(false);
+    expect(hasUnmappedRoutedCustomToolOutput({
+      tools: [{ type: "custom", name: "exec" }],
+      input: [{ ...result, type: "function_call_output" }],
+    })).toBe(false);
+  });
+
+  test("detects lowered results when the current catalog is nested or supplied by additional_tools", () => {
+    const result = { type: "custom_tool_call_output", call_id: "call_sample", output: "done" };
+    const tool = { type: "custom", name: "exec", description: "Run JavaScript" };
+    expect(hasUnmappedRoutedCustomToolOutput({
+      tools: [{ type: "namespace", name: "functions", tools: [tool] }], input: [result],
+    })).toBe(true);
+    expect(hasUnmappedRoutedCustomToolOutput({
+      input: [{ type: "additional_tools", tools: [tool] }, result],
+    })).toBe(true);
+  });
+
   test.each([
     ["absent", undefined],
     ["true", true],
diff --git a/tests/responses/responses-undeclared-tool-guard.test.ts b/tests/responses/responses-undeclared-tool-guard.test.ts
index 41d8383a6c..6dd680c9d2 100644
--- a/tests/responses/responses-undeclared-tool-guard.test.ts
+++ b/tests/responses/responses-undeclared-tool-guard.test.ts
@@ -7,7 +7,11 @@
 import { describe, expect, test } from "bun:test";
 import {
   collectDeclaredNamelessClientCallTypes,
+  collectDeclaredBareWireToolNames,
   collectDeclaredWireToolNames,
+  normalizeDefaultNamespaceInJson,
+  normalizeDefaultNamespaceInPayload,
+  normalizeDefaultNamespaceInResponse,
   collectProviderExecutedCallTypes,
   createUndeclaredToolCallGuardBlockRewrite,
   currentTurnWireToolCatalogBody,
@@ -63,6 +67,7 @@ async function relay(
   upstream: string,
   declared: Iterable<string>,
   declaredNamelessClientCallTypes: Iterable<string> = [],
+  declaredBare?: Iterable<string>,
 ): Promise<string> {
   const budget = createTestTranslatorBudget();
   try {
@@ -71,6 +76,8 @@ async function relay(
       createUndeclaredToolCallGuardBlockRewrite(
         new Set(declared),
         new Set(declaredNamelessClientCallTypes),
+        undefined,
+        declaredBare ? new Set(declaredBare) : undefined,
       ),
       budget,
     ));
@@ -79,6 +86,33 @@ async function relay(
   }
 }
 
+describe("collectDeclaredBareWireToolNames", () => {
+  test("collects top-level bare tools and functions namespace, ignoring other namespaces and flattened/dotted names", () => {
+    const names = collectDeclaredBareWireToolNames({
+      tools: [
+        { type: "function", name: "view_image" },
+        { type: "custom", name: "exec" },
+        { type: "function", name: "foo__tool" },
+        { type: "function", name: "foo.tool" },
+        { type: "namespace", name: "functions", tools: [{ type: "function", name: "shell" }, { type: "function", name: "bar.baz" }] },
+        { type: "namespace", name: "linear", tools: [{ type: "function", name: "create_issue" }] },
+      ],
+      input: [
+        {
+          type: "additional_tools",
+          tools: [{ type: "function", name: "extra_tool" }, { type: "function", name: "pkg__sub" }],
+        },
+      ],
+    });
+    expect([...names].sort()).toEqual(["exec", "extra_tool", "shell", "view_image"]);
+  });
+
+  test("returns empty set for invalid or missing body", () => {
+    expect(collectDeclaredBareWireToolNames(null).size).toBe(0);
+    expect(collectDeclaredBareWireToolNames({}).size).toBe(0);
+  });
+});
+
 describe("collectDeclaredWireToolNames", () => {
   test("reads function, custom, and namespaced tools off the outbound body", () => {
     const names = collectDeclaredWireToolNames({
@@ -436,6 +470,235 @@ describe("undeclared tool call guard", () => {
     expect(await relay(upstream, ["linear.create_issue"])).toBe(upstream);
   });
 
+  test("accepts and rewrites dotted default.view_image back to bare view_image in SSE added and done items (#4176)", async () => {
+    const outbound = {
+      tools: [{ type: "function", name: "view_image" }],
+    };
+    const declared = collectDeclaredWireToolNames(outbound);
+    const declaredBare = collectDeclaredBareWireToolNames(outbound);
+
+    // output_item.added
+    const upstreamAdded = sse("response.output_item.added", {
+      output_index: 0,
+      item: { type: "function_call", id: "fc_1", call_id: "call_1", name: "default.view_image", arguments: "{}" },
+    });
+    const expectedAdded = sse("response.output_item.added", {
+      output_index: 0,
+      item: { type: "function_call", id: "fc_1", call_id: "call_1", name: "view_image", arguments: "{}" },
+    });
+    expect(await relay(upstreamAdded, declared, [], declaredBare)).toBe(expectedAdded);
+
+    // output_item.done with custom args
+    const upstreamDone = sse("response.output_item.done", {
+      output_index: 0,
+      item: { type: "function_call", id: "fc_1", call_id: "call_1", name: "default.view_image", arguments: JSON.stringify({ path: "/tmp/img.png" }) },
+    });
+    const expectedDone = sse("response.output_item.done", {
+      output_index: 0,
+      item: { type: "function_call", id: "fc_1", call_id: "call_1", name: "view_image", arguments: JSON.stringify({ path: "/tmp/img.png" }) },
+    });
+    expect(await relay(upstreamDone, declared, [], declaredBare)).toBe(expectedDone);
+  });
+
+  test("accepts and rewrites default. prefix in response.function_call_arguments.done SSE event (#4176)", async () => {
+    const outbound = {
+      tools: [{ type: "function", name: "view_image" }],
+    };
+    const declared = collectDeclaredWireToolNames(outbound);
+    const declaredBare = collectDeclaredBareWireToolNames(outbound);
+
+    const upstreamDone = sse("response.function_call_arguments.done", {
+      item_id: "item_1",
+      output_index: 0,
+      call_id: "call_1",
+      name: "default.view_image",
+      arguments: JSON.stringify({ path: "/tmp/img.png" }),
+    });
+    const expectedDone = sse("response.function_call_arguments.done", {
+      item_id: "item_1",
+      output_index: 0,
+      call_id: "call_1",
+      name: "view_image",
+      arguments: JSON.stringify({ path: "/tmp/img.png" }),
+    });
+    expect(await relay(upstreamDone, declared, [], declaredBare)).toBe(expectedDone);
+  });
+
+    test("accepts and rewrites namespace: 'default' with bare name back to bare tool (#4176)", async () => {
+    const outbound = {
+      tools: [{ type: "function", name: "view_image" }],
+    };
+    const declared = collectDeclaredWireToolNames(outbound);
+    const declaredBare = collectDeclaredBareWireToolNames(outbound);
+
+    const upstreamAdded = sse("response.output_item.added", {
+      output_index: 0,
+      item: { type: "function_call", id: "fc_1", call_id: "call_1", namespace: "default", name: "view_image", arguments: JSON.stringify({ detail: "high" }) },
+    });
+    const expectedAdded = sse("response.output_item.added", {
+      output_index: 0,
+      item: { type: "function_call", id: "fc_1", call_id: "call_1", name: "view_image", arguments: JSON.stringify({ detail: "high" }) },
+    });
+    expect(await relay(upstreamAdded, declared, [], declaredBare)).toBe(expectedAdded);
+
+    const upstreamDone = sse("response.output_item.done", {
+      output_index: 0,
+      item: { type: "function_call", id: "fc_1", call_id: "call_1", namespace: "default", name: "view_image", arguments: JSON.stringify({ detail: "high" }) },
+    });
+    const expectedDone = sse("response.output_item.done", {
+      output_index: 0,
+      item: { type: "function_call", id: "fc_1", call_id: "call_1", name: "view_image", arguments: JSON.stringify({ detail: "high" }) },
+    });
+    expect(await relay(upstreamDone, declared, [], declaredBare)).toBe(expectedDone);
+  });
+
+  test("rewrites terminal snapshots (completed/incomplete) in SSE streams (#4176)", async () => {
+    const outbound = {
+      tools: [{ type: "function", name: "view_image" }],
+    };
+    const declared = collectDeclaredWireToolNames(outbound);
+    const declaredBare = collectDeclaredBareWireToolNames(outbound);
+
+    const upstreamCompleted = sse("response.completed", {
+      response: {
+        id: "resp_1",
+        status: "completed",
+        output: [
+          { type: "function_call", id: "fc_1", call_id: "call_1", name: "default.view_image", arguments: "{}" },
+          { type: "function_call", id: "fc_2", call_id: "call_2", namespace: "default", name: "view_image", arguments: "{}" },
+        ],
+      },
+    });
+    const expectedCompleted = sse("response.completed", {
+      response: {
+        id: "resp_1",
+        status: "completed",
+        output: [
+          { type: "function_call", id: "fc_1", call_id: "call_1", name: "view_image", arguments: "{}" },
+          { type: "function_call", id: "fc_2", call_id: "call_2", name: "view_image", arguments: "{}" },
+        ],
+      },
+    });
+    expect(await relay(upstreamCompleted, declared, [], declaredBare)).toBe(expectedCompleted);
+  });
+
+  test("does not rewrite default.view_image to bare when default.view_image is explicitly declared (#4176)", async () => {
+    const outbound = {
+      tools: [{ type: "function", name: "view_image" }, { type: "function", name: "default.view_image" }],
+    };
+    const declared = collectDeclaredWireToolNames(outbound);
+    const declaredBare = collectDeclaredBareWireToolNames(outbound);
+    const upstream = sse("response.output_item.added", {
+      output_index: 0,
+      item: { type: "function_call", id: "fc_1", call_id: "call_1", name: "default.view_image", arguments: "{}" },
+    });
+    expect(await relay(upstream, declared, [], declaredBare)).toBe(upstream);
+  });
+
+  test("preserves namespaced default__view_image over bare normalization (#4176)", async () => {
+    const outbound = {
+      tools: [
+        { type: "function", name: "view_image" },
+        { type: "namespace", name: "default", tools: [{ type: "function", name: "view_image" }] },
+      ],
+    };
+    const declared = collectDeclaredWireToolNames(outbound);
+    const declaredBare = collectDeclaredBareWireToolNames(outbound);
+    const upstream = sse("response.output_item.added", {
+      output_index: 0,
+      item: { type: "function_call", id: "fc_1", call_id: "call_1", name: "default.view_image", arguments: "{}" },
+    });
+    expect(await relay(upstream, declared, [], declaredBare)).toBe(upstream);
+  });
+
+  test("rejects default. prefix when the bare tool was not declared (#4176)", async () => {
+    const outbound = {
+      tools: [{ type: "function", name: "list_dir" }],
+    };
+    const declared = collectDeclaredWireToolNames(outbound);
+    const declaredBare = collectDeclaredBareWireToolNames(outbound);
+    const upstream = sse("response.output_item.added", {
+      output_index: 0,
+      item: { type: "function_call", id: "fc_1", call_id: "call_1", name: "default.view_image", arguments: "{}" },
+    });
+    const out = await relay(upstream, declared, [], declaredBare);
+    expect(out).toContain(UNDECLARED_TOOL_CALL_ERROR_CODE);
+  });
+
+  test("rejects default.view_image and namespace=default when only a different namespaced tool was declared (#4176)", async () => {
+    const outbound = {
+      tools: [
+        { type: "namespace", name: "foo", tools: [{ type: "function", name: "view_image" }] },
+      ],
+    };
+    const declared = collectDeclaredWireToolNames(outbound);
+    const declaredBare = collectDeclaredBareWireToolNames(outbound);
+
+    const upstreamDotted = sse("response.output_item.added", {
+      output_index: 0,
+      item: { type: "function_call", id: "fc_1", call_id: "call_1", name: "default.view_image", arguments: "{}" },
+    });
+    const outDotted = await relay(upstreamDotted, declared, [], declaredBare);
+    expect(outDotted).toContain(UNDECLARED_TOOL_CALL_ERROR_CODE);
+
+    const upstreamNs = sse("response.output_item.added", {
+      output_index: 0,
+      item: { type: "function_call", id: "fc_1", call_id: "call_1", namespace: "default", name: "view_image", arguments: "{}" },
+    });
+    const outNs = await relay(upstreamNs, declared, [], declaredBare);
+    expect(outNs).toContain(UNDECLARED_TOOL_CALL_ERROR_CODE);
+  });
+
+  test("normalizes default namespace in non-streaming JSON responses (#4176)", () => {
+    const outbound = {
+      tools: [{ type: "function", name: "view_image" }],
+    };
+    const declared = collectDeclaredWireToolNames(outbound);
+    const declaredBare = collectDeclaredBareWireToolNames(outbound);
+    const jsonInput = JSON.stringify({
+      id: "resp_1",
+      status: "completed",
+      output: [
+        { type: "function_call", id: "fc_1", call_id: "call_1", name: "default.view_image", arguments: JSON.stringify({ path: "img.png" }) },
+        { type: "function_call", id: "fc_2", call_id: "call_2", namespace: "default", name: "view_image", arguments: "{}" },
+      ],
+    });
+    const normalized = normalizeDefaultNamespaceInJson(jsonInput, declared, declaredBare);
+    const parsed = JSON.parse(normalized);
+    expect(parsed.output[0]).toEqual({
+      type: "function_call",
+      id: "fc_1",
+      call_id: "call_1",
+      name: "view_image",
+      arguments: JSON.stringify({ path: "img.png" }),
+    });
+    expect(parsed.output[1]).toEqual({
+      type: "function_call",
+      id: "fc_2",
+      call_id: "call_2",
+      name: "view_image",
+      arguments: "{}",
+    });
+  });
+
+  test("does not normalize non-streaming JSON when bare tool was not declared (#4176)", () => {
+    const outbound = {
+      tools: [{ type: "namespace", name: "foo", tools: [{ type: "function", name: "view_image" }] }],
+    };
+    const declared = collectDeclaredWireToolNames(outbound);
+    const declaredBare = collectDeclaredBareWireToolNames(outbound);
+    const jsonInput = JSON.stringify({
+      id: "resp_1",
+      status: "completed",
+      output: [
+        { type: "function_call", id: "fc_1", call_id: "call_1", name: "default.view_image", arguments: "{}" },
+      ],
+    });
+    const normalized = normalizeDefaultNamespaceInJson(jsonInput, declared, declaredBare);
+    expect(normalized).toBe(jsonInput);
+    expect(undeclaredToolCallNameInResponse(JSON.parse(normalized), declared, [], undefined, declaredBare)).toBe("default.view_image");
+  });
+
   test("never blocks apply_patch when the request really declared it", async () => {
     // `apply_patch` is exempt from the routed custom-tool rewrite, so it reaches upstream as
     // `{type:"custom"}` and comes back as a `custom_tool_call`. A request that declares it must
@@ -829,6 +1092,202 @@ describe("a refused turn does not become continuation state", () => {
   });
 });
 
+describe("real relay and continuation caller normalization (#4176 / #4181)", () => {
+  const config = {
+    port: 0,
+    defaultProvider: "fixture",
+    providers: {
+      fixture: {
+        adapter: "openai-responses",
+        baseUrl: "https://fixture.test/v1",
+        authMode: "key",
+        apiKey: "fixture-key",
+      },
+    },
+  } as OcxConfig;
+
+  test("Turn 1 stream normalizes default.view_image, and Turn 2 continuation expands normalized replay", async () => {
+    const originalFetch = globalThis.fetch;
+    const capturedOutbound: Array<Record<string, unknown>> = [];
+    let turn = 1;
+
+    globalThis.fetch = (async (_input, init) => {
+      const body = init?.body ? JSON.parse(String(init.body)) as Record<string, unknown> : {};
+      capturedOutbound.push(body);
+
+      if (turn === 2) {
+        return Response.json({
+          id: "resp_turn2",
+          status: "completed",
+          output: [{ type: "message", role: "assistant", content: [{ type: "text", text: "image processed" }] }],
+        });
+      }
+      turn++;
+
+      const toolCall = {
+        type: "function_call",
+        id: "fc_img_1",
+        call_id: "call_img_1",
+        name: "default.view_image",
+        arguments: JSON.stringify({ path: "/tmp/sample.png" }),
+        status: "completed",
+      };
+      const sse = [
+        `data: ${JSON.stringify({ type: "response.created", response: { id: "resp_turn1", status: "in_progress" } })}\n\n`,
+        `data: ${JSON.stringify({ type: "response.output_item.added", output_index: 0, item: { ...toolCall, arguments: "", status: "in_progress" } })}\n\n`,
+        `data: ${JSON.stringify({ type: "response.output_item.done", output_index: 0, item: toolCall })}\n\n`,
+        `data: ${JSON.stringify({ type: "response.completed", response: { id: "resp_turn1", status: "completed", output: [toolCall] } })}\n\n`,
+        "data: [DONE]\n\n",
+      ].join("");
+      return new Response(sse, { headers: { "content-type": "text/event-stream" } });
+    }) as typeof fetch;
+
+    try {
+      // 1. Turn 1 (stream): Client declares bare tool 'view_image'.
+      // Upstream sends SSE stream containing 'default.view_image' with call_id 'call_img_1'.
+      // Client receives normalized 'view_image' with 'call_img_1' and no 'default.view_image'.
+      const turn1Req = new Request("http://localhost/v1/responses", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          model: "fixture/deepseek-v4-flash",
+          stream: true,
+          input: [{ role: "user", content: [{ type: "input_text", text: "inspect this image" }] }],
+          tools: [{ type: "function", name: "view_image", parameters: { type: "object" } }],
+        }),
+      });
+
+      const turn1Res = await handleResponses(turn1Req, config, { model: "", provider: "" });
+      expect(turn1Res.status).toBe(200);
+      const clientStreamText = await turn1Res.text();
+
+      expect(clientStreamText).toContain('"name":"view_image"');
+      expect(clientStreamText).toContain('"call_id":"call_img_1"');
+      expect(clientStreamText).not.toContain("default.view_image");
+      expect(clientStreamText).not.toContain("response.failed");
+
+      // Wait briefly for background stream inspector tee to commit normalized response state
+      await Bun.sleep(50);
+
+      // 2. Turn 2: Client continuation with previous_response_id and function_call_output for 'call_img_1'.
+      // Outbound request to upstream expands the replayed tool call with normalized name 'view_image' and matching 'call_img_1'.
+      const turn2Req = new Request("http://localhost/v1/responses", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          model: "fixture/deepseek-v4-flash",
+          stream: false,
+          previous_response_id: "resp_turn1",
+          input: [
+            {
+              type: "function_call_output",
+              call_id: "call_img_1",
+              output: JSON.stringify({ width: 800, height: 600 }),
+            },
+          ],
+          tools: [{ type: "function", name: "view_image", parameters: { type: "object" } }],
+        }),
+      });
+
+      const turn2Res = await handleResponses(turn2Req, config, { model: "", provider: "" });
+      expect(turn2Res.status).toBe(200);
+      await turn2Res.json();
+
+      expect(capturedOutbound.length).toBe(2);
+      const turn2Outbound = capturedOutbound[1];
+      const replayedToolCall = (turn2Outbound.input as Array<Record<string, unknown>>)?.find(
+        item => item.call_id === "call_img_1",
+      );
+      expect(replayedToolCall).toBeDefined();
+      expect(replayedToolCall).toMatchObject({
+        type: "function_call",
+        id: "fc_img_1",
+        call_id: "call_img_1",
+        name: "view_image",
+      });
+      expect(JSON.stringify(turn2Outbound)).not.toContain("default.view_image");
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  test("negative control: request declaring only 'foo__view_image', upstream returning 'default.view_image' is rejected with 502", async () => {
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = (async () => Response.json({
+      id: "resp_foo",
+      status: "completed",
+      output: [{
+        type: "function_call",
+        id: "fc_img_bad",
+        call_id: "call_img_bad",
+        name: "default.view_image",
+        arguments: "{}",
+        status: "completed",
+      }],
+    })) as typeof fetch;
+
+    try {
+      const response = await handleResponses(new Request("http://localhost/v1/responses", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          model: "fixture/deepseek-v4-flash",
+          stream: false,
+          input: [{ role: "user", content: [{ type: "input_text", text: "inspect" }] }],
+          tools: [{ type: "function", name: "foo__view_image", parameters: { type: "object" } }],
+        }),
+      }), config, { model: "", provider: "" });
+
+      expect(response.status).toBe(502);
+      const body = await response.json() as { error: { message: string } };
+      expect(body.error.message).toContain('undeclared client tool "default.view_image"');
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  test("negative control: request explicitly declaring 'default.view_image' preserves 'default.view_image'", async () => {
+    const originalFetch = globalThis.fetch;
+    const toolCall = {
+      type: "function_call",
+      id: "fc_img_explicit",
+      call_id: "call_img_explicit",
+      name: "default.view_image",
+      arguments: JSON.stringify({ path: "/tmp/explicit.png" }),
+      status: "completed",
+    };
+
+    globalThis.fetch = (async () => Response.json({
+      id: "resp_explicit",
+      status: "completed",
+      output: [toolCall],
+    })) as typeof fetch;
+
+    try {
+      const response = await handleResponses(new Request("http://localhost/v1/responses", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          model: "fixture/deepseek-v4-flash",
+          stream: false,
+          input: [{ role: "user", content: [{ type: "input_text", text: "inspect" }] }],
+          tools: [{ type: "function", name: "default.view_image", parameters: { type: "object" } }],
+        }),
+      }), config, { model: "", provider: "" });
+
+      expect(response.status).toBe(200);
+      const body = await response.json() as { output: Array<Record<string, unknown>> };
+      expect(body.output[0]).toMatchObject({
+        type: "function_call",
+        name: "default.view_image",
+        call_id: "call_img_explicit",
+      });
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
+
 describe("empty and absent tool catalogs", () => {
   const config = {
     port: 0,
diff --git a/tests/responses/ws-failure-stage.test.ts b/tests/responses/ws-failure-stage.test.ts
index af4db2136a..04c12c6357 100644
--- a/tests/responses/ws-failure-stage.test.ts
+++ b/tests/responses/ws-failure-stage.test.ts
@@ -86,6 +86,8 @@ function stage(overrides: Partial<CodexWsFailureStage> = {}): CodexWsFailureStag
     relayedEvents: 0,
     firstFrameMs: null,
     elapsedMs: 90_003,
+    pings: 0,
+    pongs: 0,
     ...overrides,
   };
 }
@@ -98,6 +100,20 @@ async function failureMessage(script: (ws: FakeWebSocket) => void): Promise<stri
     noFallback as unknown as typeof fetch,
     BOUNDED_WS_RUNTIME,
   );
+  return failureMessageOf(response);
+}
+
+/**
+ * A failure before the first response event is an honest gateway status whose JSON body
+ * carries the message; a failure after the response started is still an errored 200 body.
+ * Both shapes carry the same stage detail, which is what these cases read.
+ */
+async function failureMessageOf(response: Response): Promise<string> {
+  if (response.status >= 500) {
+    const body = await response.json() as { error?: { message?: unknown } };
+    if (typeof body.error?.message !== "string") throw new Error("expected a gateway failure body");
+    return body.error.message;
+  }
   try {
     await response.text();
   } catch (error) {
@@ -136,12 +152,14 @@ describe("codex WS failure classification", () => {
   test("renders every field, with n/a for the durations that do not exist yet", () => {
     expect(codexWsFailureDetail(stage({ upstreamFrames: 2, controlFrames: 2, firstFrameMs: 41 }))).toBe(
       " [cause=no-response-event request=812B sent=yes frames=2 control=2 relayed=0"
-      + " first-frame=41ms elapsed=90003ms]",
+      + " first-frame=41ms elapsed=90003ms pings=0 pongs=0]",
     );
     expect(codexWsFailureDetail(stage({ sent: false, elapsedMs: null }))).toBe(
       " [cause=before-send request=812B sent=no frames=0 control=0 relayed=0"
-      + " first-frame=n/a elapsed=n/a]",
+      + " first-frame=n/a elapsed=n/a pings=0 pongs=0]",
     );
+    // A peer that answered pings but never started a response is named as such.
+    expect(codexWsFailureDetail(stage({ upstreamFrames: 0, pings: 6, pongs: 6 }))).toContain(" pings=6 pongs=6]");
   });
 });
 
@@ -219,7 +237,8 @@ describe("codexWsUpstreamFetch failure reporting", () => {
       await opened.promise;
       jest.advanceTimersByTime(CODEX_WS_RESPONSE_PRELUDE_TIMEOUT_MS);
       const response = await pending;
-      await expect(response.text()).rejects.toThrow(
+      expect(response.status).toBe(504);
+      expect(await failureMessageOf(response)).toMatch(
         /prelude timed out \[cause=no-upstream-frame request=\d+B sent=yes frames=0 control=0 relayed=0/,
       );
     } finally {
@@ -227,4 +246,3 @@ describe("codexWsUpstreamFetch failure reporting", () => {
     }
   });
 });
-
diff --git a/tests/responses/ws-upstream.test.ts b/tests/responses/ws-upstream.test.ts
index 9e4f689208..80c6291780 100644
--- a/tests/responses/ws-upstream.test.ts
+++ b/tests/responses/ws-upstream.test.ts
@@ -3,7 +3,7 @@ import { providerFetch } from "../../src/server/responses/fetch-helpers";
 import { handleResponses } from "../../src/server/responses";
 import { isEagerRelaySseResponse } from "../../src/server/relay";
 import { isWin32EagerRewrite } from "../../src/lib/bun-stream-caps";
-import { fetchWithTransientRetry } from "../../src/lib/upstream-retry";
+import { fetchWithTransientRetry, isNonReplayableResponse } from "../../src/lib/upstream-retry";
 import { codexWsExchange } from "../../src/server/responses/codex-ws-exchange";
 import { CodexWsSession } from "../../src/server/responses/codex-ws-session";
 import { prepareCodexWsRequest } from "../../src/server/responses/codex-ws-request";
@@ -20,6 +20,7 @@ import {
   MAX_CODEX_WS_FRAME_BYTES,
   MAX_CODEX_WS_QUEUE_BYTES,
   CODEX_WS_RESPONSE_PRELUDE_TIMEOUT_MS,
+  CODEX_WS_LIVENESS_PING_INTERVAL_MS,
   shouldUseCodexWsUpstream as rawShouldUseCodexWsUpstream,
 } from "../../src/server/responses/ws-upstream";
 import type { OcxProviderConfig } from "../../src/types";
@@ -798,9 +799,14 @@ describe("codexWsUpstreamFetch", () => {
         for (const [name, value] of Object.entries(headers)) expect(response.headers.get(name)).toBe(value);
         expect(await response.json()).toEqual({ error: refusal.error });
       } else {
-        expect(response.status).toBe(200);
-        expect(isCodexWsUpstreamResponse(response)).toBe(true);
-        await expect(response.text()).rejects.toThrow("metadata");
+        // The overflow lands before any response event: an honest 502, never a 200 whose
+        // body then fails, and never the HTTP fallback (the frame was sent).
+        expect(response.status).toBe(502);
+        expect(isCodexWsUpstreamResponse(response)).toBe(false);
+        expect(response.headers.get("content-type")).toBe("application/json");
+        const failure = ((await response.json()) as { error: { code: string; message: string } }).error;
+        expect(failure.code).toBe("upstream_closed_before_response");
+        expect(failure.message).toContain("metadata");
       }
     });
 
@@ -808,8 +814,8 @@ describe("codexWsUpstreamFetch", () => {
       const response = await receive({ ...refusal, headers: boundedHeaders(5, "x".repeat(4096)) }, [
         { type: "codex.response.metadata", headers: boundedHeaders(4, "y".repeat(4096)) },
       ]);
-      expect(response.status).toBe(200);
-      await expect(response.text()).rejects.toThrow("metadata");
+      expect(response.status).toBe(502);
+      expect(((await response.json()) as { error: { message: string } }).error.message).toContain("metadata");
     });
 
     test.each([
@@ -896,8 +902,11 @@ describe("codexWsUpstreamFetch", () => {
         expect(session.reserve()).toBe(true);
         const response = await codexWsExchange(options);
         if (foreign) {
-          expect(response.status).toBe(200);
-          await expect(response.text()).rejects.toThrow("identity mismatch");
+          // A foreign stream before any response event is a transport that misbehaved after
+          // the send: non-replayable 502, and never the 4xx refusal projection.
+          expect(response.status).toBe(502);
+          expect(isCodexWsUpstreamResponse(response)).toBe(false);
+          expect(((await response.json()) as { error: { message: string } }).error.message).toContain("identity mismatch");
         } else {
           expect(response.status).toBe(429);
           expect(isCodexWsUpstreamResponse(response)).toBe(false);
@@ -1070,7 +1079,10 @@ describe("codexWsUpstreamFetch", () => {
       throw new Error("fallback must not run after open");
     }) as unknown as typeof fetch);
 
-    await expect(response.text()).rejects.toThrow("frame exceeds the response size limit");
+    // No response event preceded the oversized frame, so the exchange never owed a stream.
+    expect(response.status).toBe(502);
+    expect(((await response.json()) as { error: { message: string } }).error.message)
+      .toContain("frame exceeds the response size limit");
     expect(FakeWebSocket.instances[0].closed).toBe(true);
   });
 
@@ -1189,9 +1201,9 @@ describe("codexWsUpstreamFetch", () => {
 
     await opened.promise;
     controller.abort(new Error("turn cancelled"));
-    const response = await pending;
-
-    await expect(response.text()).rejects.toThrow("turn cancelled");
+    // Sent and unacknowledged: the caller's abort is the caller's decision, so the fetch
+    // itself rejects with that reason and closing the socket cancels the upstream turn.
+    await expect(pending).rejects.toThrow("turn cancelled");
     expect(FakeWebSocket.instances[0].closed).toBe(true);
   });
 
@@ -1215,7 +1227,7 @@ describe("codexWsUpstreamFetch", () => {
     await response.text();
   });
 
-  test("post-send prelude overflow settles as an errored body without HTTP fallback", async () => {
+  test("post-send prelude overflow settles as a non-replayable 502 without HTTP fallback", async () => {
     installFake(ws => {
       ws.emit("open", {});
       ws.emit("message", { data: JSON.stringify({ type: "codex.response.metadata", headers: { "x-models-etag": "x".repeat(CODEX_WS_METADATA_MAX_BYTES) } }) });
@@ -1225,9 +1237,10 @@ describe("codexWsUpstreamFetch", () => {
       resends++;
       return new Response("unexpected resend");
     }) as typeof fetch);
-    expect(response.status).toBe(200);
-    expect(isCodexWsUpstreamResponse(response)).toBe(true);
-    await expect(response.text()).rejects.toThrow("metadata");
+    expect(response.status).toBe(502);
+    expect(isCodexWsUpstreamResponse(response)).toBe(false);
+    expect(isNonReplayableResponse(response)).toBe(true);
+    expect(((await response.json()) as { error: { message: string } }).error.message).toContain("metadata");
     expect(resends).toBe(0);
     expect(FakeWebSocket.instances[0].sent).toHaveLength(1);
   });
@@ -1259,7 +1272,7 @@ describe("codexWsUpstreamFetch", () => {
     }
   });
 
-  test("the first-response deadline settles a sent request through the outer retry wrapper without resending", async () => {
+  test("the first-response deadline settles a sent request as a 504 the outer retry wrapper does not resend", async () => {
     const { fetchWithTransientRetry } = await import("../../src/lib/upstream-retry");
     jest.useFakeTimers();
     const opened = Promise.withResolvers<void>();
@@ -1277,8 +1290,14 @@ describe("codexWsUpstreamFetch", () => {
       await opened.promise;
       jest.advanceTimersByTime(CODEX_WS_RESPONSE_PRELUDE_TIMEOUT_MS);
       const response = await pending;
-      expect(response.status).toBe(200);
-      await expect(response.text()).rejects.toThrow("prelude timed out");
+      // 504 is a transient status for the wrapper; the non-replayable marker is what stops
+      // the second send, and the status is what lets the client apply its own policy.
+      expect(response.status).toBe(504);
+      expect(isNonReplayableResponse(response)).toBe(true);
+      const failure = ((await response.json()) as { error: { code: string; message: string } }).error;
+      expect(failure.code).toBe("upstream_no_response");
+      expect(failure.message).toContain("prelude timed out");
+      expect(failure.message).toContain("cause=no-upstream-frame");
       expect(sends).toBe(1);
       expect(http).toBe(0);
     } finally {
@@ -1286,6 +1305,109 @@ describe("codexWsUpstreamFetch", () => {
     }
   });
 
+  describe("prelude liveness", () => {
+    // The 90 s bound is a silence bound, not a deadline: a peer that answers pings is alive,
+    // and how long an alive origin may take before response.created belongs to the client's
+    // own deadline and the operator's connectTimeoutMs, not to a fixed number in the proxy.
+    const noResend = (counter: { http: number }) => (async () => {
+      counter.http++;
+      return new Response("must not resend");
+    }) as typeof fetch;
+
+    test("a peer that answers pings stays alive past the silence bound and still completes with one send", async () => {
+      jest.useFakeTimers();
+      const opened = Promise.withResolvers<void>();
+      let pingsSent = 0;
+      installFake(ws => {
+        Object.assign(ws, { ping: () => { pingsSent++; ws.emit("pong", {}); } });
+        ws.emit("open", {});
+        opened.resolve();
+      });
+      const counter = { http: 0 };
+      try {
+        const pending = codexWsUpstreamFetch(CODEX_URL, streamingInit(), noResend(counter));
+        await opened.promise;
+        const ws = FakeWebSocket.instances[0];
+        // Seven steps: 105 s of no message frames, well past the 90 s bound, every step ponged.
+        for (let step = 0; step < 7; step++) jest.advanceTimersByTime(CODEX_WS_LIVENESS_PING_INTERVAL_MS);
+        expect(pingsSent).toBe(7);
+        ws.emit("message", { data: JSON.stringify({ type: "response.created", response: { id: "r1" } }) });
+        ws.emit("message", { data: JSON.stringify({ type: "response.completed", response: { id: "r1" } }) });
+        const response = await pending;
+        expect(response.status).toBe(200);
+        expect(await response.text()).toContain("event: response.completed");
+        expect(ws.sent).toHaveLength(1);
+        expect(counter.http).toBe(0);
+        // The pinger stops once the response has started.
+        jest.advanceTimersByTime(CODEX_WS_LIVENESS_PING_INTERVAL_MS * 4);
+        expect(pingsSent).toBe(7);
+        expect([...ws.listeners.values()].every(listeners => listeners.length === 0)).toBe(true);
+      } finally {
+        jest.useRealTimers();
+      }
+    });
+
+    test("a peer that never pongs keeps the previous 90 s bound and names the unanswered pings", async () => {
+      jest.useFakeTimers();
+      const opened = Promise.withResolvers<void>();
+      let pingsSent = 0;
+      installFake(ws => {
+        Object.assign(ws, { ping: () => { pingsSent++; } });
+        ws.emit("open", {});
+        opened.resolve();
+      });
+      const counter = { http: 0 };
+      try {
+        const pending = codexWsUpstreamFetch(CODEX_URL, streamingInit(), noResend(counter));
+        await opened.promise;
+        // Step the clock so each chained ping timer is scheduled and fired in turn.
+        for (let elapsed = 0; elapsed < CODEX_WS_RESPONSE_PRELUDE_TIMEOUT_MS; elapsed += CODEX_WS_LIVENESS_PING_INTERVAL_MS) {
+          jest.advanceTimersByTime(CODEX_WS_LIVENESS_PING_INTERVAL_MS);
+        }
+        const response = await pending;
+        expect(response.status).toBe(504);
+        const failure = ((await response.json()) as { error: { code: string; message: string } }).error;
+        expect(failure.code).toBe("upstream_no_response");
+        expect(failure.message).toContain("prelude timed out");
+        expect(failure.message).toMatch(/pings=[56] pongs=0\]/);
+        expect(pingsSent).toBeGreaterThanOrEqual(5);
+        expect(FakeWebSocket.instances[0].sent).toHaveLength(1);
+        expect(counter.http).toBe(0);
+        expect(FakeWebSocket.instances[0].closed).toBe(true);
+      } finally {
+        jest.useRealTimers();
+      }
+    });
+
+    test("a control frame is proof of life too: quota keeps the exchange waiting", async () => {
+      jest.useFakeTimers();
+      const opened = Promise.withResolvers<void>();
+      installFake(ws => { ws.emit("open", {}); opened.resolve(); });
+      const counter = { http: 0 };
+      try {
+        const pending = codexWsUpstreamFetch(CODEX_URL, streamingInit(), noResend(counter));
+        await opened.promise;
+        const ws = FakeWebSocket.instances[0];
+        // No ping() on this socket. Quota at 60 s and 120 s resets the silence clock each time.
+        jest.advanceTimersByTime(60_000);
+        ws.emit("message", { data: JSON.stringify({ type: "codex.rate_limits", rate_limits: { primary: { used_percent: 10, window_minutes: 10080 } } }) });
+        jest.advanceTimersByTime(60_000);
+        ws.emit("message", { data: JSON.stringify({ type: "codex.rate_limits", rate_limits: { primary: { used_percent: 11, window_minutes: 10080 } } }) });
+        jest.advanceTimersByTime(60_000);
+        ws.emit("message", { data: JSON.stringify({ type: "response.created", response: { id: "r1" } }) });
+        ws.emit("message", { data: JSON.stringify({ type: "response.completed", response: { id: "r1" } }) });
+        const response = await pending;
+        expect(response.status).toBe(200);
+        expect(response.headers.get("x-codex-primary-used-percent")).toBe("11");
+        expect(await response.text()).toContain("event: response.completed");
+        expect(ws.sent).toHaveLength(1);
+        expect(counter.http).toBe(0);
+      } finally {
+        jest.useRealTimers();
+      }
+    });
+  });
+
   test("malformed native WS metadata still normalizes the real HTTP fallback routing hint", async () => {
     let fallbackInit: RequestInit | undefined;
     const body = JSON.stringify({ model: "gpt-6-astra", service_tier: "priority", stream: true, client_metadata: [] });
@@ -1539,7 +1661,8 @@ describe("oversized Codex create frames", () => {
       throw new Error("fallback must not run after open");
     }) as unknown as typeof fetch);
 
-    await expect(response.text()).rejects.toThrow(
+    expect(response.status).toBe(502);
+    expect(((await response.json()) as { error: { message: string } }).error.message).toMatch(
       /rejected the request frame as too large \(close 1009 Message Too Big\)/,
     );
   });
@@ -1553,7 +1676,10 @@ describe("oversized Codex create frames", () => {
       throw new Error("fallback must not run after open");
     }) as unknown as typeof fetch);
 
-    await expect(response.text()).rejects.toThrow("closed before a Responses terminal event (close 1006)");
+    expect(response.status).toBe(502);
+    const failure = ((await response.json()) as { error: { code: string; message: string } }).error;
+    expect(failure.code).toBe("upstream_closed_before_response");
+    expect(failure.message).toContain("closed before a Responses terminal event (close 1006)");
   });
 
   test("dials the configured provider's own wss URL for an opt-in upstream", async () => {
diff --git a/tests/routing/fastwire-policy.test.ts b/tests/routing/fastwire-policy.test.ts
index e9918dc6ce..36b64f6fb9 100644
--- a/tests/routing/fastwire-policy.test.ts
+++ b/tests/routing/fastwire-policy.test.ts
@@ -320,7 +320,7 @@ describe("resolveFastPolicy matrix", () => {
       {
         name: "DeepSeek V4 defaults",
         providerName: "deepseek",
-        modelIds: ["deepseek-v4-flash", "deepseek-v4-pro"],
+        modelIds: ["deepseek-flash", "deepseek-v4-flash"],
         provider: {
           adapter: "openai-chat",
           baseUrl: "https://api.deepseek.com",
diff --git a/tests/routing/router-combo-failover-classification.test.ts b/tests/routing/router-combo-failover-classification.test.ts
index 742f411bfb..93b58170a6 100644
--- a/tests/routing/router-combo-failover-classification.test.ts
+++ b/tests/routing/router-combo-failover-classification.test.ts
@@ -129,6 +129,16 @@ describe("combo failure hop/stop verdicts", () => {
   test("INVARIANT: a structured model lifecycle 410 still hops", () => {
     expect(comboFailureDecision(410, "model retired", { code: "model_end_of_life" })).toBe("hop");
   });
+
+  test("a post-send gateway status from the Codex WebSocket relay never hops", () => {
+    // The relay sent the create frame and the origin never acknowledged it (504) or the
+    // transport closed first (502). The turn may still be executing at the first target, so
+    // a second target must not receive the same request; the client decides the retry.
+    expect(comboFailureDecision(504, "Provider error 504", { code: "upstream_no_response" })).toBe("stop");
+    expect(comboFailureDecision(502, "Provider error 502", { code: "upstream_closed_before_response" })).toBe("stop");
+    // The same statuses without the structured code keep the ordinary transient hop.
+    expect(comboFailureDecision(504, "Provider error 504")).toBe("hop");
+  });
 });
 
 describe("cooled targets are not selectable", () => {
diff --git a/tests/routing/router.test.ts b/tests/routing/router.test.ts
index 83be39818e..9b6eb68d4d 100644
--- a/tests/routing/router.test.ts
+++ b/tests/routing/router.test.ts
@@ -447,7 +447,7 @@ describe("routeModel registry effort defaults", () => {
     const route = routeModel(config, "deepseek/deepseek-v4-flash");
 
     expect(route.provider.noVisionModels).toEqual([
-      "deepseek-chat", "deepseek-reasoner", "deepseek-v4-pro", "deepseek-v4-flash",
+      "deepseek-chat", "deepseek-reasoner", "deepseek-flash", "deepseek-v4-flash",
     ]);
   });
 
diff --git a/tests/server/account-pool-management-api.test.ts b/tests/server/account-pool-management-api.test.ts
index e8eed3c05d..feec9a8151 100644
--- a/tests/server/account-pool-management-api.test.ts
+++ b/tests/server/account-pool-management-api.test.ts
@@ -4,7 +4,7 @@ import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { handleCodexAuthAPI } from "../../src/codex/auth-api";
-import { saveConfig } from "../../src/config";
+import { loadConfig, saveConfig } from "../../src/config";
 import { startServer } from "../../src/server";
 import type { OcxConfig } from "../../src/types";
 import { installIsolatedCodexHome, type IsolatedCodexHome } from "../helpers/isolated-codex-home";
@@ -439,7 +439,13 @@ describe("Anthropic account pool strategy management API", () => {
     // reading `inert` as covering `enabled` would render a live control as decorative.
     const source = await Bun.file("src/oauth/pool-settings-capability.ts").text();
     const start = source.indexOf("autoSwitchThreshold: number | null;");
-    const marker = source.slice(start, source.indexOf("inert: true;", start));
+    // Anchored on the CURRENT literal. When this type read `inert: true;` and the field became
+    // `inert: boolean;`, indexOf returned -1 and slice(start, -1) handed back almost the whole
+    // file -- which still contains all three words, so every assertion below passed while the
+    // test had stopped checking anything. Fail closed on a missing anchor instead.
+    const end = source.indexOf("inert: boolean;", start);
+    expect(end).toBeGreaterThan(start);
+    const marker = source.slice(start, end);
     expect(marker).toContain("strategy");
     expect(marker).toContain("autoSwitchThreshold");
     expect(marker).toContain("enabled");
@@ -474,7 +480,10 @@ describe("generic OAuth pool-settings contract (#695)", () => {
     try {
       const absent = await fetch(new URL("/api/oauth/accounts/pool?provider=google-antigravity", server.url));
       expect(absent.status).toBe(200);
-      expect(await absent.json()).toEqual({ provider: "google-antigravity", kind: "generic", enabled: null, strategy: null, autoSwitchThreshold: null, inert: true });
+      expect(await absent.json()).toEqual({
+        provider: "google-antigravity", kind: "generic", enabled: null, strategy: null,
+        autoSwitchThreshold: null, stickyLimit: null, inert: true,
+      });
 
       const put = await fetch(new URL("/api/oauth/accounts/pool", server.url), {
         method: "PUT", headers: { "Content-Type": "application/json" },
@@ -488,7 +497,8 @@ describe("generic OAuth pool-settings contract (#695)", () => {
       for (const body of [
         { provider: "google-antigravity", strategy: "weighted" },
         { provider: "google-antigravity", autoSwitchThreshold: 101 },
-        { provider: "google-antigravity", stickyLimit: 3 },
+        { provider: "google-antigravity", stickyLimit: 0 },
+        { provider: "google-antigravity", quotaWindow: "weekly" },
         { provider: "deepseek", strategy: "quota" },
       ]) {
         const bad = await fetch(new URL("/api/oauth/accounts/pool", server.url), {
@@ -509,3 +519,258 @@ describe("generic OAuth pool-settings contract (#695)", () => {
     }
   });
 });
+
+describe("legacy pool contract goldens (#wp5)", () => {
+  /**
+   * Exact-body pins for the three pool contracts, written BEFORE anything is shared between
+   * them. The existing coverage could not serve as the compatibility net it was assumed to be:
+   * the Codex and Anthropic assertions use toMatchObject, which passes when extra keys appear,
+   * and PUT /api/codex-auth/auto-switch checked only the status code. A refactor guarded by
+   * those would not have noticed the regression it was supposed to catch.
+   *
+   * GET /api/codex-auth/active is deliberately absent: it already carries a full toEqual in
+   * tests/codex-integration/codex-auth-api.test.ts.
+   */
+  test("PUT /api/codex-auth/auto-switch answers exactly { ok: true }", async () => {
+    const req = new Request("http://localhost/api/codex-auth/auto-switch", {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ threshold: 70 }),
+    });
+    const resp = await handleCodexAuthAPI(req, new URL(req.url), makeCodexConfig());
+    expect(resp!.status).toBe(200);
+    expect(await resp!.json()).toEqual({ ok: true });
+  });
+
+  test("PUT /api/codex-auth/pool-strategy answers exactly its three keys", async () => {
+    const req = new Request("http://localhost/api/codex-auth/pool-strategy", {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ strategy: "round-robin", stickyLimit: 5 }),
+    });
+    const resp = await handleCodexAuthAPI(req, new URL(req.url), makeCodexConfig());
+    expect(resp!.status).toBe(200);
+    expect(await resp!.json()).toEqual({
+      ok: true,
+      accountPoolStrategy: "round-robin",
+      accountPoolStickyLimit: 5,
+    });
+  });
+
+  test("GET /api/oauth/accounts/pool answers exactly the anthropic shape", async () => {
+    const server = startServer(0);
+    try {
+      const res = await fetch(new URL("/api/oauth/accounts/pool?provider=anthropic", server.url));
+      expect(res.status).toBe(200);
+      expect(await res.json()).toEqual({
+        provider: "anthropic",
+        enabled: false,
+        autoSwitchThreshold: 80,
+        strategy: "quota",
+        stickyLimit: 1,
+        quotaWindow: "five-hour",
+        experimental: true,
+      });
+    } finally {
+      await server.stop(true);
+    }
+  });
+
+  test("PUT /api/oauth/accounts/pool answers exactly the anthropic shape", async () => {
+    const server = startServer(0);
+    try {
+      const res = await fetch(new URL("/api/oauth/accounts/pool", server.url), {
+        method: "PUT",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          provider: "anthropic", enabled: true, autoSwitchThreshold: 70,
+          strategy: "round-robin", stickyLimit: 4,
+        }),
+      });
+      expect(res.status).toBe(200);
+      expect(await res.json()).toEqual({
+        ok: true,
+        provider: "anthropic",
+        enabled: true,
+        autoSwitchThreshold: 70,
+        strategy: "round-robin",
+        stickyLimit: 4,
+        quotaWindow: "five-hour",
+        experimental: true,
+      });
+    } finally {
+      await server.stop(true);
+    }
+  });
+
+  test("a bad strategy and a bad stickyLimit are rejected identically on every kind", async () => {
+    // One validator, three adapters. The kinds keep their own request and response shapes --
+    // that is what the goldens above pin -- but the VALUE rules are now a single implementation,
+    // so "quota, round-robin, fill-first" and the 1..100 sticky bound cannot drift apart per
+    // kind. Before this, the generic kind carried a private copy of both.
+    const codex = async (payload: Record<string, unknown>) => {
+      const req = new Request("http://localhost/api/codex-auth/pool-strategy", {
+        method: "PUT", headers: { "Content-Type": "application/json" }, body: JSON.stringify(payload),
+      });
+      const resp = await handleCodexAuthAPI(req, new URL(req.url), makeCodexConfig());
+      return resp!.status;
+    };
+    const server = startServer(0);
+    try {
+      const oauth = async (payload: Record<string, unknown>) => {
+        const res = await fetch(new URL("/api/oauth/accounts/pool", server.url), {
+          method: "PUT", headers: { "content-type": "application/json" }, body: JSON.stringify(payload),
+        });
+        return res.status;
+      };
+      for (const strategy of ["weighted", "", 3, null]) {
+        expect(await codex({ strategy })).toBe(400);
+        expect(await oauth({ provider: "anthropic", strategy })).toBe(400);
+        expect(await oauth({ provider: "google-antigravity", strategy })).toBe(400);
+      }
+      // 0 and 101 sit just outside the shared bound; 1 and 100 are the edges that must pass.
+      for (const stickyLimit of [0, 101, 1.5]) {
+        expect(await codex({ stickyLimit })).toBe(400);
+        expect(await oauth({ provider: "anthropic", stickyLimit })).toBe(400);
+        expect(await oauth({ provider: "google-antigravity", stickyLimit })).toBe(400);
+      }
+      for (const stickyLimit of [1, 100]) {
+        expect(await codex({ stickyLimit })).toBe(200);
+      }
+    } finally {
+      await server.stop(true);
+    }
+  });
+
+});
+
+describe("unified pool-settings contract (#695 wp5c)", () => {
+  let previousHome2: string | undefined;
+  let dir = "";
+  beforeEach(() => {
+    previousHome2 = process.env.OPENCODEX_HOME;
+    dir = mkdtempSync(join(tmpdir(), "ocx-pool-unified-"));
+    process.env.OPENCODEX_HOME = dir;
+    saveConfig({
+      port: 0,
+      hostname: "127.0.0.1",
+      defaultProvider: "google-antigravity",
+      providers: {
+        "google-antigravity": { adapter: "google", baseUrl: "https://daily-cloudcode-pa.googleapis.com", authMode: "oauth" },
+        deepseek: { adapter: "openai-chat", baseUrl: "https://api.deepseek.com/v1", apiKey: "deepseek-key-fixture" },
+      },
+    } as OcxConfig);
+  });
+  afterEach(() => {
+    if (previousHome2 === undefined) delete process.env.OPENCODEX_HOME;
+    else process.env.OPENCODEX_HOME = previousHome2;
+    if (dir) removeTreeWithRetry(dir);
+  });
+
+  test("every kind answers with the same keys and declares what it supports", async () => {
+    const server = startServer(0);
+    try {
+      for (const [provider, kind, supported] of [
+        ["openai", "codex", ["strategy", "stickyLimit", "autoSwitchThreshold"]],
+        ["anthropic", "anthropic", ["enabled", "strategy", "stickyLimit", "autoSwitchThreshold", "quotaWindow"]],
+        ["google-antigravity", "generic", ["enabled", "strategy", "stickyLimit", "autoSwitchThreshold"]],
+      ] as const) {
+        const res = await fetch(new URL(`/api/pool/settings?provider=${provider}`, server.url));
+        expect(res.status).toBe(200);
+        const dto = await res.json() as Record<string, unknown>;
+        // Same key set for every kind. An unsupported field is a declared null, not an absence,
+        // which is the whole difference between a consolidation and a fourth contract.
+        expect(Object.keys(dto).sort()).toEqual([
+          "autoSwitchThreshold", "enabled", "enabledEffective", "kind", "provider",
+          "quotaWindow", "stickyLimit", "strategy", "supported",
+        ]);
+        expect(dto.kind).toBe(kind);
+        expect(dto.supported).toEqual([...supported]);
+        // quotaWindow belongs to anthropic alone; the others state null rather than omitting it.
+        if (kind !== "anthropic") expect(dto.quotaWindow).toBeNull();
+      }
+      // An API-key provider has no pool at all and is refused rather than answered with nulls.
+      expect((await fetch(new URL("/api/pool/settings?provider=deepseek", server.url))).status).toBe(400);
+    } finally {
+      await server.stop(true);
+    }
+  });
+
+  test("a generic pool with no stored override reports the inherited global", async () => {
+    const config = loadConfig();
+    config.oauthAccountFailover = { enabled: true };
+    saveConfig(config);
+    const server = startServer(0);
+    try {
+      const dto = await (await fetch(new URL("/api/pool/settings?provider=google-antigravity", server.url))).json() as Record<string, unknown>;
+      // The defect this field closes: `enabled: null` means "nothing stored here", which alone
+      // cannot distinguish a disabled pool from one inheriting a global true.
+      expect(dto.enabled).toBeNull();
+      expect(dto.enabledEffective).toBe(true);
+    } finally {
+      await server.stop(true);
+    }
+  });
+
+  test("a global false leaves an unset generic pool effectively off", async () => {
+    const config = loadConfig();
+    config.oauthAccountFailover = { enabled: false };
+    saveConfig(config);
+    const server = startServer(0);
+    try {
+      const dto = await (await fetch(new URL("/api/pool/settings?provider=google-antigravity", server.url))).json() as Record<string, unknown>;
+      expect(dto.enabled).toBeNull();
+      expect(dto.enabledEffective).toBe(false);
+    } finally {
+      await server.stop(true);
+    }
+  });
+
+  test("a stored provider override beats the global in both directions", async () => {
+    const config = loadConfig();
+    config.oauthAccountFailover = { enabled: true };
+    config.providers["google-antigravity"]!.oauthAccountFailover = { enabled: false };
+    saveConfig(config);
+    const server = startServer(0);
+    try {
+      const dto = await (await fetch(new URL("/api/pool/settings?provider=google-antigravity", server.url))).json() as Record<string, unknown>;
+      expect(dto.enabled).toBe(false);
+      expect(dto.enabledEffective).toBe(false);
+    } finally {
+      await server.stop(true);
+    }
+  });
+
+  test("a write reaches each kind's own storage and is refused identically on bad values", async () => {
+    const server = startServer(0);
+    try {
+      const put = async (payload: Record<string, unknown>) => {
+        const res = await fetch(new URL("/api/pool/settings", server.url), {
+          method: "PUT", headers: { "content-type": "application/json" }, body: JSON.stringify(payload),
+        });
+        return { status: res.status, body: await res.json() as Record<string, unknown> };
+      };
+      // Consolidating the contract does not consolidate the persistence: each kind still lands
+      // in its own place, which is what keeps the legacy paths answering byte-identically.
+      expect((await put({ provider: "openai", strategy: "round-robin", stickyLimit: 5 })).body).toMatchObject({ strategy: "round-robin", stickyLimit: 5 });
+      expect((await put({ provider: "anthropic", strategy: "fill-first", quotaWindow: "weekly" })).body).toMatchObject({ strategy: "fill-first", quotaWindow: "weekly" });
+      expect((await put({ provider: "google-antigravity", strategy: "round-robin", enabled: true })).body).toMatchObject({ strategy: "round-robin", enabled: true, enabledEffective: true });
+      const saved = JSON.parse(readFileSync(join(dir, "config.json"), "utf8"));
+      expect(saved.accountPoolStrategy).toBe("round-robin");
+      expect(saved.anthropicAccountPool.strategy).toBe("fill-first");
+      expect(saved.providers["google-antigravity"].oauthAccountFailover.strategy).toBe("round-robin");
+
+      for (const provider of ["openai", "anthropic", "google-antigravity"]) {
+        expect((await put({ provider, strategy: "weighted" })).status).toBe(400);
+        expect((await put({ provider, stickyLimit: 0 })).status).toBe(400);
+      }
+      // quotaWindow and enabled are declared unsupported for the kinds that lack them, and the
+      // route says so instead of silently dropping the field.
+      expect((await put({ provider: "openai", quotaWindow: "weekly" })).status).toBe(400);
+      expect((await put({ provider: "openai", enabled: true })).status).toBe(400);
+      expect((await put({ provider: "google-antigravity", quotaWindow: "weekly" })).status).toBe(400);
+    } finally {
+      await server.stop(true);
+    }
+  });
+});
diff --git a/tests/server/adapter-resolve.test.ts b/tests/server/adapter-resolve.test.ts
index 1805ad7022..7d316a43c9 100644
--- a/tests/server/adapter-resolve.test.ts
+++ b/tests/server/adapter-resolve.test.ts
@@ -154,9 +154,9 @@ describe("registry per-model wire defaults", () => {
   test("routes the official V4 API ids through Responses", () => {
     expect(resolveWireProtocolOverride("deepseek", "deepseek-v4-flash", deepseek()).adapter)
       .toBe("openai-responses");
-    // V4 Pro GA (DeepSeek-V4-Pro-0813) is officially on the Responses wire too —
+    // V4.1-Flash is officially on the Responses wire too —
     // the /responses reference lists both V4 ids as accepted `model` values.
-    expect(resolveWireProtocolOverride("deepseek", "deepseek-v4-pro", deepseek()).adapter)
+    expect(resolveWireProtocolOverride("deepseek", "deepseek-flash", deepseek()).adapter)
       .toBe("openai-responses");
     // The dated release label is not the API model id and must not be silently rewritten.
     expect(resolveWireProtocolOverride("deepseek", "deepseek-v4-flash-0731", deepseek()).adapter)
diff --git a/tests/server/config.test.ts b/tests/server/config.test.ts
index 33643fb495..b096b5857c 100644
--- a/tests/server/config.test.ts
+++ b/tests/server/config.test.ts
@@ -41,8 +41,11 @@ import { DEFAULT_SUBAGENT_MODELS, migrateSubagentModels } from "../../src/config
 import { migrateStartupSubagentModels } from "../../src/server/subagent-models-startup";
 import { migrateXaiResponsesDefault } from "../../src/providers/xai-responses-opt-in";
 import { migrateStartupXaiResponses } from "../../src/server/xai-responses-startup";
+import { migrateZaiResponsesDefault } from "../../src/providers/zai-responses-migration";
+import { migrateStartupZaiResponses } from "../../src/server/zai-responses-startup";
 import * as configStore from "../../src/config";
 import { runClaudeAuthModeMigration } from "../../src/claude/auth-mode-migration";
+import { runRetiredCodexModelMigration, RETIRED_MODEL_MIGRATION_CUTOFF } from "../../src/codex/retired-model-migration";
 import { providerManagementConfigError } from "../../src/server/auth-cors";
 import { removeTreeWithRetry } from "../helpers/remove-tree";
 let testDir = "";
@@ -186,6 +189,41 @@ describe("Astra-first subagent upgrade", () => {
     expect(loadConfig().subagentModels).toEqual(migrated.subagentModels);
   });
 
+  test("a stored retired model moves to the live floor, including the pool warmup slug", () => {
+    const after = RETIRED_MODEL_MIGRATION_CUTOFF + 1;
+    const stored = {
+      ...getDefaultConfig(),
+      webSearchSidecar: { model: "gpt-5.4-mini", reasoning: "low" },
+      visionSidecar: { model: "gpt-5.4-mini" },
+      tokenGuardian: { codexWarmupEnabled: true, codexWarmupModel: "gpt-5.4-mini" },
+    } as never as ReturnType<typeof getDefaultConfig>;
+
+    expect(runRetiredCodexModelMigration(stored, after)).toBe(true);
+    expect(stored.webSearchSidecar?.model).toBe("gpt-5.6-luna");
+    expect(stored.visionSidecar?.model).toBe("gpt-5.6-luna");
+    expect(stored.tokenGuardian?.codexWarmupModel).toBe("gpt-5.6-luna");
+    // Sibling keys survive: this rewrites one slug, it does not rebuild the block.
+    expect(stored.webSearchSidecar?.reasoning).toBe("low");
+    expect(stored.tokenGuardian?.codexWarmupEnabled).toBe(true);
+    // Idempotent, so a second start does not report a write it does not need.
+    expect(runRetiredCodexModelMigration(stored, after)).toBe(false);
+  });
+
+  test("the retired-model migration leaves any other stored slug alone", () => {
+    const after = RETIRED_MODEL_MIGRATION_CUTOFF + 1;
+    const chosen = {
+      ...getDefaultConfig(),
+      webSearchSidecar: { model: "claude-sonnet-5" },
+      visionSidecar: { model: "gpt-5.6-terra" },
+      tokenGuardian: { codexWarmupModel: "gpt-5.5" },
+    } as never as ReturnType<typeof getDefaultConfig>;
+
+    expect(runRetiredCodexModelMigration(chosen, after)).toBe(false);
+    expect(chosen.webSearchSidecar?.model).toBe("claude-sonnet-5");
+    expect(chosen.visionSidecar?.model).toBe("gpt-5.6-terra");
+    expect(chosen.tokenGuardian?.codexWarmupModel).toBe("gpt-5.5");
+  });
+
   test("unavailable persistence leaves malformed disk bytes untouched", () => {
     const legacy = { ...getDefaultConfig(), subagentModelsVersion: undefined, subagentModels: ["one"] };
     writeConfig("{ invalid");
@@ -303,6 +341,64 @@ describe("one-time Grok Responses upgrade", () => {
   });
 });
 
+describe("one-time Z.AI Responses upgrade", () => {
+  const CANONICAL = { adapter: "openai-responses", baseUrl: "https://api.z.ai" };
+  const RETIRED = { adapter: "openai-chat", baseUrl: "https://api.z.ai/api/coding/paas/v4" };
+
+  function legacy() {
+    return {
+      ...getDefaultConfig(),
+      providers: {
+        zai: { ...RETIRED, authMode: "key" as const, defaultModel: "glm-5.3" },
+      },
+      defaultProvider: "zai",
+    };
+  }
+
+  test("read-only load keeps the retired endpoint; startup persists the canonical wire once", () => {
+    saveConfig(legacy());
+    const before = readFileSync(getConfigPath(), "utf8");
+    const config = loadConfig();
+    expect(config.providers.zai).toMatchObject(RETIRED);
+    expect(readFileSync(getConfigPath(), "utf8")).toBe(before);
+
+    const upgraded = migrateStartupZaiResponses(config);
+    expect(upgraded.providers.zai).toMatchObject({ ...CANONICAL, zaiResponsesDefaultVersion: 1 });
+    expect(upgraded.providers.zai!.defaultModel).toBe("glm-5.3");
+    expect(loadConfig().providers.zai).toEqual(upgraded.providers.zai);
+    // The caller's snapshot is not mutated in place, and a second boot is a no-op.
+    expect(config.providers.zai).toMatchObject(RETIRED);
+    expect(migrateZaiResponsesDefault(upgraded)).toBe(false);
+  });
+
+  test.each([1, 2])("an existing marker of version %i blocks a second rewrite", version => {
+    const config = legacy();
+    config.providers.zai.zaiResponsesDefaultVersion = version;
+    saveConfig(config);
+    expect(migrateStartupZaiResponses(loadConfig()).providers.zai).toEqual(config.providers.zai);
+    expect(loadConfig().providers.zai!.zaiResponsesDefaultVersion).toBe(version);
+  });
+
+  test("a custom-named row at the retired endpoint keeps its configured wire", () => {
+    const source = legacy();
+    const custom = { ...source, defaultProvider: "my-zai", providers: { "my-zai": source.providers.zai } };
+    const before = structuredClone(custom);
+    expect(migrateZaiResponsesDefault(custom)).toBe(false);
+    expect(custom).toEqual(before);
+  });
+
+  test("unavailable persistence preserves disk and returns an isolated projection", () => {
+    const config = legacy();
+    writeConfig("{ invalid");
+    const warn = spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      expect(migrateStartupZaiResponses(config).providers.zai).toMatchObject(CANONICAL);
+      expect(readFileSync(getConfigPath(), "utf8")).toBe("{ invalid");
+      expect(config.providers.zai).toMatchObject(RETIRED);
+    } finally { warn.mockRestore(); }
+  });
+});
+
 function writeConfig(content: unknown): void {
   writeFileSync(
     getConfigPath(),
@@ -325,6 +421,20 @@ function writeResponsesPathConfig(responsesPath: string): void {
   });
 }
 
+function writeChatCompletionsPathConfig(chatCompletionsPath: string): void {
+  writeConfig({
+    port: 12345,
+    providers: {
+      custom: {
+        adapter: "openai-chat",
+        baseUrl: "https://example.test",
+        chatCompletionsPath,
+      },
+    },
+    defaultProvider: "custom",
+  });
+}
+
 function writeAccountNamespaceConfig(
   codexAccountNamespaces: unknown,
   overrides: Record<string, unknown> = {},
@@ -1505,6 +1615,40 @@ describe("opencodex config defaults", () => {
     }
   });
 
+  // chatCompletionsPath is the openai-chat mirror of responsesPath and shares its shape
+  // rules, so the same three cases have to hold on that side too.
+  test("accepts a relative chatCompletionsPath", () => {
+    writeChatCompletionsPathConfig("/api/coding/paas/v4/chat/completions");
+
+    const diagnostics = readConfigDiagnostics();
+    expect(diagnostics.source).toBe("file");
+    expect(diagnostics.error).toBeNull();
+    expect(diagnostics.config.providers.custom.chatCompletionsPath).toBe("/api/coding/paas/v4/chat/completions");
+  });
+
+  test("rejects chatCompletionsPath without a leading slash", () => {
+    writeChatCompletionsPathConfig("chat/completions");
+
+    const diagnostics = readConfigDiagnostics();
+    expect(diagnostics.source).toBe("fallback");
+    expect(diagnostics.error).toContain("chatCompletionsPath must start with /");
+  });
+
+  test("rejects chatCompletionsPath containing a URL scheme, query, or fragment", () => {
+    for (const [chatCompletionsPath, expectedError] of [
+      ["https://other-origin.example/chat/completions", "chatCompletionsPath must be a relative path without a URL scheme"],
+      ["/https://other-origin.example/chat/completions", "chatCompletionsPath must be a relative path without a URL scheme"],
+      ["/chat/completions?api-version=v1", "chatCompletionsPath must not include query strings or fragments"],
+      ["/chat/completions#section", "chatCompletionsPath must not include query strings or fragments"],
+    ] as const) {
+      writeChatCompletionsPathConfig(chatCompletionsPath);
+
+      const diagnostics = readConfigDiagnostics();
+      expect(diagnostics.source).toBe("fallback");
+      expect(diagnostics.error).toContain(expectedError);
+    }
+  });
+
   test("reads valid config diagnostics without mutation", () => {
     writeConfig({
       port: 12345,
diff --git a/tests/server/context-history-ownership.test.ts b/tests/server/context-history-ownership.test.ts
new file mode 100644
index 0000000000..3a1df4253f
--- /dev/null
+++ b/tests/server/context-history-ownership.test.ts
@@ -0,0 +1,171 @@
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { handleResponses } from "../../src/server/responses";
+import { handleContextHistory } from "../../src/server/context-history";
+import { tryAdmitTurn } from "../../src/server/lifecycle";
+import type { DataPlaneAdmission } from "../../src/server/auth-cors";
+import { saveCodexAccountCredential } from "../../src/codex/account-store";
+import { clearAccountNeedsReauth } from "../../src/codex/account-runtime-state";
+import { clearAccountQuota, setAccountQuotaFromParsed } from "../../src/codex/quota";
+import { clearCodexUpstreamHealth, clearThreadAccountMap, resetCodexRoutingForManualSelection } from "../../src/codex/routing";
+import { clearContextSessionOwnersForTests, getContextSessionOwner } from "../../src/codex/context-owner";
+import { resetContextRelayActivationForTests } from "../../src/codex/context-compat";
+
+const principal = "principal-a";
+const keyAdmission: DataPlaneAdmission = { kind: "configured", keyId: "k1", source: "dedicated", contextPrincipalId: principal };
+import type { OcxConfig } from "../../src/types";
+import { removeTreeWithRetry } from "../helpers/remove-tree";
+
+const destination = "https://chatgpt.com/backend-api/codex";
+const originalFetch = globalThis.fetch;
+let previousHome: string | undefined;
+let previousCodexHome: string | undefined;
+let home = "";
+let sent: Array<{ url: string; headers: Headers }> = [];
+let failFirstAccount: string | undefined;
+
+function install(id: string, owner: string, token = `${id}-token`): void {
+  saveCodexAccountCredential(id, { accessToken: token, refreshToken: `${id}-refresh`,
+    chatgptAccountId: owner, expiresAt: Date.now() + 3600_000 });
+  setAccountQuotaFromParsed(id, { weeklyPercent: 20 });
+}
+
+function config(): OcxConfig {
+  return { port: 0, defaultProvider: "openai", activeCodexAccountId: "pool-b",
+    autoSwitchThreshold: 95, accountPoolStrategy: "fill-first", emptyCompletionRetry: false,
+    codexAccountNamespaces: { side: "pool-a" },
+    codexAccounts: [{ id: "pool-a", isMain: false }, { id: "pool-b", isMain: false }],
+    providers: { openai: { adapter: "openai-responses", baseUrl: destination,
+      authMode: "forward", codexAccountMode: "pool" } } };
+}
+
+function requestHeaders(session: string, bearer = "caller-native-token", account = "caller-account"): Headers {
+  return new Headers({ "content-type": "application/json", authorization: `Bearer ${bearer}`,
+    "chatgpt-account-id": account, "session-id": session, "thread-id": session });
+}
+
+async function model(cfg: OcxConfig, session: string, name = "side/gpt-5.5", headers = requestHeaders(session), admission: DataPlaneAdmission = keyAdmission): Promise<Response> {
+  const lease = tryAdmitTurn(); expect(lease).not.toBeNull();
+  try {
+    const response = await handleResponses(new Request("http://localhost/v1/responses", { method: "POST", headers,
+      body: JSON.stringify({ model: name, input: "hello", stream: false }) }), cfg,
+      { model: "", provider: "" }, { turnAdmissionLease: lease!, admission });
+    const text = await response.text();
+    return new Response(text, { status: response.status, headers: response.headers });
+  } finally { lease?.release(); }
+}
+
+async function notes(cfg: OcxConfig, session: string, headers = requestHeaders(session), admission: DataPlaneAdmission = keyAdmission): Promise<Response> {
+  const lease = tryAdmitTurn(); expect(lease).not.toBeNull();
+  try {
+    return await handleContextHistory(new Request("http://localhost/v1/alpha/notes/v2/read_file", {
+      method: "POST", headers, body: JSON.stringify({ context: { session_id: session } }),
+    }), cfg, { model: "context_history", provider: "" }, "alpha/notes/v2/read_file", lease!, admission);
+  } finally { lease?.release(); }
+}
+
+function setContextFeature(enabled: boolean): void {
+  writeFileSync(join(home, "config.toml"), enabled ? "[features]\ncontext_management.experimental_mode = true\n" : "model = \"gpt-5.5\"\n");
+  resetContextRelayActivationForTests();
+}
+
+beforeEach(() => {
+  previousHome = process.env.OPENCODEX_HOME; previousCodexHome = process.env.CODEX_HOME;
+  home = mkdtempSync(join(tmpdir(), "ocx-context-owner-"));
+  process.env.OPENCODEX_HOME = home; process.env.CODEX_HOME = home;
+  setContextFeature(true);
+  clearContextSessionOwnersForTests(); clearAccountQuota(); clearThreadAccountMap(); clearCodexUpstreamHealth();
+  for (const id of ["pool-a", "pool-b", "__main__"]) clearAccountNeedsReauth(id);
+  install("pool-a", "physical-a"); install("pool-b", "physical-b");
+  sent = []; failFirstAccount = undefined;
+  globalThis.fetch = Object.assign(async (input: string | URL | Request, init?: RequestInit) => {
+    const url = String(input); const headers = new Headers(init?.headers); sent.push({ url, headers });
+    if (url === `${destination}/responses`) {
+      if (headers.get("chatgpt-account-id") === failFirstAccount) {
+        failFirstAccount = undefined;
+        return Response.json({ error: { message: "usage limit reached", type: "usage_limit_reached" } }, { status: 429 });
+      }
+      return Response.json({ id: "response-owned", object: "response", status: "completed",
+        output: [{ id: "message-owned", type: "message", role: "assistant", status: "completed",
+          content: [{ type: "output_text", text: "ready", annotations: [] }] }],
+        usage: { input_tokens: 1, output_tokens: 1, total_tokens: 2 } });
+    }
+    if (url === `${destination}/alpha/notes/v2/read_file`) return Response.json({ value: "same account" });
+    throw new Error(`Unexpected test request: ${url}`);
+  }, { preconnect: originalFetch.preconnect });
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+  clearContextSessionOwnersForTests(); clearAccountQuota(); clearThreadAccountMap(); clearCodexUpstreamHealth();
+  removeTreeWithRetry(home);
+  if (previousHome === undefined) delete process.env.OPENCODEX_HOME; else process.env.OPENCODEX_HOME = previousHome;
+  if (previousCodexHome === undefined) delete process.env.CODEX_HOME; else process.env.CODEX_HOME = previousCodexHome;
+});
+
+test("successful explicit account A owns context while active B remains selected", async () => {
+  const cfg = config(); resetCodexRoutingForManualSelection("pool-b");
+  const response = await model(cfg, "root-explicit");
+  expect(response.status).toBe(200);
+  expect(getContextSessionOwner(principal, "root-explicit", destination)).toMatchObject({ kind: "stored", accountId: "pool-a", ambiguous: false });
+  expect((await notes(cfg, "root-explicit")).status).toBe(200);
+  expect(sent.map(row => row.headers.get("chatgpt-account-id"))).toEqual(["physical-a", "physical-a"]);
+  expect(cfg.activeCodexAccountId).toBe("pool-b");
+  // These synthetic tokens carry no user claim, so a replaced credential is a different owner
+  // fingerprint: history waits for an accepted model turn instead of trusting the workspace id.
+  install("pool-a", "physical-a", "renewed-a-token");
+  expect((await notes(cfg, "root-explicit")).status).toBe(409);
+  install("pool-a", "replacement-a");
+  expect((await notes(cfg, "root-explicit")).status).toBe(409);
+  clearContextSessionOwnersForTests();
+  expect((await notes(cfg, "root-explicit")).status).toBe(409);
+  expect(sent).toHaveLength(2);
+});
+
+test("with the experimental feature off no relay state is built and no endpoint answers", async () => {
+  const cfg = config(); resetCodexRoutingForManualSelection("pool-b");
+  setContextFeature(false);
+  expect((await model(cfg, "root-disabled")).status).toBe(200);
+  // The model turn still serves normally; what it must not do is build ownership for a relay
+  // that is switched off, and the endpoints must not answer.
+  expect(getContextSessionOwner(principal, "root-disabled", destination)).toBeUndefined();
+  expect((await notes(cfg, "root-disabled")).status).toBe(404);
+  expect(sent.filter(row => row.url.includes("/alpha/"))).toHaveLength(0);
+});
+
+test("failed account A then successful B records only the serving account", async () => {
+  const cfg = config(); cfg.activeCodexAccountId = "pool-a";
+  resetCodexRoutingForManualSelection("pool-a"); failFirstAccount = "physical-a";
+  const response = await model(cfg, "root-retry", "gpt-5.5");
+  expect(response.status).toBe(200);
+  expect(sent.map(row => row.headers.get("chatgpt-account-id"))).toEqual(["physical-a", "physical-b"]);
+  expect(getContextSessionOwner(principal, "root-retry", destination)).toMatchObject({ kind: "stored", accountId: "pool-b", ambiguous: false });
+  expect((await notes(cfg, "root-retry")).status).toBe(200);
+  expect(sent.at(-1)!.headers.get("chatgpt-account-id")).toBe("physical-b");
+});
+
+test("Direct caller context never borrows stored login or proxy admission", async () => {
+  const cfg = config(); cfg.providers.openai.codexAccountMode = "direct";
+  expect((await model(cfg, "root-caller", "gpt-5.5")).status).toBe(200);
+  expect(getContextSessionOwner(principal, "root-caller", destination)?.kind).toBe("caller");
+  expect((await notes(cfg, "root-caller")).status).toBe(200);
+  expect(sent.map(row => row.headers.get("authorization"))).toEqual(["Bearer caller-native-token", "Bearer caller-native-token"]);
+  const admission = { kind: "environment", source: "bearer", contextPrincipalId: principal } as const;
+  expect((await notes(cfg, "root-caller", requestHeaders("root-caller", "ocx_data_test_key"), admission)).status).toBe(409);
+  expect(sent).toHaveLength(2);
+});
+
+test("Direct proxy-bearer model and notes use stored main without leaking the proxy secret", async () => {
+  const cfg = config(); cfg.providers.openai.codexAccountMode = "direct";
+  const token = `header.${Buffer.from(JSON.stringify({ exp: Math.floor(Date.now() / 1000) + 3600 })).toString("base64url")}.signature`;
+  writeFileSync(join(home, "auth.json"), JSON.stringify({ tokens: { access_token: token, account_id: "physical-main" } }));
+  const admission = { kind: "environment", source: "bearer", contextPrincipalId: principal } as const;
+  const headers = requestHeaders("root-proxy", "ocx_data_test_key", "untrusted-account");
+  expect((await model(cfg, "root-proxy", "gpt-5.5", headers, admission)).status).toBe(200);
+  expect(getContextSessionOwner(principal, "root-proxy", destination)).toMatchObject({ kind: "stored", accountId: "__main__" });
+  expect((await notes(cfg, "root-proxy", headers, admission)).status).toBe(200);
+  expect(sent.map(row => row.headers.get("authorization"))).toEqual([`Bearer ${token}`, `Bearer ${token}`]);
+  expect(sent.every(row => row.headers.get("chatgpt-account-id") === "physical-main")).toBe(true);
+});
diff --git a/tests/server/context-history.test.ts b/tests/server/context-history.test.ts
new file mode 100644
index 0000000000..b44c144ab9
--- /dev/null
+++ b/tests/server/context-history.test.ts
@@ -0,0 +1,408 @@
+// mock.module replacements require file isolation (bun test --isolate).
+import { describe, test, expect, mock, beforeEach, afterAll } from "bun:test";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { resetContextRelayActivationForTests } from "../../src/codex/context-compat";
+import type { CodexAuthContext } from "../../src/codex/auth-context";
+import { recordContextSessionOwner, clearContextSessionOwnersForTests } from "../../src/codex/context-owner";
+import type { DataPlaneAdmission } from "../../src/server/auth-cors";
+import type { OcxConfig } from "../../src/types";
+import type { RequestLogContext } from "../../src/server/request-log";
+
+type Selection = { headers: Headers; mode: string; options: { modelId: string; admission?: DataPlaneAdmission; substituteMainCredentialForDirect?: boolean; accountId?: string; requestScopedMainCredential?: boolean } };
+let selection: Selection | undefined;
+const config: OcxConfig = { port: 0, defaultProvider: "openai", providers: {} };
+const logContext = (): RequestLogContext => ({ model: "context_history", provider: "" });
+
+// The relay only exists while Codex own config opts in, so these cases need a home that does.
+const codexHome = mkdtempSync(join(tmpdir(), "ocx-context-flag-"));
+const codexConfigPath = join(codexHome, "config.toml");
+const previousCodexHome = process.env.CODEX_HOME;
+process.env.CODEX_HOME = codexHome;
+function setContextFeature(enabled: boolean): void {
+  writeFileSync(codexConfigPath, enabled ? "[features]\ncontext_management.experimental_mode = true\n" : "model = \"gpt-5.5\"\n");
+  resetContextRelayActivationForTests();
+}
+setContextFeature(true);
+let materialized: { config: OcxConfig; modelId: string } | undefined;
+let materializationError: Error | undefined;
+let materializationOptions: { admission?: DataPlaneAdmission; substituteMainCredential?: boolean } | undefined;
+let outgoingBearer = "test-only";
+let outgoingAccount = "test-only";
+let accountMode = "pool";
+let validated=0;
+let probe=false;let released=0;let directError=false;let duringSelection:(()=>void)|undefined;
+const errors = {
+  CodexAccountCooldownError: class extends Error {},
+  CodexMainSubstitutionUnavailableError: class extends Error {},
+  CodexDirectAuthenticationError: class extends Error {},
+  CodexAuthContextError: class extends Error {},
+  CodexMainProfileDrainingError: class extends Error {},
+  CodexPoolAuthenticationError: class extends Error {},
+  CodexThreadAffinityExpiredError: class extends Error {},
+};
+mock.module("../../src/codex/auth-context",()=>({
+  ...errors,
+  resolveCodexAuthContext:async(headers: Headers, _config: OcxConfig, mode: string, options: Selection["options"])=>{selection={headers,mode,options};duringSelection?.();if(directError)throw new errors.CodexDirectAuthenticationError();return {kind:"pool",accountId:"test-account",...(probe?{probeLeaseId:"test-probe"}:{})};},
+  isCodexAuthContextUsable:()=>true,
+  releaseCodexAuthContextProbeLease:()=>{released++;},
+  materializeCodexUpstreamAuth: (_headers: Headers, _auth: unknown, options: { config: OcxConfig; modelId: string; admission?: DataPlaneAdmission; substituteMainCredential?: boolean }) => {
+    materializationOptions = options;
+    materialized = { config: options.config, modelId: options.modelId };
+    if (materializationError) throw materializationError;
+    return new Headers({ authorization: `Bearer ${outgoingBearer}`, "chatgpt-account-id": outgoingAccount });
+  },
+  headersForCodexAuthContext:(_headers: Headers, _auth: unknown, selectedConfig: OcxConfig, modelId: string) => {
+    materialized = { config: selectedConfig, modelId };
+    if (materializationError) throw materializationError;
+    return new Headers({ authorization: "Bearer test-only", "chatgpt-account-id": outgoingAccount });
+  },
+  cooldownErrorResponse:()=>new Response("cooldown",{status:429}),
+  codexMainProfileDrainingResponse:()=>new Response("draining",{status:503}),
+}));
+const realRouting = await import("../../src/codex/routing");
+mock.module("../../src/codex/routing",()=>({...realRouting, formatCodexProviderForLog:()=>"openai-test"}));
+mock.module("../../src/providers/openai-sidecar",()=>({listOpenAiForwardSidecarCandidates:()=>[{providerName:"openai",provider:{baseUrl:"https://chatgpt.com/backend-api/codex"},accountMode}]}));
+class ForwardAdmissionCredentialError extends Error {}
+mock.module("../../src/server/auth-cors",()=>({ForwardAdmissionCredentialError,resolveContextPrincipal:(_r:Request,_c:OcxConfig,a?:{contextPrincipalId?:string})=>a?.contextPrincipalId,validateForwardAdmissionCredential:(h:Headers)=>{validated++;if(!h.has("authorization") || h.get("authorization") === "Bearer ocx_data_test_admission")throw new ForwardAdmissionCredentialError("test credential missing");}}));
+mock.module("../../src/server/responses",()=>({codexLogAccountId:()=>"test",decodeRequestErrorResponse:()=>new Response("invalid json",{status:400})}));
+mock.module("../../src/server/lifecycle",()=>({codexAccountSelectionForTurn:()=>()=>undefined}));
+const { handleContextHistory, contextSelectionHeaders } = await import("../../src/server/context-history");
+const destination = "https://chatgpt.com/backend-api/codex";
+let issuedTokens = 0;
+// A real ChatGPT credential carries a stable user claim; ownership continuity across a refresh
+// depends on it, so a test that models a refresh has to issue distinct tokens for one user.
+function userToken(user: string): string {
+  const payload = Buffer.from(JSON.stringify({
+    iat: ++issuedTokens, "https://api.openai.com/auth": { chatgpt_user_id: user },
+  }), "utf8").toString("base64url");
+  return `header.${payload}.signature`;
+}
+function seedOwner(sessionId: string, kind: "stored" | "caller" = "stored", account = "test-only",
+  now?: number, token = "test-only") {
+  const auth = kind === "caller" ? { kind: "main", accountId: null } : {
+    kind: "pool", accountId: "test-account", chatgptAccountId: account,
+    accessToken: "test-only", generation: 1, writerGeneration: 0,
+  };
+  recordContextSessionOwner("principal-a", new Headers({ "session-id": sessionId }), destination,
+    auth as CodexAuthContext, new Headers({ authorization: `Bearer ${token}`, "chatgpt-account-id": account }), false, now);
+}
+const originalFetch=globalThis.fetch;
+function setFetch(handler: (input: string | URL | Request, init?: RequestInit) => Promise<Response>): void {
+  globalThis.fetch = Object.assign(handler, { preconnect: originalFetch.preconnect });
+}
+afterAll(()=>{if(previousCodexHome===undefined)delete process.env.CODEX_HOME;else process.env.CODEX_HOME=previousCodexHome;resetContextRelayActivationForTests();clearContextSessionOwnersForTests();globalThis.fetch=originalFetch;mock.restore();});
+beforeEach(()=>{clearContextSessionOwnersForTests();for (const id of ["root", "root-test", "s"]) seedOwner(id);outgoingAccount="test-only";globalThis.fetch=originalFetch;materialized=undefined;materializationError=undefined;selection=undefined;validated=0;materializationOptions=undefined;outgoingBearer="test-only";accountMode="pool";probe=false;released=0;directError=false;duringSelection=undefined;setContextFeature(true);});
+
+describe("context relay contract",()=>{
+  test("selects root shared lane but sends original body and protocol headers",async()=>{
+    const body={context:{session_id:"root-test",current_agent_name:"/root"},encrypted_arguments:"opaque+==",unknown:{future:true}};
+    let sent: RequestInit & { url: string } = { url: "" };
+    setFetch(async(url: string | URL | Request, opts?: RequestInit)=>{sent={url:String(url),...opts};return new Response('{"ok":true}',{headers:{"content-type":"application/json","x-request-id":"req-test"}});});
+    const req=new Request("http://127.0.0.1/backend-api/codex/alpha/notes/v2/write_file",{method:"POST",headers:{authorization:"Bearer incoming","content-type":"application/json","x-openai-encrypted-tool-arguments":"true","x-openai-tool-output-truncation-policy":"{\"mode\":\"tokens\"}"},body:JSON.stringify(body)});
+    const r=await handleContextHistory(req, config, logContext(), "alpha/notes/v2/write_file", undefined, keyAdmission);
+    expect(r.status).toBe(200);expect(r.headers.get("x-request-id")).toBe("req-test");
+    expect(materialized).toEqual({ config, modelId: "context_history" });
+    expect(validated).toBeGreaterThanOrEqual(1);expect(selection?.mode).toBe("pool");expect(selection?.options.modelId).toBe("context_history");
+    expect(selection?.headers.get("session-id")).toBe("root-test");expect(selection?.headers.get("thread-id")).toBe("root-test");expect(selection?.headers.get("x-codex-parent-thread-id")).toBeNull();
+    expect(JSON.parse(String(sent.body))).toEqual(body);expect(new Headers(sent.headers).has("session-id")).toBe(false);
+    expect(new Headers(sent.headers).get("x-openai-encrypted-tool-arguments")).toBe("true");expect(sent.redirect).toBe("manual");
+  });
+  test("propagates errors without retrying or hiding a write failure",async()=>{
+    let calls=0;
+    setFetch(async()=>{calls++;return new Response('{"error":"feature denied"}',{status:403,headers:{"retry-after":"7"}});});
+    const req=new Request("http://localhost/v1/alpha/notes/v2/write_file",{method:"POST",headers:{authorization:"Bearer test","content-type":"application/json"},body:JSON.stringify({context:{session_id:"s"}})});
+    const r=await handleContextHistory(req, config, logContext(), "alpha/notes/v2/write_file", undefined, keyAdmission);
+    expect(r.status).toBe(403);expect(await r.text()).toBe('{"error":"feature denied"}');expect(r.headers.get("retry-after")).toBe("7");expect(calls).toBe(1);
+  });
+  test("rejects malformed context before any account selection",async()=>{
+    const req=new Request("http://localhost/v1/alpha/notes/v2/write_file",{method:"POST",headers:{authorization:"Bearer test","content-type":"application/json"},body:"{}"});
+    expect((await handleContextHistory(req, config, logContext(), "alpha/notes/v2/write_file", undefined, keyAdmission)).status).toBe(400);expect(selection).toBeUndefined();
+    expect(contextSelectionHeaders(new Headers({"x-codex-parent-thread-id":"parent"}),"s").get("session-id")).toBeNull();
+  });
+});
+
+test("context traffic releases quota probe and maps missing direct auth",async()=>{
+ const request=()=>new Request("http://localhost/v1/alpha/notes/v2/read_file",{method:"POST",headers:{authorization:"Bearer test","content-type":"application/json"},body:JSON.stringify({context:{session_id:"root-test"}})});
+ probe=true;
+ expect((await handleContextHistory(request(), config, logContext(), "alpha/notes/v2/read_file", undefined, keyAdmission)).status).toBe(503);
+ expect(released).toBe(1);
+ probe=false;directError=true;
+ expect((await handleContextHistory(request(), config, logContext(), "alpha/notes/v2/read_file", undefined, keyAdmission)).status).toBe(401);
+});
+test("invalid header characters are rejected before selection",async()=>{
+ const req=new Request("http://localhost/v1/alpha/notes/v2/read_file",{method:"POST",headers:{authorization:"Bearer test","content-type":"application/json"},body:JSON.stringify({context:{session_id:"bad\nvalue"}})});
+ expect((await handleContextHistory(req, config, logContext(), "alpha/notes/v2/read_file", undefined, keyAdmission)).status).toBe(400);
+ expect(selection).toBeUndefined();
+});
+
+function contextRequest(body: string, headers: HeadersInit = { authorization: "Bearer test" }, signal?: AbortSignal): Request {
+  return new Request("http://localhost/v1/alpha/notes/v2/read_file", { method: "POST", headers, body, signal });
+}
+
+test("missing admission credential fails before parsing or selecting an account", async () => {
+  const response = await handleContextHistory(contextRequest("not json", {}), config, logContext(), "alpha/notes/v2/read_file", undefined, keyAdmission);
+  expect(response.status).toBe(401);
+  expect(selection).toBeUndefined();
+});
+
+test("malformed JSON and non-string or oversized session IDs fail before selection", async () => {
+  for (const body of ["not json", "null", JSON.stringify({ context: { session_id: 42 } }), JSON.stringify({ context: { session_id: "a".repeat(513) } })]) {
+    expect((await handleContextHistory(contextRequest(body), config, logContext(), "alpha/notes/v2/read_file", undefined, keyAdmission)).status).toBe(400);
+    expect(selection).toBeUndefined();
+  }
+});
+
+test("existing session and child affinity headers are not overwritten", () => {
+  for (const entry of [{ "session-id": "existing" }, { "thread-id": "child" }, { "x-codex-parent-thread-id": "parent" }] as Record<string, string>[]) {
+    const headers = new Headers(entry);
+    const result = contextSelectionHeaders(headers, "root");
+    expect([...result]).toEqual([...headers]);
+    expect([...headers]).toEqual([...new Headers(entry)]);
+  }
+});
+
+test("network failures and client cancellation do not retry writes", async () => {
+  let calls = 0;
+  setFetch(async () => { calls++; throw new Error("test transport failure"); });
+  const body = JSON.stringify({ context: { session_id: "root" } });
+  expect((await handleContextHistory(contextRequest(body), config, logContext(), "alpha/notes/v2/write_file", undefined, keyAdmission)).status).toBe(502);
+  const controller = new AbortController();
+  setFetch(async () => { calls++; controller.abort(); throw new Error("test canceled"); });
+  expect((await handleContextHistory(contextRequest(body, { authorization: "Bearer test" }, controller.signal), config, logContext(), "alpha/notes/v2/write_file", undefined, keyAdmission)).status).toBe(499);
+  expect(calls).toBe(2);
+});
+
+test("a client that gives up before dispatch releases without reaching upstream", async () => {
+  let calls = 0;
+  setFetch(async () => { calls++; return Response.json({}); });
+  const controller = new AbortController();
+  controller.abort();
+  const response = await handleContextHistory(
+    contextRequest(JSON.stringify({ context: { session_id: "root" } }), { authorization: "Bearer test" }, controller.signal),
+    config, logContext(), "alpha/notes/v2/write_file", undefined, keyAdmission);
+  // The deadline starts before the body is read, so cancellation there is reported as the client
+  // hanging up rather than as a parse failure, and nothing is written upstream.
+  expect(response.status).toBe(499);
+  expect(calls).toBe(0);
+});
+
+test("cancelling during credential selection dispatches nothing", async () => {
+  let calls = 0;
+  setFetch(async () => { calls++; return Response.json({ value: "ok" }); });
+  const controller = new AbortController();
+  duringSelection = () => controller.abort();
+  const response = await handleContextHistory(
+    contextRequest(JSON.stringify({ context: { session_id: "root" } }), { authorization: "Bearer test" }, controller.signal),
+    config, logContext(), "alpha/notes/v2/write_file", undefined, keyAdmission);
+  // Selection is inside the deadline, so a client that leaves during it is reported as a hangup
+  // and nothing reaches upstream. Listener-owned lease release is covered separately.
+  expect(response.status).toBe(499);
+  expect(selection).toBeDefined();
+  expect(calls).toBe(0);
+});
+
+test.each(["body", "selection"])("disabling the feature during %s prevents dispatch", async stage => {
+  let calls = 0;
+  setFetch(async () => { calls++; return Response.json({}); });
+  const body = JSON.stringify({ context: { session_id: "root" } });
+  if (stage === "selection") duringSelection = () => setContextFeature(false);
+  const req = stage === "body"
+    ? new Request("http://localhost/v1/alpha/notes/v2/write_file", {
+        method: "POST", headers: { authorization: "Bearer test" },
+        body: new ReadableStream({ pull(controller) {
+          setContextFeature(false);
+          controller.enqueue(new TextEncoder().encode(body));
+          controller.close();
+        } }, { highWaterMark: 0 }),
+      })
+    : contextRequest(body);
+  const response = await handleContextHistory(req, config, logContext(),
+    "alpha/notes/v2/write_file", undefined, keyAdmission);
+  expect(response.status).toBe(404);
+  expect(calls).toBe(0);
+});
+
+test("a key withdrawn during the request cannot dispatch on its earlier admission", async () => {
+  let calls = 0;
+  setFetch(async () => { calls++; return Response.json({ value: "ok" }); });
+  seedOwner("root-revalidate");
+  const body = JSON.stringify({ context: { session_id: "root-revalidate" } });
+  const response = await handleContextHistory(contextRequest(body), config, logContext(),
+    "alpha/notes/v2/read_file", undefined, keyAdmission, () => null);
+  expect(response.status).toBe(401);
+  expect(calls).toBe(0);
+
+  const rotated = { kind: "configured", keyId: "synthetic-key", source: "dedicated", contextPrincipalId: "principal-b" } as const;
+  expect((await handleContextHistory(contextRequest(body), config, logContext(),
+    "alpha/notes/v2/read_file", undefined, keyAdmission, () => rotated)).status).toBe(401);
+  expect(calls).toBe(0);
+});
+
+test("with the experimental feature off the endpoints do not exist", async () => {
+  let calls = 0;
+  setFetch(async () => { calls++; return Response.json({ value: "ok" }); });
+  setContextFeature(false);
+  const body = JSON.stringify({ context: { session_id: "root" } });
+  // Rewriting the injected base URL is what makes the feature reachable, but a caller that can
+  // already reach the data plane can POST these paths directly, so the opt-in has to hold here.
+  for (const endpoint of ["alpha/history/v2/list_items", "alpha/notes/v2/write_file"]) {
+    const response = await handleContextHistory(contextRequest(body), config, logContext(), endpoint, undefined, keyAdmission);
+    expect(response.status).toBe(404);
+  }
+  expect(selection).toBeUndefined();
+  expect(calls).toBe(0);
+});
+
+test("an admission without a caller principal cannot reach context history", async () => {
+  const before = selection;
+  // Loopback admission authenticates the socket, not a person. Without a minted principal there
+  // is no owner to compare against, so the relay refuses instead of serving whoever asked.
+  for (const admission of [undefined, { kind: "loopback", source: "loopback" } as const]) {
+    const response = await handleContextHistory(
+      contextRequest(JSON.stringify({ context: { session_id: "root" } })),
+      config, logContext(), "alpha/notes/v2/read_file", undefined, admission);
+    expect(response.status).toBe(403);
+    expect(await response.json()).toEqual({ error: {
+      type: "permission_error", code: "permission_denied",
+      message: "Context history requires an opencodex API key on the request; admission alone carries no caller identity",
+    } });
+  }
+  expect(selection).toBe(before);
+});
+
+test("unknown endpoints and methods are rejected before admission", async () => {
+  expect((await handleContextHistory(contextRequest("{}"), config, logContext(), "alpha/notes/v2/delete_file", undefined, keyAdmission)).status).toBe(404);
+  expect((await handleContextHistory(new Request("http://localhost/v1/alpha/notes/v2/read_file"), config, logContext(), "alpha/notes/v2/read_file", undefined, keyAdmission)).status).toBe(404);
+  expect(validated).toBe(0);
+  expect(selection).toBeUndefined();
+});
+
+test("credential materialization rechecks hardlocks and maps auth errors", async () => {
+  const body = JSON.stringify({ context: { session_id: "root" } });
+  let calls = 0;
+  setFetch(async () => { calls++; return new Response("unexpected"); });
+  for (const [error, status] of [[new errors.CodexAccountCooldownError(), 429], [new errors.CodexAuthContextError(), 401]] as const) {
+    materializationError = error;
+    const response = await handleContextHistory(contextRequest(body), config, logContext(), "alpha/notes/v2/read_file", undefined, keyAdmission);
+    expect(response.status).toBe(status);
+    expect(materialized).toEqual({ config, modelId: "context_history" });
+  }
+  expect(calls).toBe(0);
+});
+
+
+const keyAdmission: DataPlaneAdmission = { kind: "configured", keyId: "synthetic-key", source: "dedicated", contextPrincipalId: "principal-a" };
+const bearerAdmission: DataPlaneAdmission = { kind: "configured", keyId: "synthetic-key", source: "bearer", contextPrincipalId: "principal-a" };
+const admissionHeaders = { authorization: "Bearer ocx_data_test_admission" };
+
+test("bearer-admitted context validates the body before selecting credentials", async () => {
+  const response = await handleContextHistory(contextRequest("{}", admissionHeaders), config, logContext(), "alpha/notes/v2/read_file", undefined, bearerAdmission);
+  expect(response.status).toBe(400);
+  expect(await response.text()).toContain("context.session_id");
+  expect(selection).toBeUndefined();
+});
+
+test("stored ownership remains fixed across current Direct and Pool settings", async () => {
+  let calls = 0;
+  setFetch(async (_url, init) => {
+    calls++;
+    expect(new Headers(init?.headers).get("authorization")).toBe("Bearer test-only");
+    return new Response("{}");
+  });
+  for (const mode of ["direct", "pool"]) {
+    accountMode = mode;
+    const response = await handleContextHistory(contextRequest('{"context":{"session_id":"root"}}', admissionHeaders), config, logContext(), "alpha/notes/v2/read_file", undefined, bearerAdmission);
+    expect(response.status).toBe(200);
+    expect(selection?.mode).toBe("pool");
+    expect(selection?.options.accountId).toBe("test-account");
+    expect(selection?.options.admission).toEqual(bearerAdmission);
+    expect(selection?.options.substituteMainCredentialForDirect).toBe(true);
+    expect(materializationOptions?.admission).toEqual(bearerAdmission);
+    expect(materializationOptions?.substituteMainCredential).toBe(true);
+  }
+  expect(calls).toBe(2);
+});
+
+test("proxy credentials cannot escape materialization or bypass non-bearer rejection", async () => {
+  let calls = 0;
+  setFetch(async () => { calls++; return new Response("unexpected"); });
+  outgoingBearer = "ocx_data_test_admission";
+  const body = '{"context":{"session_id":"root"}}';
+  const response = await handleContextHistory(contextRequest(body, admissionHeaders), config, logContext(), "alpha/notes/v2/read_file", undefined, bearerAdmission);
+  expect(response.status).toBe(401);
+  expect(materialized).toBeDefined();
+  for (const admission of [undefined, { kind: "environment", source: "dedicated" } as const, { kind: "loopback", source: "loopback" } as const]) {
+    selection = undefined;
+    expect((await handleContextHistory(contextRequest(body, admissionHeaders), config, logContext(), "alpha/notes/v2/read_file", undefined, admission)).status).toBe(401);
+    expect(selection).toBeUndefined();
+  }
+  expect(calls).toBe(0);
+});
+
+
+test("missing usable stored credentials fail before upstream I/O in bearer mode", async () => {
+  let calls = 0;
+  setFetch(async () => { calls++; return new Response("unexpected"); });
+  for (const mode of ["direct", "pool"]) {
+    accountMode = mode;
+    materializationError = mode === "direct"
+      ? new errors.CodexMainSubstitutionUnavailableError()
+      : new errors.CodexPoolAuthenticationError();
+    const response = await handleContextHistory(contextRequest('{"context":{"session_id":"root"}}', admissionHeaders), config, logContext(), "alpha/notes/v2/read_file", undefined, bearerAdmission);
+    expect(response.status).toBe(401);
+    expect(materializationOptions?.substituteMainCredential).toBe(true);
+  }
+  expect(calls).toBe(0);
+});
+
+
+test("unknown, expired and conflicting owners fail before selecting or sending", async () => {
+  let calls = 0;
+  setFetch(async () => { calls++; return new Response("unexpected"); });
+  for (const state of ["unknown", "expired", "conflicting"]) {
+    clearContextSessionOwnersForTests();
+    if (state === "expired") seedOwner("root", "stored", "test-only", Date.now() - 25 * 60 * 60_000);
+    if (state === "conflicting") { seedOwner("root"); seedOwner("root", "stored", "other-account"); }
+    expect((await handleContextHistory(contextRequest('{"context":{"session_id":"root"}}'), config, logContext(), "alpha/notes/v2/read_file", undefined, keyAdmission)).status).toBe(409);
+    expect(selection).toBeUndefined();
+  }
+  expect(calls).toBe(0);
+});
+
+test("stored token refresh is accepted but physical account replacement is refused", async () => {
+  let calls = 0;
+  setFetch(async () => { calls++; return new Response("{}"); });
+  // Same person, new token: that is what a refresh looks like, and it stays the same owner.
+  clearContextSessionOwnersForTests();
+  seedOwner("root", "stored", "test-only", undefined, userToken("user-a"));
+  outgoingBearer = userToken("user-a");
+  const body = '{"context":{"session_id":"root"}}';
+  expect((await handleContextHistory(contextRequest(body), config, logContext(), "alpha/notes/v2/read_file", undefined, keyAdmission)).status).toBe(200);
+  outgoingAccount = "replacement-account";
+  expect((await handleContextHistory(contextRequest(body), config, logContext(), "alpha/notes/v2/read_file", undefined, keyAdmission)).status).toBe(409);
+  expect(calls).toBe(1);
+});
+
+test("caller owner uses Direct request credentials and cannot authorize proxy-bearer substitution", async () => {
+  clearContextSessionOwnersForTests(); seedOwner("root", "caller");
+  let calls = 0;
+  setFetch(async () => { calls++; return new Response("{}"); });
+  const body = '{"context":{"session_id":"root"}}';
+  expect((await handleContextHistory(contextRequest(body), config, logContext(), "alpha/notes/v2/read_file", undefined, keyAdmission)).status).toBe(200);
+  expect(selection?.mode).toBe("direct");
+  expect(selection?.options.requestScopedMainCredential).toBe(true);
+  expect(selection?.options.accountId).toBeUndefined();
+  expect(materializationOptions?.substituteMainCredential).toBe(false);
+  selection = undefined;
+  expect((await handleContextHistory(contextRequest(body, admissionHeaders), config, logContext(), "alpha/notes/v2/read_file", undefined, bearerAdmission)).status).toBe(409);
+  expect(selection).toBeUndefined(); expect(calls).toBe(1);
+});
+
+test("a context root conflicting with protocol headers is rejected without selection", async () => {
+  const response = await handleContextHistory(contextRequest('{"context":{"session_id":"root"}}', {
+    authorization: "Bearer test", "session-id": "another-root",
+  }), config, logContext(), "alpha/notes/v2/read_file", undefined, keyAdmission);
+  expect(response.status).toBe(409); expect(selection).toBeUndefined();
+});
diff --git a/tests/server/data-plane-admission-identity.test.ts b/tests/server/data-plane-admission-identity.test.ts
index 474ed0658a..1e79431aa2 100644
--- a/tests/server/data-plane-admission-identity.test.ts
+++ b/tests/server/data-plane-admission-identity.test.ts
@@ -5,12 +5,14 @@ import {
   isProxyAdmissionSecret,
   requireResponsesApiAuth,
   resolveApiAuth,
+  resolveContextPrincipal,
   resolveDataPlaneAdmissionSecret,
   resolveResponsesApiAuth,
 } from "../../src/server/auth-cors";
-import { mkdtempSync } from "node:fs";
+import { mkdtempSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { contextRelayActivated } from "../../src/codex/context-compat";
 import { saveConfig } from "../../src/config";
 import { startServer } from "../../src/server";
 import { buildResponsesWsData } from "../../src/server/ws-bridge";
@@ -70,12 +72,35 @@ describe("resolveDataPlaneAdmissionSecret", () => {
     config.apiKeys![0]!.pendingRotation!.expiresAt = new Date(Date.now() - 1).toISOString();
     expect(resolveDataPlaneAdmissionSecret("ocx_data_pendingsecret", config)).toBeNull();
   });
+  test("principal identity binds secret rotation while preserving promotion and transport identity", () => {
+    const config = remoteConfig();
+    const key = config.apiKeys![0]!;
+    const principal = (token: string, source: "dedicated" | "bearer" = "dedicated") => {
+      const admission = resolveDataPlaneAdmissionSecret(token, config, source);
+      expect(admission).not.toBeNull();
+      return admission && "contextPrincipalId" in admission ? admission.contextPrincipalId : undefined;
+    };
+    const initial = principal(key.key);
+    expect(initial).toMatch(/^[a-f0-9]{64}$/);
+    expect(principal(key.key, "bearer")).toBe(initial);
+    expect(principal(config.apiKeys![1]!.key)).not.toBe(initial);
+    key.pendingRotation = { id: "rotation", key: "ocx_data_new_secret",
+      createdAt: new Date().toISOString(), expiresAt: new Date(Date.now() + 60_000).toISOString() };
+    const pending = principal(key.pendingRotation.key);
+    expect(pending).not.toBe(initial);
+    const old = key.key;
+    key.key = key.pendingRotation.key;
+    delete key.pendingRotation;
+    expect(principal(key.key)).toBe(pending);
+    expect(resolveDataPlaneAdmissionSecret(old, config)).toBeNull();
+  });
   test("names the configured key that actually matched", () => {
     const config = remoteConfig();
     expect(resolveDataPlaneAdmissionSecret("ocx_data_firstsecret", config)).toEqual({
       kind: "configured",
       keyId: "first-key",
       source: "dedicated",
+      contextPrincipalId: expect.stringMatching(/^[a-f0-9]{64}$/),
     });
   });
 
@@ -87,12 +112,13 @@ describe("resolveDataPlaneAdmissionSecret", () => {
       kind: "configured",
       keyId: "second-key",
       source: "dedicated",
+      contextPrincipalId: expect.stringMatching(/^[a-f0-9]{64}$/),
     });
   });
 
   test("the environment token has no configured key to name", () => {
     process.env.OPENCODEX_API_AUTH_TOKEN = "env-secret";
-    expect(resolveDataPlaneAdmissionSecret("env-secret", remoteConfig())).toEqual({ kind: "environment", source: "dedicated" });
+    expect(resolveDataPlaneAdmissionSecret("env-secret", remoteConfig())).toEqual({ kind: "environment", source: "dedicated", contextPrincipalId: expect.stringMatching(/^[a-f0-9]{64}$/) });
   });
 
   test.each([
@@ -135,7 +161,7 @@ describe("the two wrappers still differ", () => {
     const bearer = request({ authorization: "Bearer ocx_data_firstsecret" });
 
     // /v1/models and /v1/messages take bearer...
-    expect(resolveApiAuth(bearer, config)).toEqual({ kind: "configured", keyId: "first-key", source: "bearer" });
+    expect(resolveApiAuth(bearer, config)).toEqual({ kind: "configured", keyId: "first-key", source: "bearer", contextPrincipalId: expect.stringMatching(/^[a-f0-9]{64}$/) });
     expect(hasValidApiAuth(bearer, config)).toBe(true);
 
     // ...and Responses now does too. Rejecting it meant a Codex client configured with
@@ -143,7 +169,7 @@ describe("the two wrappers still differ", () => {
     // credential is substituted rather than forwarded -- see materializeCodexUpstreamAuth.
     // The source is recorded so that substitution can be made conditional on it.
     expect(resolveResponsesApiAuth(request({ authorization: "Bearer ocx_data_firstsecret" }), config))
-      .toEqual({ kind: "configured", keyId: "first-key", source: "bearer" });
+      .toEqual({ kind: "configured", keyId: "first-key", source: "bearer", contextPrincipalId: expect.stringMatching(/^[a-f0-9]{64}$/) });
     expect(requireResponsesApiAuth(request({ authorization: "Bearer ocx_data_firstsecret" }), config)).toBeNull();
   });
 
@@ -163,7 +189,7 @@ describe("the two wrappers still differ", () => {
       authorization: "Bearer ocx_data_firstsecret",
     });
     expect(resolveResponsesApiAuth(both, config))
-      .toEqual({ kind: "configured", keyId: "second-key", source: "dedicated" });
+      .toEqual({ kind: "configured", keyId: "second-key", source: "dedicated", contextPrincipalId: expect.stringMatching(/^[a-f0-9]{64}$/) });
   });
 
   test("x-api-key is accepted only by the broad path", () => {
@@ -175,8 +201,8 @@ describe("the two wrappers still differ", () => {
   test("the dedicated header works on both", () => {
     const config = remoteConfig();
     const dedicated = () => request({ "x-opencodex-api-key": "ocx_data_secondsecret" });
-    expect(resolveApiAuth(dedicated(), config)).toEqual({ kind: "configured", keyId: "second-key", source: "dedicated" });
-    expect(resolveResponsesApiAuth(dedicated(), config)).toEqual({ kind: "configured", keyId: "second-key", source: "dedicated" });
+    expect(resolveApiAuth(dedicated(), config)).toEqual({ kind: "configured", keyId: "second-key", source: "dedicated", contextPrincipalId: expect.stringMatching(/^[a-f0-9]{64}$/) });
+    expect(resolveResponsesApiAuth(dedicated(), config)).toEqual({ kind: "configured", keyId: "second-key", source: "dedicated", contextPrincipalId: expect.stringMatching(/^[a-f0-9]{64}$/) });
     expect(requireResponsesApiAuth(dedicated(), config)).toBeNull();
   });
 });
@@ -189,6 +215,55 @@ describe("loopback binds", () => {
     expect(hasValidApiAuth(request(), config)).toBe(true);
     expect(requireResponsesApiAuth(request(), config)).toBeNull();
   });
+
+  test("still let a context caller name itself with a real key", () => {
+    const config = loopbackConfig();
+    const admission = resolveApiAuth(request(), config)!;
+    // Admission is unchanged: the relay asks the identity question separately, so a caller that
+    // volunteers a real key owns its sessions even here, and one that volunteers nothing does not.
+    expect(resolveContextPrincipal(request(), config, admission)).toBeUndefined();
+    expect(resolveContextPrincipal(request({ "x-opencodex-api-key": "ocx_data_wrongsecret" }), config, admission)).toBeUndefined();
+
+    const first = resolveContextPrincipal(request({ "x-opencodex-api-key": "ocx_data_firstsecret" }), config, admission);
+    const bearer = resolveContextPrincipal(request({ authorization: "Bearer ocx_data_firstsecret" }), config, admission);
+    const second = resolveContextPrincipal(request({ "x-opencodex-api-key": "ocx_data_secondsecret" }), config, admission);
+    expect(first).toBeString();
+    expect(bearer).toBe(first!);
+    expect(second).not.toBe(first!);
+  });
+
+  test("the activation gate re-reads a changed config and fails closed on a bad home", () => {
+    const home = mkdtempSync(join(tmpdir(), "ocx-context-gate-"));
+    const configPath = join(home, "config.toml");
+    writeFileSync(configPath, "[features]\ncontext_management.experimental_mode = true\n");
+    expect(contextRelayActivated(configPath)).toBe(true);
+    // No reset seam here on purpose: turning the feature off has to take effect on its own,
+    // which is the whole point of keying the cache on the config identity.
+    writeFileSync(configPath, "[features]\ncontext_management.experimental_mode = false\n");
+    expect(contextRelayActivated(configPath)).toBe(false);
+    writeFileSync(configPath, "model = \"gpt-5.5\"\n");
+    expect(contextRelayActivated(configPath)).toBe(false);
+    expect(contextRelayActivated(join(home, "absent.toml"))).toBe(false);
+
+    const previous = process.env.CODEX_HOME;
+    process.env.CODEX_HOME = join(home, "not-a-directory-here");
+    try {
+      // An unreadable CODEX_HOME is a refusal, never an exception: this runs during model turns.
+      expect(contextRelayActivated()).toBe(false);
+    } finally {
+      if (previous === undefined) delete process.env.CODEX_HOME;
+      else process.env.CODEX_HOME = previous;
+    }
+    removeTreeWithRetry(home);
+  });
+
+  test("a remote bind keeps naming the principal from its own admission", () => {
+    const config = remoteConfig();
+    const admission = resolveApiAuth(request({ "x-opencodex-api-key": "ocx_data_firstsecret" }), config)!;
+    expect(resolveContextPrincipal(request(), config, admission))
+      .toBe(resolveContextPrincipal(request({ "x-opencodex-api-key": "ocx_data_firstsecret" }), config, admission));
+    expect(resolveContextPrincipal(request(), config, undefined)).toBeUndefined();
+  });
 });
 
 describe("the Responses WebSocket handshake", () => {
diff --git a/tests/server/loopback-listener-admission.test.ts b/tests/server/loopback-listener-admission.test.ts
index e87cc5104c..140cebbbfb 100644
--- a/tests/server/loopback-listener-admission.test.ts
+++ b/tests/server/loopback-listener-admission.test.ts
@@ -57,7 +57,7 @@ describe("loopback listener policy view", () => {
     expect(resolveResponsesApiAuth(
       request("/v1/responses", { "x-opencodex-api-key": "ocx_data_realsecret" }),
       wildcardConfig,
-    )).toEqual({ kind: "configured", keyId: "k1", source: "dedicated" });
+    )).toEqual({ kind: "configured", keyId: "k1", source: "dedicated", contextPrincipalId: expect.stringMatching(/^[a-f0-9]{64}$/) });
   });
 
   test("both Anthropic routes finish CORS with the listener-effective policy", () => {
diff --git a/tests/server/management-client-config-route.test.ts b/tests/server/management-client-config-route.test.ts
index 9fcb92e81d..45514c9754 100644
--- a/tests/server/management-client-config-route.test.ts
+++ b/tests/server/management-client-config-route.test.ts
@@ -286,7 +286,15 @@ describe("GET /api/client-config", () => {
     const document = body.config as OpencodeGeneratedConfig;
     expect(document.$schema).toBe(OPENCODE_CONFIG_SCHEMA);
     const models = document.provider[OPENCODE_PROVIDER_ID].models;
-    expect(models["a/m1"]).toEqual({ name: "m1 (a)", limit: { context: 128_000, output: 32_000 } });
+    // The row's declared modalities now reach opencode's own capability fields; without them
+    // opencode gates attachments client-side and the image never leaves the TUI (#4286).
+    expect(models["a/m1"]).toEqual({
+      name: "m1 (a)", limit: { context: 128_000, output: 32_000 },
+      attachment: true, modalities: { input: ["text", "image"], output: ["text"] },
+    });
+    // m2 declares text-only in `modelInputModalities`, which is exactly what routes it through
+    // the vision sidecar: the catalog advertises image so the attachment can reach the proxy.
+    expect(models["a/m2"]!.modalities).toEqual({ input: ["text", "image"], output: ["text"] });
     expect(models["b/no-context"]).toEqual({ name: "no-context (b)" });
   }, 15_000);
 
diff --git a/tests/server/management-provider-validation.test.ts b/tests/server/management-provider-validation.test.ts
index 09bfb1e67c..949791f2d6 100644
--- a/tests/server/management-provider-validation.test.ts
+++ b/tests/server/management-provider-validation.test.ts
@@ -48,6 +48,8 @@ import { getAccountSet, saveCredential } from "../../src/oauth/store";
 import { fastPolicyForModel } from "../../src/providers/service-tier";
 import { resolveWireProtocolOverride } from "../../src/server/adapter-resolve";
 import { removeTreeWithRetry } from "../helpers/remove-tree";
+import { clearProviderQuotaCache, fetchProviderQuotaReports, setProviderQuotaBeforePublishForTests } from "../../src/providers/quota";
+import { setCachedProviderQuotaForTests } from "../../src/providers/quota-routing-cache";
 
 // Full-suite Windows load: startServer + multi-step provider PATCH/GET flows exceed the
 // default 5s per-test budget (same flake class as 810fa115 / claude-management-api).
@@ -136,6 +138,153 @@ afterEach(() => {
   if (existsSync(TEST_DIR)) removeTreeWithRetry(TEST_DIR);
 });
 
+describe("provider quota routing state", () => {
+  function quotaConfig(name = "openrouter", baseUrl = "https://openrouter.ai/api/v1"): OcxConfig {
+    return { port: 10100, defaultProvider: name, providers: { [name]: {
+      adapter: "openai-chat", authMode: "key", baseUrl, apiKey: "synthetic-probed-key",
+    } } };
+  }
+
+  async function readQuota(cfg: OcxConfig, force = false) {
+    const url = new URL(`http://localhost/api/provider-quotas${force ? "?refresh=1" : ""}`);
+    const response = await handleManagementAPI(new Request(url), url, cfg);
+    expect(response?.status).toBe(200);
+    return response!.json();
+  }
+
+  beforeEach(() => {
+    mkdirSync(TEST_DIR, { recursive: true });
+    process.env.OPENCODEX_HOME = TEST_DIR;
+    clearProviderQuotaCache();
+    setProviderQuotaBeforePublishForTests(null);
+  });
+
+  afterEach(() => {
+    clearProviderQuotaCache();
+    setProviderQuotaBeforePublishForTests(null);
+  });
+
+  test("projects bound inference state without mutating display reports", async () => {
+    const cfg: OcxConfig = {
+      port: 10100,
+      defaultProvider: "openrouter",
+      providers: {
+        openrouter: {
+          adapter: "openai-chat", authMode: "key",
+          baseUrl: "https://openrouter.ai/api/v1", apiKey: "synthetic-probed-key",
+        },
+      },
+    };
+    globalThis.fetch = (async () => Response.json({ data: { limit: 20, limit_remaining: 0 } })) as typeof fetch;
+    const url = new URL("http://localhost/api/provider-quotas");
+    const response = await handleManagementAPI(new Request(url), url, cfg);
+    expect(response?.status).toBe(200);
+    const dto = await response!.json();
+    const row = dto.reports.find((item: { provider: string }) => item.provider === "openrouter");
+    expect(row.routingQuota).toEqual({
+      state: "exhausted", updatedAt: row.quota.updatedAt,
+      validUntil: row.quota.updatedAt + 30 * 60_000,
+    });
+    const cached = await fetchProviderQuotaReports(cfg, false);
+    expect(cached.reports[0]).not.toHaveProperty("routingQuota");
+    expect(row.quota).toEqual(cached.reports[0]!.quota);
+    expect(JSON.stringify(dto)).not.toContain("synthetic-probed-key");
+    expect(JSON.stringify(dto)).not.toContain("binding");
+  });
+
+  test("single-key capacity recovers on refresh and an uncapped key drops its old cap", async () => {
+    const cfg = quotaConfig();
+    let payload = { limit: 20 as number | null, limit_remaining: 0 };
+    globalThis.fetch = (async () => Response.json({ data: payload })) as typeof fetch;
+    expect((await readQuota(cfg)).reports[0].routingQuota.state).toBe("exhausted");
+    payload = { limit: 20, limit_remaining: 8 };
+    expect((await readQuota(cfg, true)).reports[0].routingQuota.state).toBe("available");
+    payload = { limit: null, limit_remaining: 0 };
+    expect((await readQuota(cfg, true)).reports).toEqual([]);
+  });
+
+  test.each(["authorization", "x-api-key", "x-goog-api-key", "key-pool", "oauth"])(
+    "rechecks current credential scope: %s", async change => {
+      const cfg = quotaConfig();
+      globalThis.fetch = (async () => Response.json({ data: { limit: 20, limit_remaining: 0 } })) as typeof fetch;
+      expect((await readQuota(cfg)).reports[0].routingQuota.state).toBe("exhausted");
+      if (change === "key-pool") cfg.providers.openrouter!.apiKeyPool = [
+        { id: "primary", key: "synthetic-probed-key" },
+        { id: "secondary", key: "other-key" },
+      ];
+      else if (change === "oauth") cfg.providers.openrouter!.authMode = "oauth";
+      else cfg.providers.openrouter!.headers = { [change]: "other-credential" };
+      const dto = await readQuota(cfg);
+      expect(dto.reports.every((row: { routingQuota: { state: string } }) => row.routingQuota.state === "unknown")).toBe(true);
+    },
+  );
+
+  test("reads a provider row replaced while the quota probe is awaiting publication", async () => {
+    const cfg = quotaConfig();
+    let replaced = false;
+    globalThis.fetch = (async () => Response.json({ data: { limit: 20, limit_remaining: 0 } })) as typeof fetch;
+    setProviderQuotaBeforePublishForTests(() => {
+      cfg.providers.openrouter = { ...cfg.providers.openrouter!, apiKey: "replacement-key" };
+      replaced = true;
+    });
+    const dto = await readQuota(cfg);
+    expect(replaced).toBe(true);
+    expect(dto.reports.every((row: { routingQuota: { state: string } }) => row.routingQuota.state === "unknown")).toBe(true);
+  });
+
+  test("search-only and MCP-only display windows have no inference authority", async () => {
+    const cfg: OcxConfig = { port: 10100, defaultProvider: "synthetic", providers: {
+      ...quotaConfig("synthetic", "https://api.synthetic.new/v2").providers,
+      ...quotaConfig("zai", "https://api.z.ai/api/coding/paas/v4").providers,
+    } };
+    globalThis.fetch = (async input => String(input).includes("synthetic")
+      ? Response.json({ data: { search: { hourly: 100 } } })
+      : Response.json({ success: true, data: { monthlyMCPUsage: 100 } })) as typeof fetch;
+    const dto = await readQuota(cfg);
+    expect(dto.reports).toHaveLength(2);
+    expect(dto.reports.every((row: { routingQuota: { state: string } }) => row.routingQuota.state === "unknown")).toBe(true);
+    expect(dto.reports.find((row: { provider: string }) => row.provider === "synthetic").quota.customWindows[0].percent).toBe(100);
+    expect(dto.reports.find((row: { provider: string }) => row.provider === "zai").quota.monthlyPercent).toBe(100);
+  });
+
+  test("an exhausted OAuth account report stays display-only", async () => {
+    const cfg = quotaConfig("kimi", "https://api.kimi.com/coding/v1");
+    cfg.providers.kimi!.authMode = "oauth";
+    await saveCredential("kimi", { access: "synthetic-account-access", refresh: "synthetic-account-refresh", expires: Date.now() + 3600_000 });
+    globalThis.fetch = (async () => Response.json({ usage: { limit: "100", used: "100" } })) as typeof fetch;
+    const dto = await readQuota(cfg);
+    expect(dto.reports[0].quota.weeklyPercent).toBe(100);
+    expect(dto.reports[0].routingQuota).toEqual({ state: "unknown" });
+  });
+
+  test("cached responses respect reset boundaries, persistent blockers and evidence expiry", async () => {
+    const cfg = quotaConfig();
+    let probes = 0;
+    globalThis.fetch = (async () => {
+      probes += 1;
+      return Response.json({ data: { limit: 20, limit_remaining: 0 } });
+    }) as typeof fetch;
+    const first = await readQuota(cfg);
+    const now = Date.now();
+    const quota = { updatedAt: now, fiveHourPercent: 100, fiveHourResetAt: now + 10_000,
+      weeklyPercent: 100, weeklyResetAt: now + 20_000 };
+    setCachedProviderQuotaForTests("openrouter", quota);
+    expect((await readQuota(cfg)).reports[0].routingQuota.validUntil).toBe(now + 20_000);
+    setCachedProviderQuotaForTests("openrouter", { ...quota, creditsUsd: { used: 20, limit: 20, remaining: 0, percent: 100 } });
+    expect((await readQuota(cfg)).reports[0].routingQuota.validUntil).toBe(now + 30 * 60_000);
+    setCachedProviderQuotaForTests("openrouter", { updatedAt: now, fiveHourPercent: 100, fiveHourResetAt: now - 1 });
+    expect((await readQuota(cfg)).reports[0].routingQuota.state).toBe("available");
+    setCachedProviderQuotaForTests("openrouter", { updatedAt: now,
+      creditsUsd: { used: 0, limit: 0, remaining: 0, percent: 0, unlimited: true } });
+    expect((await readQuota(cfg)).reports[0].routingQuota.state).toBe("available");
+    setCachedProviderQuotaForTests("openrouter", { ...quota, updatedAt: now - 30 * 60_000 });
+    const stale = await readQuota(cfg);
+    expect(stale.reports[0].routingQuota).toEqual({ state: "unknown" });
+    expect(stale.reports[0].quota).toEqual(first.reports[0].quota);
+    expect(probes).toBe(1);
+  });
+});
+
 describe("provider management validation", () => {
   test("provider reload adopts only the validated disk row without rewriting config", async () => {
     if (existsSync(TEST_DIR)) removeTreeWithRetry(TEST_DIR);
diff --git a/tests/server/server-combo-failover-e2e.test.ts b/tests/server/server-combo-failover-e2e.test.ts
index 38f0368d54..6f649c52d3 100644
--- a/tests/server/server-combo-failover-e2e.test.ts
+++ b/tests/server/server-combo-failover-e2e.test.ts
@@ -1412,7 +1412,7 @@ describe("server combo failover 030 activation matrix", () => {
         authMode: "forward",
         codexAccountMode: "pool",
       },
-    }, [{ provider: "openai", model: "gpt-5.4" }]);
+    }, [{ provider: "openai", model: "gpt-5.6-luna" }]);
     config.codexAccounts = [{
       id: rawAccountId,
       email: "pool@example.test",
@@ -1427,7 +1427,7 @@ describe("server combo failover 030 activation matrix", () => {
       expiresAt: Date.now() + 300_000,
       chatgptAccountId: "acct-pool-safe",
     });
-    customTransientResponse = async () => Response.json(responsesSuccess("pool success", "gpt-5.4"));
+    customTransientResponse = async () => Response.json(responsesSuccess("pool success", "gpt-5.6-luna"));
 
     const response = await postLogged(config);
     expect(response.status).toBe(200);
@@ -1459,7 +1459,7 @@ describe("server combo failover 030 activation matrix", () => {
         authMode: "forward",
         codexAccountMode: "pool",
       },
-    }, [{ provider: "openai", model: "gpt-5.4" }]);
+    }, [{ provider: "openai", model: "gpt-5.6-luna" }]);
     config.codexAccounts = [{
       id: rawAccountId,
       email: "combo-terminal@example.test",
@@ -1504,7 +1504,7 @@ describe("server combo failover 030 activation matrix", () => {
       },
     }, [
       { provider: "openai", model: "gpt-5.3-codex-spark" },
-      { provider: "openai", model: "gpt-5.4" },
+      { provider: "openai", model: "gpt-5.6-luna" },
     ]);
     config.codexAccounts = [{
       id: rawAccountId,
@@ -1531,7 +1531,7 @@ describe("server combo failover 030 activation matrix", () => {
             headers: { "x-codex-primary-reset-at": String(Math.floor(Date.now() / 1000) + 3600) },
           },
         )
-        : Response.json(responsesSuccess("model fallback succeeded", "gpt-5.4"));
+        : Response.json(responsesSuccess("model fallback succeeded", "gpt-5.6-luna"));
     };
 
     const response = await postLogged(config);
@@ -1552,7 +1552,7 @@ describe("server combo failover 030 activation matrix", () => {
       },
     }, [
       { provider: "openai", model: "gpt-5.3-codex-spark" },
-      { provider: "openai", model: "gpt-5.4" },
+      { provider: "openai", model: "gpt-5.6-luna" },
     ]);
     config.codexAccounts = [{
       id: rawAccountId,
@@ -1582,7 +1582,7 @@ describe("server combo failover 030 activation matrix", () => {
             },
           },
         )
-        : Response.json(responsesSuccess("must not reach second upstream", "gpt-5.4"));
+        : Response.json(responsesSuccess("must not reach second upstream", "gpt-5.6-luna"));
     };
 
     const response = await postLogged(config);
@@ -3801,7 +3801,7 @@ describe("combo compact failover", () => {
       return chatStream("compact backup");
     });
     const { config } = canonicalPoolConfig([
-      { provider: "openai-apikey", model: "gpt-5.4" },
+      { provider: "openai-apikey", model: "gpt-5.6-luna" },
       { provider: "backup", model: "m1" },
     ], baseUrl(b));
     globalThis.fetch = (async (input: unknown, init?: RequestInit) => {
@@ -3857,7 +3857,7 @@ describe("combo compact failover", () => {
 
   test("combo compact runs the synthetic turn as SSE so a canonical child can serve it", async () => {
     const bodies: Array<Record<string, unknown>> = [];
-    const { config } = canonicalPoolConfig([{ provider: "openai-apikey", model: "gpt-5.4" }]);
+    const { config } = canonicalPoolConfig([{ provider: "openai-apikey", model: "gpt-5.6-luna" }]);
     globalThis.fetch = (async (input: unknown, init?: RequestInit) => {
       const url = typeof input === "object" && input !== null && "url" in input
         ? String((input as Request).url)
@@ -3908,7 +3908,7 @@ describe("combo compact failover", () => {
   });
 
   test("native compact rejects an empty ciphertext item", async () => {
-    const { config } = canonicalPoolConfig([{ provider: "openai-apikey", model: "gpt-5.4" }]);
+    const { config } = canonicalPoolConfig([{ provider: "openai-apikey", model: "gpt-5.6-luna" }]);
     globalThis.fetch = (async (input: unknown, init?: RequestInit) => {
       const url = typeof input === "object" && input !== null && "url" in input
         ? String((input as Request).url)
diff --git a/tests/server/server-images.test.ts b/tests/server/server-images.test.ts
index 371aa264c0..f08dfac858 100644
--- a/tests/server/server-images.test.ts
+++ b/tests/server/server-images.test.ts
@@ -9,7 +9,8 @@ import { join } from "node:path";
 import { saveCodexAccountCredential } from "../../src/codex/account-store";
 import { clearAccountNeedsReauth, clearAccountQuota } from "../../src/codex/auth-api";
 import { clearCodexUpstreamHealth, clearThreadAccountMap, getCodexUpstreamHealth } from "../../src/codex/routing";
-import { saveConfig } from "../../src/config";
+import { loadConfig, saveConfig } from "../../src/config";
+import { clearKeyCooldowns, rotateKeyOn429 } from "../../src/providers/key-failover";
 import { selectImagesProvider } from "../../src/providers/openai-sidecar";
 import { startServer } from "../../src/server";
 import { handleImages, IMAGES_RESPONSE_MAX_BYTES, readImageResponseBytes, setXaiResultPinnedDownloadForTests } from "../../src/server/images";
@@ -685,6 +686,144 @@ test("zstd-compressed request bodies are decoded before the relay", async () =>
   }
 });
 
+
+test("a cooled committed key is replaced before the first keyed image send", async () => {
+  const captured: CapturedRequest[] = [];
+  const upstream = fakeImagesUpstream(captured);
+  clearKeyCooldowns();
+  const pooled = {
+    ...keyedProvider(upstream.url.toString().replace(/\/$/, "")),
+    apiKeyPoolStrategy: "round-robin",
+    apiKeyPool: [
+      { id: "first", key: "sk-platform-key" },
+      { id: "second", key: "sk-warm-key" },
+    ],
+  };
+  saveConfig({
+    port: 0,
+    defaultProvider: "openai-apikey",
+    openaiProviderTierVersion: 2,
+    providers: { openai: disabledOpenAiProvider, "openai-apikey": pooled },
+  } as unknown as OcxConfig);
+
+  // Cool the committed key the way a real 429 does, then point the stored selection back at it.
+  // This is the state an operator lands in after a rotation plus a restart or a config reload.
+  const live = loadConfig();
+  rotateKeyOn429(live, "openai-apikey", null, Date.now(), "sk-platform-key");
+  const restored = loadConfig();
+  restored.providers["openai-apikey"]!.apiKey = "sk-platform-key";
+  saveConfig(restored);
+
+  const server = startServer(0);
+  try {
+    const response = await fetch(new URL("/v1/images/generations", server.url), {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${DIRECT_CHATGPT_TOKEN}` },
+      body: JSON.stringify({ prompt: "a cat", model: "gpt-image-2" }),
+    });
+    expect(response.status).toBe(200);
+    expect(captured).toHaveLength(1);
+    // The warm key, on the FIRST send. This path builds its own Authorization header from a
+    // snapshot resolved before the pick, so a naive wiring would have sent sk-platform-key here
+    // while the picker had already committed sk-warm-key to config.
+    expect(captured[0].headers.get("authorization")).toBe("Bearer sk-warm-key");
+  } finally {
+    await server.stop(true);
+    await upstream.stop(true);
+    clearKeyCooldowns();
+  }
+});
+
+/**
+ * The pick COMMITS its choice before returning, so an unresolvable selection is not a reason to
+ * quietly reuse the previous key: that would authenticate a non-idempotent image POST with a
+ * credential the config no longer treats as active, and the previous key is the one that was
+ * cooling. Raised by CodeRabbit on #4292.
+ */
+test("an unresolvable selected key fails the keyed image send instead of reusing the old one", async () => {
+  const captured: CapturedRequest[] = [];
+  const upstream = fakeImagesUpstream(captured);
+  clearKeyCooldowns();
+  delete process.env.OCX_IMAGES_MISSING_KEY;
+  const pooled = {
+    ...keyedProvider(upstream.url.toString().replace(/\/$/, "")),
+    apiKeyPoolStrategy: "round-robin",
+    apiKeyPool: [
+      { id: "first", key: "sk-platform-key" },
+      // An env reference that is deliberately not set: a revoked keychain entry looks the same.
+      { id: "second", key: "\${OCX_IMAGES_MISSING_KEY}" },
+    ],
+  };
+  saveConfig({
+    port: 0,
+    defaultProvider: "openai-apikey",
+    openaiProviderTierVersion: 2,
+    providers: { openai: disabledOpenAiProvider, "openai-apikey": pooled },
+  } as unknown as OcxConfig);
+  const live = loadConfig();
+  rotateKeyOn429(live, "openai-apikey", null, Date.now(), "sk-platform-key");
+  const restored = loadConfig();
+  restored.providers["openai-apikey"]!.apiKey = "sk-platform-key";
+  saveConfig(restored);
+
+  const server = startServer(0);
+  try {
+    const response = await fetch(new URL("/v1/images/generations", server.url), {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${DIRECT_CHATGPT_TOKEN}` },
+      body: JSON.stringify({ prompt: "a cat", model: "gpt-image-2" }),
+    });
+    expect(response.status).toBe(500);
+    // Nothing was sent. Red control: restore the `?? candidates.keyed.apiKey` fallback and this
+    // becomes a 200 carrying Bearer sk-platform-key -- the cooled key the pool had left.
+    expect(captured).toHaveLength(0);
+  } finally {
+    await server.stop(true);
+    await upstream.stop(true);
+    clearKeyCooldowns();
+  }
+});
+
+test("without a configured strategy the keyed image send keeps the cooled key", async () => {
+  const captured: CapturedRequest[] = [];
+  const upstream = fakeImagesUpstream(captured);
+  clearKeyCooldowns();
+  const pooled = {
+    ...keyedProvider(upstream.url.toString().replace(/\/$/, "")),
+    apiKeyPool: [
+      { id: "first", key: "sk-platform-key" },
+      { id: "second", key: "sk-warm-key" },
+    ],
+  };
+  saveConfig({
+    port: 0,
+    defaultProvider: "openai-apikey",
+    openaiProviderTierVersion: 2,
+    providers: { openai: disabledOpenAiProvider, "openai-apikey": pooled },
+  } as unknown as OcxConfig);
+  const live = loadConfig();
+  rotateKeyOn429(live, "openai-apikey", null, Date.now(), "sk-platform-key");
+  const restored = loadConfig();
+  restored.providers["openai-apikey"]!.apiKey = "sk-platform-key";
+  saveConfig(restored);
+
+  const server = startServer(0);
+  try {
+    const response = await fetch(new URL("/v1/images/generations", server.url), {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${DIRECT_CHATGPT_TOKEN}` },
+      body: JSON.stringify({ prompt: "a cat", model: "gpt-image-2" }),
+    });
+    expect(response.status).toBe(200);
+    // Rotation stays reactive-only for an install that never asked for a strategy.
+    expect(captured[0].headers.get("authorization")).toBe("Bearer sk-platform-key");
+  } finally {
+    await server.stop(true);
+    await upstream.stop(true);
+    clearKeyCooldowns();
+  }
+});
+
 test("falls back to a keyed openai-responses provider when no forward provider exists", async () => {
   const captured: CapturedRequest[] = [];
   const upstream = fakeImagesUpstream(captured);
diff --git a/tests/server/server-key-failover-e2e.test.ts b/tests/server/server-key-failover-e2e.test.ts
index d23bf848dd..418ef993ca 100644
--- a/tests/server/server-key-failover-e2e.test.ts
+++ b/tests/server/server-key-failover-e2e.test.ts
@@ -3,7 +3,7 @@ import { mkdtempSync} from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { loadConfig, saveConfig } from "../../src/config";
-import { clearKeyCooldowns } from "../../src/providers/key-failover";
+import { clearKeyCooldowns, rotateKeyOn429 } from "../../src/providers/key-failover";
 import { deriveXaiConvId } from "../../src/providers/xai-transport";
 import { clearReasoningReplayCacheForTests } from "../../src/responses/reasoning-replay-cache";
 import { startServer } from "../../src/server";
@@ -664,3 +664,126 @@ describe("server 429 key failover (end-to-end)", () => {
     }
   });
 });
+
+  /**
+   * Both cases land on the same state: the committed key is already cooling when a request
+   * arrives. That is not exotic -- it is what an operator has after the pool rotated and a
+   * restart, a manual edit or a config reload pointed `apiKey` back at the spent key.
+   */
+  async function cooledCommittedKeySetup(strategy?: "round-robin" | "fill-first") {
+    const seen: string[] = [];
+    upstream = Bun.serve({ hostname: "127.0.0.1", port: 0, fetch(req) {
+      seen.push(req.headers.get("authorization") ?? "");
+      return Response.json({ id: "chatcmpl-warm", object: "chat.completion",
+        choices: [{ index: 0, message: { role: "assistant", content: "warm" }, finish_reason: "stop" }],
+        usage: { prompt_tokens: 1, completion_tokens: 1 },
+      });
+    } });
+    saveConfig({ port: 0, hostname: "127.0.0.1", defaultProvider: "pooled", providers: { pooled: {
+      adapter: "openai-chat", baseUrl: `http://127.0.0.1:${upstream.port}/v1`, allowPrivateNetwork: true,
+      authMode: "key", apiKey: "synthetic-first",
+      ...(strategy ? { apiKeyPoolStrategy: strategy } : {}),
+      apiKeyPool: [{ id: "first", key: "synthetic-first" }, { id: "second", key: "synthetic-second" }],
+    } } } as OcxConfig);
+    // Cool the committed key exactly the way a real 429 does, then point the stored selection
+    // back at it. Cooldowns are process-local, so the server started below shares this state.
+    const live = loadConfig();
+    rotateKeyOn429(live, "pooled", null, Date.now(), "synthetic-first");
+    const restored = loadConfig();
+    restored.providers.pooled!.apiKey = "synthetic-first";
+    saveConfig(restored);
+    return seen;
+  }
+
+  test("a cooled committed key is replaced before the first attempt", async () => {
+    const seen = await cooledCommittedKeySetup("round-robin");
+    const server = startServer(0);
+    try {
+      const response = await fetch(new URL("/v1/chat/completions", server.url), {
+        method: "POST", headers: { "content-type": "application/json" },
+        body: JSON.stringify({ model: "pooled/test", stream: false, messages: [{ role: "user", content: "hello" }] }),
+      });
+      expect(response.status).toBe(200);
+      // ONE attempt, on the warm key. Reactive rotation alone cannot produce this: it needs a
+      // 429 first, so without the pre-dispatch pick the upstream would see the cooled key here
+      // and the request would be spent earning a refusal the runtime could already predict.
+      expect(seen).toEqual(["Bearer synthetic-second"]);
+    } finally {
+      await server.stop(true);
+    }
+  });
+
+  test("without a configured strategy the cooled key is still used", async () => {
+    const seen = await cooledCommittedKeySetup();
+    const server = startServer(0);
+    try {
+      const response = await fetch(new URL("/v1/chat/completions", server.url), {
+        method: "POST", headers: { "content-type": "application/json" },
+        body: JSON.stringify({ model: "pooled/test", stream: false, messages: [{ role: "user", content: "hello" }] }),
+      });
+      expect(response.status).toBe(200);
+      // The other half of the contract: rotation stays reactive-only for an install that never
+      // asked for a strategy, so the committed key is honoured even when it is cooling.
+      expect(seen).toEqual(["Bearer synthetic-first"]);
+    } finally {
+      await server.stop(true);
+    }
+  });
+
+  /**
+   * The two cases above pin the behaviour but not the PATH: an `openai-chat` provider sends
+   * /v1/chat/completions through `handleNativeChatCompletions`, so the pick in
+   * `responses/core.ts` never runs in either of them. This one goes through /v1/responses, so
+   * the independently changed core call site is actually covered.
+   *
+   * The pool keys are stored as `\${VAR}` references on purpose. Reference resolution is one of
+   * the backfills `routedProviderConfig` applies and the adapter does not, so the upstream
+   * bearer proves the route the core path dispatched was a rebuilt one rather than the
+   * picker's persisted snapshot.
+   *
+   * Red control: remove the pick from core.ts and the upstream sees `Bearer resolved-cooled`,
+   * because the committed selection still points at the cooled key.
+   *
+   * What this case does NOT prove is the Transport-vs-snapshot distinction on this path:
+   * `refreshDispatchAdapter` re-derives the transport from config before dispatch, so the
+   * Responses core self-heals a wholesale assignment. That contract is pinned as a unit in
+   * tests/adapters/key-failover.test.ts, where it has a red control that actually fails.
+   */
+  test("the Responses core pick reaches the warm key through /v1/responses", async () => {
+    const seen: string[] = [];
+    upstream = Bun.serve({ hostname: "127.0.0.1", port: 0, fetch(req) {
+      seen.push(req.headers.get("authorization") ?? "");
+      return Response.json({ id: "chatcmpl-warm", object: "chat.completion",
+        choices: [{ index: 0, message: { role: "assistant", content: "warm" }, finish_reason: "stop" }],
+        usage: { prompt_tokens: 1, completion_tokens: 1 },
+      });
+    } });
+    process.env.OCX_KEYFAIL_COOLED = "resolved-cooled";
+    process.env.OCX_KEYFAIL_WARM = "resolved-warm";
+    saveConfig({ port: 0, hostname: "127.0.0.1", defaultProvider: "env-pooled", providers: { "env-pooled": {
+      adapter: "openai-chat", baseUrl: `http://127.0.0.1:${upstream.port}/v1`, allowPrivateNetwork: true,
+      authMode: "key", apiKey: "\${OCX_KEYFAIL_COOLED}", apiKeyPoolStrategy: "round-robin",
+      apiKeyPool: [
+        { id: "cooled", key: "\${OCX_KEYFAIL_COOLED}" },
+        { id: "warm", key: "\${OCX_KEYFAIL_WARM}" },
+      ],
+    } } } as OcxConfig);
+    const live = loadConfig();
+    rotateKeyOn429(live, "env-pooled", null, Date.now(), "\${OCX_KEYFAIL_COOLED}");
+    const restored = loadConfig();
+    restored.providers["env-pooled"]!.apiKey = "\${OCX_KEYFAIL_COOLED}";
+    saveConfig(restored);
+    const server = startServer(0);
+    try {
+      const response = await fetch(new URL("/v1/responses", server.url), {
+        method: "POST", headers: { "content-type": "application/json" },
+        body: JSON.stringify({ model: "env-pooled/test", input: "hi", stream: false }),
+      });
+      expect(response.status).toBe(200);
+      expect(seen).toEqual(["Bearer resolved-warm"]);
+    } finally {
+      await server.stop(true);
+      delete process.env.OCX_KEYFAIL_COOLED;
+      delete process.env.OCX_KEYFAIL_WARM;
+    }
+  });
diff --git a/tests/server/server-live.test.ts b/tests/server/server-live.test.ts
index f6d4da8916..f0fc6c94cd 100644
--- a/tests/server/server-live.test.ts
+++ b/tests/server/server-live.test.ts
@@ -198,7 +198,7 @@ test("POST /v1/live rewrites ChatGPT multipart into backend realtime/calls JSON"
   }
 });
 
-test("POST /v1/live relays to an OpenAI API-key provider at /v1/live without AVAS", async () => {
+test.each(["/v1/live", "/backend-api/codex/live"])("POST %s relays to an OpenAI API-key provider at /v1/live without AVAS", async (path) => {
   const captured: CapturedRequest[] = [];
   const upstream = fakeLiveUpstream(captured, 201, "/v1/live/rtc_api");
   saveConfig({
@@ -217,7 +217,7 @@ test("POST /v1/live relays to an OpenAI API-key provider at /v1/live without AVA
   const server = startServer(0);
   try {
     const { body, contentType } = multipartLiveBody();
-    const response = await fetch(new URL("/v1/live", server.url), {
+    const response = await fetch(new URL(path, server.url), {
       method: "POST",
       headers: { "content-type": contentType },
       body,
diff --git a/tests/server/server-management-auth.test.ts b/tests/server/server-management-auth.test.ts
index 4b9995ab90..2e5f3db061 100644
--- a/tests/server/server-management-auth.test.ts
+++ b/tests/server/server-management-auth.test.ts
@@ -1,9 +1,14 @@
+import { request as httpRequest } from "node:http";
+import { getActiveTurnCount } from "../../src/server/lifecycle";
+// Holds INV-AUTH-01 from structure/overview.md; keep the id here if this file is split or renamed.
 import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
 import { SERVER_BUDGET_MS } from "../helpers/test-budget";
 import { mkdtempSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { getConfigPath, saveConfig } from "../../src/config";
+import { clearContextSessionOwnersForTests } from "../../src/codex/context-owner";
+import { resetContextRelayActivationForTests } from "../../src/codex/context-compat";
 import { startServer } from "../../src/server";
 import { readCodexAccountRecord, saveCodexAccountCredential } from "../../src/codex/account-store";
 import type { OcxConfig } from "../../src/types";
@@ -86,10 +91,16 @@ import { setSystemRestartIoForTests } from "../../src/server/management/system-r
 import { removeTreeWithRetry } from "../helpers/remove-tree";
 
 const previousHome = process.env.OPENCODEX_HOME;
+const previousCodexHome = process.env.CODEX_HOME;
 const previousDataToken = process.env.OPENCODEX_API_AUTH_TOKEN;
 const previousAdminToken = process.env.OPENCODEX_ADMIN_AUTH_TOKEN;
 let testHome = "";
 
+function enableContextRelay(): void {
+  writeFileSync(join(testHome, "config.toml"), "[features]\ncontext_management.experimental_mode = true\n");
+  resetContextRelayActivationForTests();
+}
+
 function remoteConfig(): OcxConfig {
   return {
     port: 0,
@@ -172,11 +183,16 @@ function websocketHandshakeOpens(url: URL, token: string): Promise<boolean> {
 beforeEach(() => {
   testHome = mkdtempSync(join(tmpdir(), "ocx-management-auth-"));
   process.env.OPENCODEX_HOME = testHome;
+  process.env.CODEX_HOME = testHome;
+  resetContextRelayActivationForTests();
   process.env.OPENCODEX_API_AUTH_TOKEN = "data-secret";
   process.env.OPENCODEX_ADMIN_AUTH_TOKEN = "admin-secret";
 });
 
 afterEach(() => {
+  resetContextRelayActivationForTests();
+  if (previousCodexHome === undefined) delete process.env.CODEX_HOME;
+  else process.env.CODEX_HOME = previousCodexHome;
   setSystemRestartIoForTests();
   setIcaclsRunnerForTests(null);
   setPlatformForTests(null);
@@ -620,6 +636,114 @@ describe("management and data-plane credential separation", () => {
     }
   });
 
+  test("Codex backend aliases retain data-plane authentication and cannot enter management", async () => {
+    enableContextRelay();
+    saveConfig(remoteConfig());
+    const server = startServer(0);
+    try {
+      for (const token of [undefined, "admin-secret", "data-secret"]) {
+        const headers: Record<string, string> = token ? { "x-opencodex-api-key": token } : {};
+        const models = await fetch(new URL("/backend-api/codex/models", server.url), { headers });
+        expect(models.status).toBe(token === "data-secret" ? 200 : 401);
+        const context = await fetch(new URL("/backend-api/codex/alpha/notes/v2/read_file", server.url), {
+          method: "POST", headers, body: "{}",
+        });
+        expect(context.status).toBe(token === "data-secret" ? 400 : 401);
+        const management = await fetch(new URL("/backend-api/codex/api/config", server.url), { headers });
+        expect(management.status).toBe(404);
+      }
+    } finally {
+      await server.stop(true);
+    }
+  });
+
+  test("canceling an incomplete context body releases the actual listener turn", async () => {
+    enableContextRelay();
+    saveConfig(remoteConfig());
+    const server = startServer(0);
+    const baseline = getActiveTurnCount();
+    const request = httpRequest(new URL("/v1/alpha/notes/v2/write_file", server.url), {
+      method: "POST", headers: { authorization: "Bearer data-secret", "content-length": "1000" },
+    });
+    request.on("error", () => {}); // Destroying this deliberately unfinished request resets the socket.
+    const waitForCount = async (expected: number) => {
+      const deadline = Date.now() + 5000;
+      while (getActiveTurnCount() !== expected && Date.now() < deadline) {
+        await new Promise<void>(resolve => setImmediate(resolve));
+      }
+      expect(getActiveTurnCount()).toBe(expected);
+    };
+    try {
+      request.write("{"); // Never end the body: the server is waiting inside the bounded parser.
+      await waitForCount(baseline + 1);
+      request.destroy();
+      await waitForCount(baseline);
+    } finally {
+      request.destroy();
+      await server.stop(true);
+    }
+  });
+
+  test("context relay remains absent without the native experimental opt-in", async () => {
+    saveConfig(remoteConfig());
+    const server = startServer(0);
+    try {
+      const response = await fetch(new URL("/v1/alpha/notes/v2/read_file", server.url), {
+        method: "POST", headers: { authorization: "Bearer data-secret" }, body: "{}",
+      });
+      expect(response.status).toBe(404);
+    } finally {
+      await server.stop(true);
+    }
+  });
+
+  test("context bearer admission reaches body validation without accepting foreign credentials", async () => {
+    enableContextRelay();
+    saveConfig(remoteConfig());
+    const server = startServer(0);
+    try {
+      for (const prefix of ["/v1", "/backend-api/codex"]) {
+        for (const token of ["data-secret", "admin-secret", "foreign-secret"]) {
+          const response = await fetch(new URL(`${prefix}/alpha/notes/v2/read_file`, server.url), {
+            method: "POST", headers: { authorization: `Bearer ${token}` }, body: "{}",
+          });
+          expect(response.status).toBe(token === "data-secret" ? 400 : 401);
+          if (token === "data-secret") expect(await response.text()).toContain("context.session_id");
+        }
+      }
+    } finally {
+      await server.stop(true);
+    }
+  });
+
+  test("authenticated context without a successful model owner fails closed on both listener prefixes", async () => {
+    enableContextRelay();
+    const cfg = remoteConfig();
+    cfg.providers.openai = { adapter: "openai-responses", baseUrl: "https://chatgpt.com/backend-api/codex", authMode: "forward", codexAccountMode: "pool" };
+    saveConfig(cfg); clearContextSessionOwnersForTests();
+    const originalFetch = globalThis.fetch;
+    let upstreamCalls = 0;
+    globalThis.fetch = Object.assign(async (input: string | URL | Request, init?: RequestInit) => {
+      const url = new URL(input instanceof Request ? input.url : String(input));
+      if (url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]" || url.hostname === "0.0.0.0") return originalFetch(input, init);
+      upstreamCalls++; throw new Error("unknown context owner must not reach upstream");
+    }, { preconnect: originalFetch.preconnect });
+    const server = startServer(0);
+    try {
+      for (const prefix of ["/v1", "/backend-api/codex"]) {
+        const response = await fetch(new URL(`${prefix}/alpha/notes/v2/read_file`, server.url), {
+          method: "POST", headers: { authorization: "Bearer data-secret" },
+          body: JSON.stringify({ context: { session_id: "unknown-root" } }),
+        });
+        expect(response.status).toBe(409);
+        expect(await response.text()).toContain("context_account_unavailable");
+      }
+      expect(upstreamCalls).toBe(0);
+    } finally {
+      await server.stop(true); globalThis.fetch = originalFetch; clearContextSessionOwnersForTests();
+    }
+  });
+
   test("data and management environment tokens authorize only their own planes", async () => {
     saveConfig(remoteConfig());
     const server = startServer(0);
diff --git a/tests/test-layout.test.ts b/tests/test-layout.test.ts
index dff198c579..ee3ef4f05d 100644
--- a/tests/test-layout.test.ts
+++ b/tests/test-layout.test.ts
@@ -1,3 +1,4 @@
+// Holds INV-TESTS-01 from structure/overview.md; keep the id here if this file is split or renamed.
 import { describe, expect, test } from "bun:test";
 import { readdirSync, statSync } from "node:fs";
 import { join, relative, sep } from "node:path";
diff --git a/tests/update/update-job.test.ts b/tests/update/update-job.test.ts
index 9ba42b8150..d3eb621ce7 100644
--- a/tests/update/update-job.test.ts
+++ b/tests/update/update-job.test.ts
@@ -1,4 +1,6 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import type { ChildProcess } from "node:child_process";
+import { EventEmitter } from "node:events";
 import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -42,6 +44,142 @@ afterEach(() => {
   removeTreeWithRetry(dir);
 });
 
+describe("pinned-start child cleanup", () => {
+  // exitCode/signalCode are readonly on ChildProcess, but these fakes must move a child from
+  // "running" to "exited" mid-test. Redeclare them as mutable rather than widening each
+  // assignment with a cast, so the transitions stay type-checked.
+  type FakeChild = EventEmitter & Pick<ChildProcess, "pid"> & {
+    exitCode: number | null;
+    signalCode: NodeJS.Signals | null;
+  };
+
+  async function exhaustRetries(options: {
+    spawned?: (child: FakeChild) => void;
+    healthWait?: (children: FakeChild[]) => void;
+    reusePid?: boolean;
+    healthyOnLastAttempt?: boolean;
+  } = {}) {
+    let now = 0;
+    const children: FakeChild[] = [];
+    const killed: number[] = [];
+    const livenessChecks: number[] = [];
+    const job: UpdateJobState = {
+      id: "pinned-child-cleanup", status: "restarting",
+      startedAt: new Date().toISOString(), updatedAt: new Date().toISOString(),
+      currentVersion: "2.49.0", latestVersion: "2.50.0", channel: "latest",
+      installer: "npm", restart: true, command: "", releaseNotesUrl: "", log: [],
+    };
+    writeFileSync(updateJobPath(), JSON.stringify(job));
+    await restartAfterUpdateForTests(job, { port: 19111, hostname: "127.0.0.1" }, {
+      serviceInstalledFn: () => false,
+      waitForPort: async () => true,
+      listListenPidsFn: () => [],
+      preparePortForPinnedStartFn: () => {},
+      waitForGhostListenClearFn: async () => ({ ok: true, accessDenied: false }),
+      probeProxyIdentity: async () => null,
+      probeProxy: async () => !!options.healthyOnLastAttempt && children.length === 3,
+      now: () => now,
+      sleepMs: async ms => {
+        options.healthWait?.(children);
+        now += ms;
+      },
+      isAliveFn: pid => {
+        livenessChecks.push(pid);
+        // A reused numeric PID may be live even after our own child has exited.
+        return true;
+      },
+      spawnDetachedStartFn: () => {
+        const child: FakeChild = Object.assign(new EventEmitter(), {
+          pid: options.reusePid ? 4241 : 4241 + children.length, exitCode: null, signalCode: null,
+        });
+        children.push(child);
+        options.spawned?.(child);
+        return child as ChildProcess;
+      },
+      killProxyFn: pid => { killed.push(pid); },
+    });
+    expect(children).toHaveLength(3);
+    return { killed, livenessChecks };
+  }
+
+  test.each([
+    { name: "successful exit", exitCode: 0, signalCode: null },
+    { name: "failed exit", exitCode: 1, signalCode: null },
+    { name: "signal exit", exitCode: null, signalCode: "SIGTERM" as const },
+  ])("never reuses a child PID after $name", async ({ exitCode, signalCode }) => {
+    const result = await exhaustRetries({
+      spawned: child => { child.exitCode = exitCode; child.signalCode = signalCode; },
+    });
+    expect(result.killed).toEqual([]);
+    expect(result.livenessChecks).toEqual([]);
+  });
+
+  test("retires a child when its exit event is observed during the health wait", async () => {
+    const observed = new Set<FakeChild>();
+    const result = await exhaustRetries({
+      healthWait: children => {
+        const child = children.at(-1)!;
+        if (observed.has(child)) return;
+        observed.add(child);
+        // Keep the fixture fields unset to exercise the event retirement independently.
+        child.emit("exit", 0, null);
+      },
+    });
+    expect(observed.size).toBe(3);
+    expect(result.killed).toEqual([]);
+    expect(result.livenessChecks).toEqual([]);
+  });
+
+  test("still cleans up live children before retries and after the final health timeout", async () => {
+    const result = await exhaustRetries();
+    expect(result.killed).toEqual([4241, 4242, 4243]);
+    expect(result.livenessChecks).toEqual([4241, 4242, 4243]);
+  });
+
+  test.each(["exit", "error", "close"])("a previous child's late %s does not retire the current live child", async event => {
+    const observed = new Set<FakeChild>();
+    const result = await exhaustRetries({
+      reusePid: true,
+      healthWait: children => {
+        const previous = children.at(-2);
+        if (!previous || observed.has(previous)) return;
+        observed.add(previous);
+        previous.exitCode = 0;
+        if (event === "error") previous.emit(event, new Error("late spawn error"));
+        else previous.emit(event, 0, null);
+      },
+    });
+    expect(observed.size).toBe(2);
+    expect(result.killed).toEqual([4241, 4241, 4241]);
+  });
+
+  test("failed spawns retire on error and close without an exit event", async () => {
+    const observed = new Set<FakeChild>();
+    const result = await exhaustRetries({
+      spawned: child => { Object.defineProperty(child, "pid", { value: undefined }); },
+      healthWait: children => {
+        const child = children.at(-1)!;
+        if (observed.has(child)) return;
+        observed.add(child);
+        child.emit("error", new Error("spawn ENOENT"));
+        // Retirement also releases this attempt's closure; an absent-PID check alone
+        // would pass the kill assertions while keeping the exit handler installed.
+        expect(child.listenerCount("exit")).toBe(0);
+        expect(child.listenerCount("close")).toBe(0);
+        child.emit("close", -1, null);
+      },
+    });
+    expect(observed.size).toBe(3);
+    expect(result.killed).toEqual([]);
+    expect(result.livenessChecks).toEqual([]);
+  });
+
+  test("leaves the current child running when its health probe succeeds", async () => {
+    const result = await exhaustRetries({ healthyOnLastAttempt: true });
+    expect(result.killed).toEqual([4241, 4242]);
+  });
+});
+
 describe("GUI update check", () => {
   test("surfaces an npm update with the launcher-safe command", () => {
     const result = checkForUpdate("latest", {
diff --git a/tests/update/update-pnpm.test.ts b/tests/update/update-pnpm.test.ts
index aadf1ce960..f0918250b2 100644
--- a/tests/update/update-pnpm.test.ts
+++ b/tests/update/update-pnpm.test.ts
@@ -386,7 +386,22 @@ describe("pnpm package tree verification", () => {
 });
 
 describe("pnpm generated shims", () => {
-  test("verifies POSIX shims point at the active package", () => {
+  function writeHostShims(globalBinDir: string, targetPackageDir: string, commands = ["ocx", "opencodex"]): void {
+    const target = relative(globalBinDir, join(targetPackageDir, "bin", "ocx.mjs"));
+    for (const command of commands) {
+      if (process.platform === "win32") {
+        const windowsTarget = target.replaceAll("/", "\\");
+        writeFileSync(join(globalBinDir, `${command}.cmd`), `@echo off\r\nnode "%~dp0\\${windowsTarget}" %*\r\n`);
+        writeFileSync(join(globalBinDir, `${command}.ps1`),
+          `$basedir = Split-Path $MyInvocation.MyCommand.Definition -Parent\n& "$basedir\\${windowsTarget}" @args\n`);
+      } else {
+        writeFileSync(join(globalBinDir, command), `#!/bin/sh\nbasedir=$(dirname "$0")\nexec node "$basedir/${target}" "$@"\n`);
+        chmodSync(join(globalBinDir, command), 0o755);
+      }
+    }
+  }
+
+  test("verifies host-native shims point at the active package", () => {
     const root = mkdtempSync(join(tmpdir(), "ocx-pnpm-shims-"));
     try {
       const packageDir = join(root, "global", "v11", "node_modules", PKG);
@@ -394,14 +409,10 @@ describe("pnpm generated shims", () => {
       mkdirSync(join(packageDir, "bin"), { recursive: true });
       mkdirSync(globalBinDir, { recursive: true });
       writeFileSync(join(packageDir, "bin", "ocx.mjs"), "#!/usr/bin/env node\n");
-      const target = relative(globalBinDir, join(packageDir, "bin", "ocx.mjs"));
-      for (const name of ["ocx", "opencodex"]) {
-        writeFileSync(join(globalBinDir, name), `#!/bin/sh\nexec node ${target} "$@"\n`);
-        chmodSync(join(globalBinDir, name), 0o755);
-      }
-      expect(verifyPnpmGlobalShims(packageDir, globalBinDir, "linux")).toEqual({ ok: true });
-      writeFileSync(join(globalBinDir, "opencodex"), "#!/bin/sh\nexec node ../global/v11/node_modules/old/bin/ocx.mjs\n");
-      expect(verifyPnpmGlobalShims(packageDir, globalBinDir, "linux").ok).toBe(false);
+      writeHostShims(globalBinDir, packageDir);
+      expect(verifyPnpmGlobalShims(packageDir, globalBinDir)).toEqual({ ok: true });
+      writeHostShims(globalBinDir, join(root, "global", "v11", "node_modules", "old"), ["opencodex"]);
+      expect(verifyPnpmGlobalShims(packageDir, globalBinDir).ok).toBe(false);
     } finally {
       rmSync(root, { recursive: true, force: true });
     }
@@ -418,12 +429,30 @@ describe("pnpm generated shims", () => {
       mkdirSync(globalBinDir, { recursive: true });
       writeFileSync(join(packageDir, "bin", "ocx.mjs"), "#!/usr/bin/env node\n");
       symlinkSync(activeGroup, aliasGroup, "dir");
-      const target = relative(globalBinDir, join(aliasGroup, "node_modules", PKG, "bin", "ocx.mjs"));
-      for (const name of ["ocx", "opencodex"]) {
-        writeFileSync(join(globalBinDir, name), `#!/bin/sh\nexec node ${target} "$@"\n`);
-        chmodSync(join(globalBinDir, name), 0o755);
-      }
-      expect(verifyPnpmGlobalShims(packageDir, globalBinDir, "linux")).toEqual({ ok: true });
+      writeHostShims(globalBinDir, join(aliasGroup, "node_modules", PKG));
+      expect(verifyPnpmGlobalShims(packageDir, globalBinDir)).toEqual({ ok: true });
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  // Windows does not expose POSIX execute bits; target/alias coverage above still runs there.
+  test.skipIf(process.platform === "win32")("requires executable permissions on POSIX shims", () => {
+    const root = mkdtempSync(join(tmpdir(), "ocx-pnpm-posix-mode-"));
+    try {
+      const packageDir = join(root, "node_modules", PKG);
+      const globalBinDir = join(root, "bin");
+      mkdirSync(join(packageDir, "bin"), { recursive: true });
+      mkdirSync(globalBinDir, { recursive: true });
+      writeFileSync(join(packageDir, "bin", "ocx.mjs"), "#!/usr/bin/env node\n");
+      writeHostShims(globalBinDir, packageDir);
+      expect(verifyPnpmGlobalShims(packageDir, globalBinDir)).toEqual({ ok: true });
+      chmodSync(join(globalBinDir, "ocx"), 0o644);
+      expect(verifyPnpmGlobalShims(packageDir, globalBinDir)).toEqual({
+        ok: false, reason: "pnpm generated shim verification failed (ocx)",
+      });
+      chmodSync(join(globalBinDir, "ocx"), 0o755);
+      expect(verifyPnpmGlobalShims(packageDir, globalBinDir)).toEqual({ ok: true });
     } finally {
       rmSync(root, { recursive: true, force: true });
     }
diff --git a/tests/usage/quota-reset-observation.test.ts b/tests/usage/quota-reset-observation.test.ts
index 39a18025ef..fdf00708ea 100644
--- a/tests/usage/quota-reset-observation.test.ts
+++ b/tests/usage/quota-reset-observation.test.ts
@@ -5,6 +5,7 @@ import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
   clearAccountQuota,
+  getAccountQuota,
   flushQuotaObservationsForTests,
   setAccountQuotaFromParsed,
 } from "../../src/codex/quota";
@@ -55,6 +56,50 @@ afterEach(async () => {
 });
 
 describe("codex quota seam", () => {
+  test("short rollover survives repeated display eviction", async () => {
+    const start = Date.now();
+    let now = start;
+    const clock = spyOn(Date, "now").mockImplementation(() => now);
+    try {
+      setAccountQuotaFromParsed(ACCOUNT, { shortPercent: 96, shortResetAt: start + 60_000,
+        shortWindowSeconds: 18_000, weeklyPercent: 20, weeklyResetAt: start + 7 * 24 * HOUR });
+      await settle();
+      for (const percent of [21, 22]) {
+        now = start + 61_000 + (percent - 21) * 1000;
+        setAccountQuotaFromParsed(ACCOUNT, { weeklyPercent: percent });
+        await settle();
+        const quota = getAccountQuota(ACCOUNT);
+        for (const key of ["shortPercent", "shortResetAt", "shortObservedAt", "shortWindowSeconds"] as const) {
+          expect(quota?.[key]).toBeUndefined();
+        }
+        expect(captured).toEqual([]);
+      }
+      now = start + 63_000;
+      const fresh = { shortPercent: 2, shortResetAt: now + 5 * HOUR, shortWindowSeconds: 18_000 };
+      setAccountQuotaFromParsed(ACCOUNT, fresh);
+      await settle();
+      expect(captured).toHaveLength(1);
+      expect(captured[0]).toMatchObject({ kind: "scheduled", window: "5h", percentBefore: 96, percentAfter: 2 });
+      setAccountQuotaFromParsed(ACCOUNT, fresh);
+      await settle();
+      expect(captured).toHaveLength(1);
+
+      // Leave a new high baseline whose deadline then expires, making a missed clear
+      // observable as a scheduled reset rather than an ignored two-point drop.
+      setAccountQuotaFromParsed(ACCOUNT, { shortPercent: 96, shortResetAt: now + 60_000, shortWindowSeconds: 18_000 });
+      await settle();
+      now += 61_000;
+      setAccountQuotaFromParsed(ACCOUNT, { weeklyPercent: 23 });
+      await settle();
+      clearAccountQuota(ACCOUNT);
+      await settle();
+      captured = [];
+      setAccountQuotaFromParsed(ACCOUNT, { shortPercent: 0, shortResetAt: now + 6 * HOUR });
+      await settle();
+      expect(captured).toEqual([]);
+    } finally { clock.mockRestore(); }
+  });
+
   test("a weekly rollover through the real writer fires exactly one scheduled event", async () => {
     const expired = Date.now() - 60_000;
     setAccountQuotaFromParsed(ACCOUNT, { weeklyPercent: 96, weeklyResetAt: expired });
diff --git a/tests/usage/quota-reset-seen-store.test.ts b/tests/usage/quota-reset-seen-store.test.ts
index dbc7dd21de..6689c26326 100644
--- a/tests/usage/quota-reset-seen-store.test.ts
+++ b/tests/usage/quota-reset-seen-store.test.ts
@@ -7,6 +7,7 @@ import {
   claimCountForTests,
   claimQuotaReset,
   forgetLastObservedWindows,
+  flushQuotaResetStoreForTests,
   hasSeenQuotaReset,
   listRecentQuotaResetEvents,
   recordQuotaResetEvent,
@@ -39,6 +40,27 @@ beforeEach(() => {
   resetQuotaResetStoreForTests();
 });
 
+test("opted-in missing short history keeps its observation clock across persistence", () => {
+  const short = { window: "5h", percent: 96, resetAt: NOW + 60_000, observedAt: NOW };
+  const weekly = { window: "weekly", percent: 20, observedAt: NOW + 61_000 };
+  swapLastObservedWindows("codex", "retain00", [short], true);
+  swapLastObservedWindows("codex", "retain00", [weekly], true);
+  flushQuotaResetStoreForTests();
+  resetQuotaResetStoreForTests();
+  expect(swapLastObservedWindows("codex", "retain00", [weekly], true)).toContainEqual(short);
+  expect(swapLastObservedWindows("codex", "retain00", [weekly], true)).toContainEqual(short);
+  forgetLastObservedWindows("codex", "retain00");
+  expect(swapLastObservedWindows("codex", "retain00", [weekly], true)).toBeUndefined();
+});
+
+test("omitted windows are still replaced when retention is not requested", () => {
+  const short = { window: "5h", percent: 96, observedAt: NOW };
+  const weekly = { window: "weekly", percent: 20, observedAt: NOW + 61_000 };
+  swapLastObservedWindows("provider", "replace0", [short]);
+  swapLastObservedWindows("provider", "replace0", [weekly]);
+  expect(swapLastObservedWindows("provider", "replace0", [weekly])).toEqual([weekly]);
+});
+
 describe("quota reset claim store", () => {
   test("claimQuotaReset returns false when the claim is not durable", () => {
     // The caller reads true as "durably claimed, safe to dispatch". Two paths broke that.
diff --git a/tests/vision/sidecar-abort.test.ts b/tests/vision/sidecar-abort.test.ts
index 348de2a69a..9e2c35ebdf 100644
--- a/tests/vision/sidecar-abort.test.ts
+++ b/tests/vision/sidecar-abort.test.ts
@@ -161,7 +161,7 @@ describe("sidecar abort propagation", () => {
       forwardProvider,
       hostedTool: { type: "web_search" },
       selectedForwardHeaders: new Headers({ authorization: "Bearer token" }),
-      settings: { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 30_000 },
+      settings: { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 30_000 },
       maxSearches: 1,
       abortSignal: turn.signal,
     });
@@ -189,7 +189,7 @@ describe("sidecar abort propagation", () => {
       { type: "web_search" },
       forwardProvider,
       new Headers({ authorization: "Bearer token" }),
-      { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 30_000 },
+      { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 30_000 },
       turn.signal,
       value => recorded.push(value),
     );
@@ -211,7 +211,7 @@ describe("sidecar abort propagation", () => {
       { type: "web_search" },
       forwardProvider,
       new Headers({ authorization: "Bearer token" }),
-      { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 30_000 },
+      { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 30_000 },
       undefined,
       outcome => recorded.push(outcome),
     );
@@ -230,7 +230,7 @@ describe("sidecar abort propagation", () => {
       { type: "web_search" },
       forwardProvider,
       new Headers({ authorization: "Bearer token" }),
-      { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 30_000 },
+      { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 30_000 },
       lateAbort.signal,
       outcome => recorded.push(outcome),
     );
@@ -246,7 +246,7 @@ describe("sidecar abort propagation", () => {
       { type: "web_search" },
       forwardProvider,
       new Headers({ authorization: "Bearer token" }),
-      { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 30_000 },
+      { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 30_000 },
     );
     expect(outcome.error).toBe("sidecar HTTP 401: upstream echoed Bearer [REDACTED]");
   });
@@ -288,7 +288,7 @@ describe("sidecar abort propagation", () => {
       forwardProvider,
       hostedTool: { type: "web_search" },
       selectedForwardHeaders: new Headers({ authorization: "Bearer token" }),
-      settings: { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 30_000 },
+      settings: { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 30_000 },
       maxSearches: 1,
       recordSidecarOutcome: outcome => recorded.push(outcome),
     });
@@ -314,7 +314,7 @@ describe("sidecar abort propagation", () => {
       "inspect screenshot",
       forwardProvider,
       new Headers({ authorization: "Bearer token" }),
-      { model: "gpt-5.4-mini", timeoutMs: 30_000 },
+      { model: "gpt-5.6-luna", timeoutMs: 30_000 },
       turn.signal,
       value => recorded.push(value),
     );
@@ -336,7 +336,7 @@ describe("sidecar abort propagation", () => {
       { type: "web_search" },
       forwardProvider,
       new Headers({ authorization: "Bearer token" }),
-      { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 30_000 },
+      { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 30_000 },
       webTurn.signal,
       value => webRecorded.push(value),
     );
@@ -358,7 +358,7 @@ describe("sidecar abort propagation", () => {
       "inspect screenshot",
       forwardProvider,
       new Headers({ authorization: "Bearer token" }),
-      { model: "gpt-5.4-mini", timeoutMs: 30_000 },
+      { model: "gpt-5.6-luna", timeoutMs: 30_000 },
       visionTurn.signal,
       value => visionRecorded.push(value),
     );
@@ -382,7 +382,7 @@ describe("sidecar abort propagation", () => {
       { type: "web_search" },
       forwardProvider,
       new Headers({ authorization: "Bearer token" }),
-      { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 30_000 },
+      { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 30_000 },
       webTurn.signal,
       value => webRecorded.push(value),
     );
@@ -402,7 +402,7 @@ describe("sidecar abort propagation", () => {
       "inspect screenshot",
       forwardProvider,
       new Headers({ authorization: "Bearer token" }),
-      { model: "gpt-5.4-mini", timeoutMs: 30_000 },
+      { model: "gpt-5.6-luna", timeoutMs: 30_000 },
       visionTurn.signal,
       value => visionRecorded.push(value),
     );
@@ -424,7 +424,7 @@ describe("sidecar abort propagation", () => {
       "inspect screenshot",
       forwardProvider,
       new Headers({ authorization: "Bearer token" }),
-      { model: "gpt-5.4-mini", timeoutMs: 30_000 },
+      { model: "gpt-5.6-luna", timeoutMs: 30_000 },
       turn.signal,
       value => recorded.push(value),
     );
@@ -443,7 +443,7 @@ describe("sidecar abort propagation", () => {
       { type: "web_search" },
       forwardProvider,
       new Headers({ authorization: "Bearer token" }),
-      { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 30_000 },
+      { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 30_000 },
       undefined,
       value => webRecorded.push(value),
     );
@@ -458,7 +458,7 @@ describe("sidecar abort propagation", () => {
       "inspect screenshot",
       forwardProvider,
       new Headers({ authorization: "Bearer token" }),
-      { model: "gpt-5.4-mini", timeoutMs: 30_000 },
+      { model: "gpt-5.6-luna", timeoutMs: 30_000 },
       undefined,
       value => visionRecorded.push(value),
     );
@@ -476,7 +476,7 @@ describe("sidecar abort propagation", () => {
       "inspect screenshot",
       forwardProvider,
       new Headers({ authorization: "Bearer token" }),
-      { model: "gpt-5.4-mini", timeoutMs: 30_000 },
+      { model: "gpt-5.6-luna", timeoutMs: 30_000 },
       undefined,
       outcome => recorded.push(outcome),
     );
@@ -496,7 +496,7 @@ describe("sidecar abort propagation", () => {
       "inspect screenshot",
       forwardProvider,
       new Headers({ authorization: "Bearer token" }),
-      { model: "gpt-5.4-mini", timeoutMs: 30_000 },
+      { model: "gpt-5.6-luna", timeoutMs: 30_000 },
       lateAbort.signal,
       outcome => recorded.push(outcome),
     );
@@ -513,7 +513,7 @@ describe("sidecar abort propagation", () => {
       { type: "web_search" },
       forwardProvider,
       new Headers({ authorization: "Bearer token" }),
-      { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 1 },
+      { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 1 },
       undefined,
       outcome => webRecorded.push(outcome),
     );
@@ -528,7 +528,7 @@ describe("sidecar abort propagation", () => {
       "inspect screenshot",
       forwardProvider,
       new Headers({ authorization: "Bearer token" }),
-      { model: "gpt-5.4-mini", timeoutMs: 1 },
+      { model: "gpt-5.6-luna", timeoutMs: 1 },
       undefined,
       outcome => visionRecorded.push(outcome),
     );
@@ -544,7 +544,7 @@ describe("sidecar abort propagation", () => {
       "inspect screenshot",
       forwardProvider,
       new Headers({ authorization: "Bearer token" }),
-      { model: "gpt-5.4-mini", timeoutMs: 30_000 },
+      { model: "gpt-5.6-luna", timeoutMs: 30_000 },
     );
     expect(outcome.error).toBe("vision sidecar HTTP 403: upstream echoed Bearer [REDACTED]");
   });
@@ -568,7 +568,7 @@ describe("sidecar abort propagation", () => {
       { type: "web_search" },
       forwardProvider,
       selectedHeaders,
-      { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 30_000 },
+      { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 30_000 },
     );
 
     expect(seenAuthorization).toBe("Bearer pool-token");
@@ -595,7 +595,7 @@ describe("sidecar abort propagation", () => {
       "inspect screenshot",
       forwardProvider,
       selectedHeaders,
-      { model: "gpt-5.4-mini", timeoutMs: 30_000 },
+      { model: "gpt-5.6-luna", timeoutMs: 30_000 },
     );
 
     expect(seenAuthorization).toBe("Bearer pool-token");
diff --git a/tests/vision/sidecar-settings-vision-controls.test.ts b/tests/vision/sidecar-settings-vision-controls.test.ts
index a57b646f78..1ac5670d06 100644
--- a/tests/vision/sidecar-settings-vision-controls.test.ts
+++ b/tests/vision/sidecar-settings-vision-controls.test.ts
@@ -86,7 +86,7 @@ describe("sidecar-settings remaining vision controls", () => {
     expect(unset.status).toBe(200);
     expect((await unset.json() as { vision: Record<string, unknown> }).vision).toMatchObject({
       enabled: true,
-      model: "gpt-5.4-mini",
+      model: "gpt-5.6-luna",
       reasoning: "low",
       maxDescriptionsPerTurn: resolveMaxDescriptionsPerTurn(undefined),
       timeoutMs: DEFAULT_VISION_TIMEOUT_MS,
diff --git a/tests/vision/sidecar-settings-vision-filter.test.ts b/tests/vision/sidecar-settings-vision-filter.test.ts
index 0582f0cff0..948ab49585 100644
--- a/tests/vision/sidecar-settings-vision-filter.test.ts
+++ b/tests/vision/sidecar-settings-vision-filter.test.ts
@@ -134,7 +134,7 @@ describe("sidecar-settings vision model filter", () => {
     const body = await response.json() as { vision: { model: string } };
     // Empty string clears the override; the effective reported model is the fallback.
     expect(config.visionSidecar?.model).toBeUndefined();
-    expect(body.vision.model).toBe("gpt-5.4-mini");
+    expect(body.vision.model).toBe("gpt-5.6-luna");
   });
 
   test("6. catalog failure degrades to baselines", async () => {
@@ -186,7 +186,7 @@ describe("sidecar-settings vision model filter", () => {
   test("9. GET reports the effective Anthropic default for an explicitly selected backend", async () => {
     // Reports what the runtime WOULD use for this backend. No OAuth account is set up
     // here, so no plan would run; the point is that the projection stops answering
-    // gpt-5.4-mini for a configuration the OpenAI describer does not own.
+    // gpt-5.6-luna for a configuration the OpenAI describer does not own.
     const config = emptyConfig({ visionSidecar: { backend: "anthropic" } });
     const response = await getSidecarSettings(config);
     expect(response.status).toBe(200);
diff --git a/tests/vision/vision-anthropic.test.ts b/tests/vision/vision-anthropic.test.ts
index f956cf6a4d..a42a238db9 100644
--- a/tests/vision/vision-anthropic.test.ts
+++ b/tests/vision/vision-anthropic.test.ts
@@ -416,7 +416,7 @@ describe("Anthropic vision planning and management config", () => {
       expect(clearBody.webSearch).toEqual({ enabled: true, model: "gpt-5.6-luna", streamRoutedModelOutput: false });
       expect(clearBody.vision).toEqual({
         enabled: true,
-        model: "gpt-5.4-mini",
+        model: "gpt-5.6-luna",
         reasoning: "low",
         maxDescriptionsPerTurn: 4,
         timeoutMs: 45_000,
diff --git a/tests/vision/vision-cache.test.ts b/tests/vision/vision-cache.test.ts
index bb6323425d..6e482d4255 100644
--- a/tests/vision/vision-cache.test.ts
+++ b/tests/vision/vision-cache.test.ts
@@ -17,6 +17,7 @@ import {
   setVisionDescriptionCache,
   setVisionDescriptionCacheLimitsForTests,
   shouldResolveOpenAiVisionSidecar,
+  planVisionSidecar,
   visionDescriptionRetainedStoreSnapshot,
   type VisionPlan,
 } from "../../src/vision";
@@ -75,6 +76,20 @@ test("vision sidecar auth stays lazy for no-image and disabled branches", () =>
   expect(shouldResolveOpenAiVisionSidecar(cfg, textOnlyProvider, "text-model", withImage)).toBe(true);
 });
 
+test("vision auth and planning agree on a routed describer and its legacy fallback", () => {
+  const cfg: OcxConfig = { port: 10100, defaultProvider: "routed", providers: {
+    routed: textOnlyProvider, sighted: { adapter: "openai-chat", baseUrl: "https://vision.test/v1", apiKey: "vision-key" },
+  }, visionSidecar: { enabled: true, backend: "routed", model: "sighted/vision-model" } };
+  const request = parseRequest({ model: "routed/text-model",
+    input: [{ type: "message", role: "user", content: [{ type: "input_image", image_url: DATA_A }] }],
+  });
+  expect(planVisionSidecar(cfg, textOnlyProvider, "text-model", request)?.backend).toBe("routed");
+  expect(shouldResolveOpenAiVisionSidecar(cfg, textOnlyProvider, "text-model", request)).toBe(false);
+  cfg.visionSidecar!.model = "legacy-bare-model";
+  expect(shouldResolveOpenAiVisionSidecar(cfg, textOnlyProvider, "text-model", request)).toBe(true);
+  expect(planVisionSidecar(cfg, textOnlyProvider, "text-model", request, plan().forwardSidecar)?.backend).toBe("openai");
+});
+
 function parsed(parts: Array<Record<string, unknown>>) {
   return parseRequest({
     model: "routed/blind",
diff --git a/tests/vision/vision-eligibility.test.ts b/tests/vision/vision-eligibility.test.ts
index 2344fc4d69..25fdc63d42 100644
--- a/tests/vision/vision-eligibility.test.ts
+++ b/tests/vision/vision-eligibility.test.ts
@@ -222,7 +222,7 @@ describe("vision eligibility core", () => {
   test("14. a non-native row's explicit text-only modality wins over a colliding native slug", () => {
     expect(modelAcceptsImageInput(emptyConfig, {
       provider: "custom-openai-compatible",
-      id: "gpt-5.4-mini",
+      id: "gpt-5.6-luna",
       inputModalities: ["text"],
     })).toBe(false);
   });
diff --git a/tests/vision/vision-reasoning-contract.test.ts b/tests/vision/vision-reasoning-contract.test.ts
index 38d8378996..b55a4008b4 100644
--- a/tests/vision/vision-reasoning-contract.test.ts
+++ b/tests/vision/vision-reasoning-contract.test.ts
@@ -68,7 +68,7 @@ describe("vision reasoning capability contracts", () => {
       | { reasoningEfforts?: string[] }
       | undefined)?.reasoningEfforts;
 
-    expect(efforts("gpt-5.4-mini")).toEqual(["low", "medium", "high", "xhigh"]);
+    expect(efforts("gpt-5.5")).toEqual(["low", "medium", "high", "xhigh"]);
     expect(efforts("gpt-5.6-luna")).toEqual(["low", "medium", "high", "xhigh", "max"]);
     expect(efforts("gpt-5.6-sol")).toEqual(["low", "medium", "high", "xhigh", "max"]);
     expect(efforts("gpt-5.6-sol")).not.toContain("ultra");
@@ -85,7 +85,7 @@ describe("vision reasoning capability contracts", () => {
       const response = await getVision(config);
       expect(response.status).toBe(200);
       expect(await response.json()).toMatchObject({
-        vision: { model: "gpt-5.4-mini", reasoning: "xhigh" },
+        vision: { model: "gpt-5.6-luna", reasoning: "max" },
       });
       // Reads report effective execution state without mutating a hand-edited config in memory.
       expect(config.visionSidecar?.reasoning).toBe("max");
@@ -99,10 +99,10 @@ describe("vision reasoning capability contracts", () => {
 
     try {
       const direct = { port: 10100, defaultProvider: "none", providers: {} } as OcxConfig;
-      let response = await putVision(direct, { model: "gpt-5.4-mini", reasoning: "max" });
+      let response = await putVision(direct, { model: "gpt-5.5", reasoning: "max" });
       expect(response.status).toBe(200);
       expect(await response.json()).toMatchObject({
-        vision: { model: "gpt-5.4-mini", reasoning: "xhigh" },
+        vision: { model: "gpt-5.5", reasoning: "xhigh" },
       });
       expect(direct.visionSidecar?.reasoning).toBe("xhigh");
 
@@ -110,7 +110,7 @@ describe("vision reasoning capability contracts", () => {
         port: 10100,
         defaultProvider: "none",
         providers: {},
-        visionSidecar: { model: "gpt-5.4-mini", reasoning: "low" },
+        visionSidecar: { model: "gpt-5.5", reasoning: "low" },
       } as OcxConfig;
       response = await putVision(reasoningOnly, { reasoning: "max" });
       expect(response.status).toBe(200);
@@ -125,10 +125,10 @@ describe("vision reasoning capability contracts", () => {
       response = await putVision(unsetModel, { reasoning: "max" });
       expect(response.status).toBe(200);
       expect(await response.json()).toMatchObject({
-        vision: { model: "gpt-5.4-mini", reasoning: "xhigh" },
+        vision: { model: "gpt-5.6-luna", reasoning: "max" },
       });
       expect(unsetModel.visionSidecar?.model).toBeUndefined();
-      expect(unsetModel.visionSidecar?.reasoning).toBe("xhigh");
+      expect(unsetModel.visionSidecar?.reasoning).toBe("max");
 
       const modelOnly = {
         port: 10100,
@@ -136,23 +136,23 @@ describe("vision reasoning capability contracts", () => {
         providers: {},
         visionSidecar: { model: "gpt-5.6-luna", reasoning: "max" },
       } as OcxConfig;
-      response = await putVision(modelOnly, { model: "gpt-5.4-mini" });
+      response = await putVision(modelOnly, { model: "gpt-5.5" });
       expect(response.status).toBe(200);
-      expect(modelOnly.visionSidecar).toMatchObject({ model: "gpt-5.4-mini", reasoning: "xhigh" });
+      expect(modelOnly.visionSidecar).toMatchObject({ model: "gpt-5.5", reasoning: "xhigh" });
 
       const reset = {
         port: 10100,
         defaultProvider: "none",
         providers: {},
-        visionSidecar: { model: "gpt-5.4-mini", reasoning: "max" },
+        visionSidecar: { model: "gpt-5.5", reasoning: "max" },
       } as OcxConfig;
       response = await putVision(reset, { model: "" });
       expect(response.status).toBe(200);
       expect(await response.json()).toMatchObject({
-        vision: { model: "gpt-5.4-mini", reasoning: "xhigh" },
+        vision: { model: "gpt-5.6-luna", reasoning: "max" },
       });
       expect(reset.visionSidecar?.model).toBeUndefined();
-      expect(reset.visionSidecar?.reasoning).toBe("xhigh");
+      expect(reset.visionSidecar?.reasoning).toBe("max");
 
       const custom = { port: 10100, defaultProvider: "none", providers: {} } as OcxConfig;
       response = await putVision(custom, { model: "custom-vision", reasoning: "max" });
@@ -175,14 +175,14 @@ describe("vision reasoning capability contracts", () => {
       writeFileSync(importPath, JSON.stringify(validCliConfig({ reasoning: "max" })));
       expect(await handleConfigCommand(["import", importPath, "--yes", "--json"])).toBe(0);
       let persisted = JSON.parse(readFileSync(join(isolatedHome, "config.json"), "utf8"));
-      expect(persisted.visionSidecar).toMatchObject({ reasoning: "xhigh" });
+      expect(persisted.visionSidecar).toMatchObject({ reasoning: "max" });
       expect(persisted.visionSidecar.model).toBeUndefined();
 
       writeFileSync(importPath, JSON.stringify(validCliConfig({ model: "", reasoning: "max" })));
       expect(await handleConfigCommand(["import", importPath, "--yes", "--json"])).toBe(0);
       persisted = JSON.parse(readFileSync(join(isolatedHome, "config.json"), "utf8"));
-      expect(persisted.visionSidecar).toMatchObject({ model: "", reasoning: "xhigh" });
-      expect(resolveOpenAiVisionModel({ visionSidecar: persisted.visionSidecar })).toBe("gpt-5.4-mini");
+      expect(persisted.visionSidecar).toMatchObject({ model: "", reasoning: "max" });
+      expect(resolveOpenAiVisionModel({ visionSidecar: persisted.visionSidecar })).toBe("gpt-5.6-luna");
     } finally {
       if (previousHome === undefined) delete process.env.OPENCODEX_HOME;
       else process.env.OPENCODEX_HOME = previousHome;
@@ -198,18 +198,18 @@ describe("vision reasoning capability contracts", () => {
       port: 10100,
       defaultProvider: "none",
       providers: {},
-      visionSidecar: { model: "gpt-5.4-mini", reasoning: "high", maxDescriptionsPerTurn: 8 },
+      visionSidecar: { model: "gpt-5.6-luna", reasoning: "high", maxDescriptionsPerTurn: 8 },
     } as OcxConfig;
 
     try {
       let response = await putVision(config, { reasoning: "ultra" });
       expect(response.status).toBe(400);
-      expect(config.visionSidecar).toMatchObject({ model: "gpt-5.4-mini", reasoning: "high" });
+      expect(config.visionSidecar).toMatchObject({ model: "gpt-5.6-luna", reasoning: "high" });
 
       response = await putVision(config, { maxDescriptionsPerTurn: 4 });
       expect(response.status).toBe(200);
       expect(config.visionSidecar).toMatchObject({
-        model: "gpt-5.4-mini",
+        model: "gpt-5.6-luna",
         reasoning: "high",
         maxDescriptionsPerTurn: 4,
       });
diff --git a/tests/web-search/web-search.test.ts b/tests/web-search/web-search.test.ts
index c116743d86..e182308a0d 100644
--- a/tests/web-search/web-search.test.ts
+++ b/tests/web-search/web-search.test.ts
@@ -304,6 +304,18 @@ describe("web-search sidecar planning", () => {
     expect(shouldResolveOpenAiWebSearchSidecar(config(), parsed, false)).toBe(true);
   });
 
+  test("a forbidden hosted search does not resolve OpenAI auth", () => {
+    for (const toolChoice of ["none", { type: "function", name: "read_file" }]) {
+      const parsed = parseRequest({ model: "routed/model", input: "hi",
+        tools: [{ type: "web_search" }, { type: "function", name: "read_file", parameters: { type: "object" } }],
+        tool_choice: toolChoice,
+      });
+      expect(parsed._webSearch).toBeDefined();
+      expect(shouldResolveOpenAiWebSearchSidecar(config(), parsed, false)).toBe(false);
+      expect(planWebSearch(config(), parsed, false, routedProvider, "model")).toBeUndefined();
+    }
+  });
+
   test("parseRequest stashes hosted web_search while keeping normal tools", () => {
     const parsed = parsedWithWebSearch();
 
@@ -952,7 +964,7 @@ describe("web-search sidecar native web_search_call emission", () => {
       forwardProvider,
       hostedTool: { type: "web_search" },
       selectedForwardHeaders: new Headers({ authorization: "Bearer token" }),
-      settings: { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 30_000 },
+      settings: { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 30_000 },
       maxSearches: 1,
       onRequestBuilt: request => reasoningLogs.push(request.reasoningLog),
       on429: async retryAfter => {
@@ -1023,7 +1035,7 @@ describe("web-search sidecar native web_search_call emission", () => {
       forwardProvider,
       hostedTool: { type: "web_search" },
       selectedForwardHeaders: new Headers({ authorization: "Bearer token" }),
-      settings: { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 30_000 },
+      settings: { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 30_000 },
       maxSearches: 1,
       retryOn429Policy: { enabled: true, attempts: 2, intervalMs: 120, maxIntervalMs: 60_000, respectRetryAfter: false },
       on429: () => {
@@ -1076,7 +1088,7 @@ describe("web-search sidecar native web_search_call emission", () => {
       forwardProvider,
       hostedTool: { type: "web_search" },
       selectedForwardHeaders: new Headers({ authorization: "Bearer token" }),
-      settings: { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 30_000 },
+      settings: { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 30_000 },
       maxSearches: 1,
       stallTimeoutSec: 1,
       retryOn429Policy: { enabled: true, attempts: 1, intervalMs: 1_500, maxIntervalMs: 60_000, respectRetryAfter: false },
@@ -1118,7 +1130,7 @@ describe("web-search sidecar native web_search_call emission", () => {
       forwardProvider,
       hostedTool: { type: "web_search" },
       selectedForwardHeaders: new Headers({ authorization: "Bearer token" }),
-      settings: { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 30_000 },
+      settings: { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 30_000 },
       maxSearches: 1,
       connectTimeoutMs: 100,
       retryOn429Policy: { enabled: true, attempts: 1, intervalMs: 150, maxIntervalMs: 60_000, respectRetryAfter: false },
@@ -1175,7 +1187,7 @@ describe("web-search sidecar native web_search_call emission", () => {
       forwardProvider,
       hostedTool: { type: "web_search" },
       selectedForwardHeaders: new Headers({ authorization: "Bearer token" }),
-      settings: { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 30_000 },
+      settings: { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 30_000 },
       maxSearches: 1,
       retryOn429Policy: { enabled: true, attempts: 1, intervalMs: 50, maxIntervalMs: 60_000, respectRetryAfter: false },
       on429: () => {
@@ -1208,7 +1220,7 @@ describe("web-search sidecar native web_search_call emission", () => {
       forwardProvider,
       hostedTool: { type: "web_search" },
       selectedForwardHeaders: new Headers({ authorization: "Bearer token" }),
-      settings: { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 30_000 },
+      settings: { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 30_000 },
       maxSearches: 1,
       on429: () => null,
     });
@@ -1231,7 +1243,7 @@ describe("web-search sidecar native web_search_call emission", () => {
       forwardProvider,
       hostedTool: { type: "web_search" },
       selectedForwardHeaders: new Headers({ authorization: "Bearer token" }),
-      settings: { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 30_000 },
+      settings: { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 30_000 },
       maxSearches: 1,
       connectTimeoutMs: 100,
     });
@@ -1269,7 +1281,7 @@ describe("web-search sidecar native web_search_call emission", () => {
       forwardProvider,
       hostedTool: { type: "web_search" },
       selectedForwardHeaders: new Headers({ authorization: "Bearer token" }),
-      settings: { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 30_000 },
+      settings: { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 30_000 },
       maxSearches: 1,
       connectTimeoutMs: 100,
       on429: () => rotatedAdapter,
@@ -1300,7 +1312,7 @@ describe("web-search sidecar native web_search_call emission", () => {
       forwardProvider,
       hostedTool: { type: "web_search" },
       selectedForwardHeaders: new Headers({ authorization: "Bearer token" }),
-      settings: { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 30_000 },
+      settings: { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 30_000 },
       maxSearches: 1,
       connectTimeoutMs: 30_000,
       abortSignal: parent.signal,
@@ -1372,7 +1384,7 @@ describe("web-search sidecar native web_search_call emission", () => {
       forwardProvider,
       hostedTool: { type: "web_search" },
       selectedForwardHeaders: new Headers({ authorization: "Bearer token" }),
-      settings: { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 30_000 },
+      settings: { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 30_000 },
       maxSearches: 2,
     });
     await collectSse(response.body!);
@@ -1437,7 +1449,7 @@ describe("web-search sidecar native web_search_call emission", () => {
       forwardProvider,
       hostedTool: { type: "web_search" },
       selectedForwardHeaders: new Headers({ authorization: "Bearer token" }),
-      settings: { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 30_000 },
+      settings: { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 30_000 },
       maxSearches: 2,
     });
     await collectSse(response.body!);
@@ -1507,7 +1519,7 @@ describe("web-search sidecar native web_search_call emission", () => {
       forwardProvider,
       hostedTool: { type: "web_search" },
       selectedForwardHeaders: new Headers({ authorization: "Bearer token" }),
-      settings: { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 30_000 },
+      settings: { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 30_000 },
       maxSearches: 2,
     });
     await collectSse(response.body!);
@@ -1581,7 +1593,7 @@ describe("web-search sidecar native web_search_call emission", () => {
       forwardProvider,
       hostedTool: { type: "web_search" },
       selectedForwardHeaders: new Headers({ authorization: "Bearer token" }),
-      settings: { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 30_000 },
+      settings: { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 30_000 },
       maxSearches: 2,
     });
     await collectSse(response.body!);
@@ -1620,7 +1632,7 @@ describe("web-search sidecar native web_search_call emission", () => {
       forwardProvider,
       hostedTool: { type: "web_search" },
       selectedForwardHeaders: new Headers({ authorization: "Bearer token" }),
-      settings: { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 30_000 },
+      settings: { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 30_000 },
       maxSearches: 1,
     });
 
@@ -1652,7 +1664,7 @@ describe("web-search sidecar native web_search_call emission", () => {
       forwardProvider,
       hostedTool: { type: "web_search" },
       selectedForwardHeaders: new Headers({ authorization: "Bearer token" }),
-      settings: { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 30_000 },
+      settings: { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 30_000 },
       maxSearches: 1,
     });
 
@@ -1725,7 +1737,7 @@ describe("web-search forced-answer nudge", () => {
       forwardProvider,
       hostedTool: { type: "web_search" },
       selectedForwardHeaders: new Headers({ authorization: "Bearer token" }),
-      settings: { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 30_000 },
+      settings: { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 30_000 },
       maxSearches: 1,
     });
     // Iteration 2 (the forced-answer pass) runs live inside the SSE body — drain it so it executes.
@@ -1764,7 +1776,7 @@ describe("web-search forced-answer nudge", () => {
       forwardProvider,
       hostedTool: { type: "web_search" },
       selectedForwardHeaders: new Headers({ authorization: "Bearer token" }),
-      settings: { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 30_000 },
+      settings: { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 30_000 },
       maxSearches: 1,
     });
     await drain(response.body!);
@@ -1804,7 +1816,7 @@ describe("web-search live spinner ordering", () => {
       forwardProvider,
       hostedTool: { type: "web_search" },
       selectedForwardHeaders: new Headers({ authorization: "Bearer token" }),
-      settings: { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 30_000 },
+      settings: { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 30_000 },
       maxSearches: 1,
     });
 
@@ -1881,7 +1893,7 @@ describe("web-search batched queries", () => {
       forwardProvider,
       hostedTool: { type: "web_search" },
       selectedForwardHeaders: new Headers({ authorization: "Bearer token" }),
-      settings: { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 30_000 },
+      settings: { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 30_000 },
       maxSearches: 3,
     });
 
@@ -1935,7 +1947,7 @@ describe("web-search sources -> url_citation annotations", () => {
       forwardProvider,
       hostedTool: { type: "web_search" },
       selectedForwardHeaders: new Headers({ authorization: "Bearer token" }),
-      settings: { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 30_000 },
+      settings: { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 30_000 },
       maxSearches: 1,
     });
 
@@ -1978,7 +1990,7 @@ describe("web-search sources -> url_citation annotations", () => {
       forwardProvider,
       hostedTool: { type: "web_search" },
       selectedForwardHeaders: new Headers({ authorization: "Bearer token" }),
-      settings: { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 30_000 },
+      settings: { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 30_000 },
       maxSearches: 1,
     });
 
@@ -2005,7 +2017,7 @@ describe("web-search sources -> url_citation annotations", () => {
       forwardProvider,
       hostedTool: { type: "web_search" },
       selectedForwardHeaders: new Headers({ authorization: "Bearer token" }),
-      settings: { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 30_000 },
+      settings: { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 30_000 },
       maxSearches: 1,
     });
     const frames = await collectSse(response.body!);
@@ -2048,7 +2060,7 @@ describe("web-search batched sources -> url_citation annotations", () => {
       forwardProvider,
       hostedTool: { type: "web_search" },
       selectedForwardHeaders: new Headers({ authorization: "Bearer token" }),
-      settings: { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 30_000 },
+      settings: { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 30_000 },
       maxSearches: 3,
     });
 
@@ -2094,7 +2106,7 @@ describe("web-search batched sources -> url_citation annotations", () => {
       forwardProvider,
       hostedTool: { type: "web_search" },
       selectedForwardHeaders: new Headers({ authorization: "Bearer token" }),
-      settings: { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 30_000 },
+      settings: { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 30_000 },
       maxSearches: 3,
     });
 
@@ -2172,7 +2184,7 @@ describe("web-search stall deadline", () => {
       forwardProvider,
       hostedTool: { type: "web_search" },
       selectedForwardHeaders: new Headers({ authorization: "Bearer token" }),
-      settings: { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 600_000 },
+      settings: { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 600_000 },
       maxSearches: 1,
       // Bridge clamps to >= 1s and checks on its 2s tick: the hung search dies on the first
       // silent tick (~4s), proving deps.stallTimeoutSec actually reaches bridgeToResponsesSSE.
@@ -2207,7 +2219,7 @@ describe("#398 sidecar failure degradation", () => {
       forwardProvider,
       hostedTool: { type: "web_search" },
       selectedForwardHeaders: new Headers({ authorization: "Bearer token" }),
-      settings: { model: "gpt-5.4-mini", reasoning: "low", timeoutMs: 30_000 },
+      settings: { model: "gpt-5.6-luna", reasoning: "low", timeoutMs: 30_000 },
       maxSearches: 1,
     });
 
diff --git a/tests/windows/windows-deploy-close-regressions.test.ts b/tests/windows/windows-deploy-close-regressions.test.ts
index e3bae4fc0b..d9f80c8d19 100644
--- a/tests/windows/windows-deploy-close-regressions.test.ts
+++ b/tests/windows/windows-deploy-close-regressions.test.ts
@@ -59,7 +59,8 @@ describe("update-job restart avoids the shell-less .cmd EINVAL (Windows, bun/sou
     // matching rules themselves are covered by windows-service-wrappers.test.ts.
     expect(src).toContain("killWindowsSchedulerWrappers");
     expect(read("src/lib/windows-service-wrappers.ts")).toContain("$_.ProcessId -eq $PID");
-    expect(src).toContain("lastChild?.pid && aliveFn(lastChild.pid)");
+    // Pinned-child cleanup is exercised through the retry loop in update/update-job.test.ts,
+    // including exited children, live retry/final cleanup, and successful health probes.
   });
 });